首页 / Skills / 开发提效 / Markdown 与 Mermaid 写作
开发提效

Markdown 与 Mermaid 写作

Clayton Young / Superior Byte WorksApache-2.0Skill 语言: 英文
协议已核对不含脚本中风险
演示真实运行记录 · claude-sonnet-5-5 · 2026年10月
I'm documenting a small data pipeline for my team's repo README. Every night a scheduler triggers an ingest job that pulls CSV files from an SFTP server, a validation step checks the schema and moves bad files to a quarantine folder, good files are loaded into a staging table, then a transform job builds the reporting tables, and finally a Slack message is sent. Please write the README section "How the nightly pipeline works": a short intro, a diagram of the flow, and a sequence diagram showing the interaction between the scheduler, the ingest job, the SFTP server, the database and Slack. Our README is viewed on GitHub.
Skill: markdown-mermaid-writing
Read: references/mermaid_style_guide.md
Read: references/diagrams/sequence.md

Here's the section, ready to paste into your README. Both diagrams use standard Mermaid, which GitHub renders natively in light and dark mode.

## How the nightly pipeline works

Every night a scheduler triggers an ingest job. The job pulls CSV files from an SFTP server and checks each file's schema. Files that fail go to a quarantine folder, and files that pass are loaded into a staging table. A transform job then builds the reporting tables from staging, and a Slack message is sent at the end of the run.

### Pipeline flow

```mermaid
flowchart LR
    accTitle: Nightly Pipeline Flow
    accDescr: A scheduler triggers ingest from SFTP. Each CSV is validated. Bad files go to quarantine, good files load into staging, then the transform builds reporting tables and Slack is notified.

    schedule([⏰ Nightly trigger]) --> ingest[📥 Pull CSVs from SFTP]
    ingest --> validate{🔍 Schema valid?}
    validate -->|No| quarantine[🗂️ Move to quarantine]
    validate -->|Yes| staging[💾 Load into staging table]
    staging --> transform[⚙️ Build reporting tables]
    transform --> notify([📤 Send Slack message])
    quarantine --> notify

    classDef good fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef bad fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d

    class staging,transform good
    class quarantine bad
```

### Interaction between components

```mermaid
sequenceDiagram
    accTitle: Nightly Pipeline Sequence
    accDescr: The scheduler starts the ingest job, which downloads files from SFTP, validates each one, quarantines bad files or loads good ones into the database, runs the transform, and posts a summary to Slack.

    participant sched as ⏰ Scheduler
    participant ingest as 📥 Ingest job
    participant sftp as 🖥️ SFTP server
    participant db as 💾 Database
    participant slack as 📤 Slack

    sched->>ingest: Trigger nightly run
    ingest->>sftp: List and download CSV files
    sftp-->>ingest: CSV files

    loop 🔄 Each file
        ingest->>ingest: 🔍 Validate schema
        alt ✅ Schema valid
            ingest->>db: Load into staging table
            db-->>ingest: Rows loaded
        else ❌ Schema invalid
            ingest->>ingest: 🗂️ Move to quarantine folder
        end
    end

    ingest->>db: Run transform (build reporting tables)
    db-->>ingest: Reporting tables updated

    ingest->>slack: 📤 Post run summary
    slack-->>ingest: Message accepted
```

A few details are my assumptions, so please check them against your setup:

  • Who runs what: You didn't say which component runs validation and the transform. I showed the ingest job doing validation and loading, then triggering the transform in the database. If the transform is a separate job, add it as a sixth participant between the database and Slack.
  • Failures: The Slack message is sent after both good and bad files, as in the flow diagram. If it should only fire on success, or should list the quarantined files, say so and I'll adjust both diagrams.
  • Quarantine location: I didn't say whether the folder is on the SFTP server or local storage. Name it in the intro if readers will need to find it.

I couldn't render the diagrams here, but they follow standard Mermaid syntax. You can paste them into mermaid.live, or preview the README on GitHub, to confirm they display.

Real run in an isolated folder with only this skill installed. Only the Skill and Read tools were enabled, so no command was run and no file was written. The scenario is fictional. The diagrams were not rendered in this run: check them in a Mermaid-aware preview such as GitHub or mermaid.live before publishing.

它做什么

提供一套可选的**“Markdown 文档 + Mermaid 图”**写作风格,让结构保存在可编辑、便于比对的文本里,而不是截图里。它帮你选对图的类型(流程图、时序图、ER 图、状态图、甘特图、C4、时间线、思维导图等),再指向对应类型的指南,里面有测试过的示例和可直接复制的模板。它会加上 accTitle 和 accDescr 无障碍元数据,每个节点最多一个表情符号,并提醒你检查文档将来展示的地方用的是哪个版本的 Mermaid。

附带的参考资料

Markdown 样式指南、Mermaid 样式指南、关于当前 Mermaid 渲染和命令行导出的说明、21 份图类型指南,以及 6 个文档模板(决策记录、操作指南、演示文稿、项目文档、研究论文、状态报告)。

适合什么场景

README、设计文档、方法说明和报告,凡是希望工作流、数据模型或时间线保持为可编辑文本的地方。

说明与风险

中风险:它会写入和编辑 Markdown 文件,没有脚本。可选的图表导出会用 npm 安装 Mermaid 命令行工具和 Chromium 浏览器,需要联网。不同平台(比如 GitHub)的 Mermaid 版本不一样,请在发布的地方确认图能正常渲染;试用中的图没有渲染过。它的样式约定(二级标题加表情符号、只有一个 H1)是可选的:请先遵循你自己项目的风格。这份副本做过精简:为了符合大小限制删去了 40 个文件中的 6 个,并已在 SKILL.md 里注明。Clayton Young 和 Superior Byte Works 的 Apache-2.0 作品,K-Dense 以 MIT 协议做了集成;随附两份协议文件。