跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 design-doc-mermaid

Design Doc Mermaid

从文本或源代码创建人鱼图(流程图,序列,类,ER,状态,C4架构). GitHub 维基默认值 。 当被请求创建图表,生成人鱼,文档架构,或将代码转换为图表时使用. PlantUML只用于剩余类型. 聚合需要巴布亚新几内亚/巴布亚新几内亚以及围栏.

105284 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

从文本或源代码创建人鱼图(流程图,序列,类,ER,状态,C4架构). GitHub 维基默认值

何时用

什么? (# 当 - 使用 - 什么)

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Mermaid Architect - Hierarchical Diagram and Documentation Skill、Table of Contents、Decision Tree、Available Guides and Resources、Diagram Type Guides (`references/guides/diagrams/`)、Code-to-Diagram Guide & Examples。 其中含规范建议的小节:分步指令、输入输出示例。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/guides/diagrams/activity-diagrams.md、references/guides/diagrams/deployment-diagrams.md、references/guides/diagrams/architecture-diagrams.md、references/guides/diagrams/sequence-diagrams.md、references/guides/wiki-ticket-and-github.md、references/guides/code-to-diagram/,属于带资源的技能包,这些文件按需再读。 正文约 514 行,超过规范建议的 500 行,激活时仍会整份载入。

官方 description(原文)

Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.

Mermaid Architect - Hierarchical Diagram and Documentation SkillTable of ContentsDecision TreeAvailable Guides and ResourcesDiagram Type Guides (`references/guides/diagrams/`)Code-to-Diagram Guide & ExamplesDesign Document TemplatesUnicode Symbols GuidePython Scripts (`scripts/`)GitHub wiki, WikiTicket, and ConfluenceUsage PatternsResilient Workflow

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
design-doc-mermaid
description
Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 10
  • references/guides/diagrams/activity-diagrams.md
  • references/guides/diagrams/deployment-diagrams.md
  • references/guides/diagrams/architecture-diagrams.md
  • references/guides/diagrams/sequence-diagrams.md
  • references/guides/wiki-ticket-and-github.md
  • references/guides/code-to-diagram/
  • references/guides/unicode-symbols/guide.md
  • scripts/extract_mermaid.py
  • scripts/mermaid_to_image.py
  • references/guides/diagrams/

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「design-doc-mermaid」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-c42e08792e25c342-%E8%AE%BE%E8%AE%A1-%E7%BE%8E%E4%BA%BA%E9%B1%BC.html
请存为 .cursor/skills/design-doc-mermaid/SKILL.md 或 .claude/skills/design-doc-mermaid/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/spillwavesolutions/design-doc-mermaid 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/spillwavesolutions/design-doc-mermaid' --list

npx skills add 'https://github.com/spillwavesolutions/design-doc-mermaid' --skill 'design-doc-mermaid'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: design-doc-mermaid description: Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence. --- # Mermaid Architect - Hierarchical Diagram and Documentation Skill Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities. ## Table of Contents - [Decision Tree](#decision-tree) - [GitHub wiki, WikiTicket, and Confluence](#github-wiki-wikiticket-and-confluence) - [Available Guides and Resources](#available-guides-and-resources) - [Usage Patterns](#usage-patterns) - [Resilient Workflow](#resilient-workflow) - [Unicode Semantic Symbols](#unicode-semantic-symbols) - [Python Utilities](#python-utilities) - [Decision Tree Examples](#decision-tree-examples) - [High-Contrast Styling](#high-contrast-styling) - [File Organization](#file-organization) - [Workflow Summary](#workflow-summary) - [When to Use What](#when-to-use-what) - [Best Practices](#best-practices) - [Learning Path](#learning-path) ## Decision Tree **How this skill works:** 1. **User makes a request** → Skill analyzes intent 2. **Skill determines diagram/document type** → Loads appropriate guide(s) 3. **AI reads specialized guide** → Generates diagram/document using templates 4. **Result delivered** → With validation and export options **User Intent Analysis:** ```mermaid flowchart TD Start([User Request]) --> Analyze{Analyze Intent} Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide
references/guides/diagrams/activity-diagrams.md] Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide
references/guides/diagrams/deployment-diagrams.md] Analyze -->|"system architecture, components"| Arch[Load Architecture Guide
references/guides/diagrams/architecture-diagrams.md] Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide
references/guides/diagrams/sequence-diagrams.md] Analyze -->|"class, ER, state, wiki, walkthrough"| WikiGuide[Load WikiTicket GitHub Guide
references/guides/wiki-ticket-and-github.md] Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide
references/guides/code-to-diagram/ + examples/] Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template
assets/*-design-template.md] Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide
references/guides/unicode-symbols/guide.md] Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts
scripts/extract_mermaid.py
scripts/mermaid_to_image.py] Activity --> Generate[Generate Diagram] Deploy --> Generate Arch --> Generate Sequence --> Generate WikiGuide --> Generate CodeToDiag --> Generate DesignDoc --> Generate Unicode --> Generate Scripts --> Execute[Execute Script] Generate --> Validate{Validate?} Validate -->|Yes| RunValidation[Run mmdc validation] Validate -->|No| Output RunValidation --> Output[Output Result] Execute --> Output classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue class Analyze,Validate decision class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide class Generate,Execute,RunValidation,Output action ``` ## Available Guides and Resources ### Diagram Type Guides (`references/guides/diagrams/`) | Guide | Full Path | Load When User Wants | Examples | |-------|-----------|---------------------|----------| | Activity Diagrams | `references/guides/diagrams/activity-diagrams.md` | Workflows, processes, business logic, user flows, decision trees | "Show checkout flow", "Document ETL pipeline", "Create approval workflow" | | Deployment Diagrams | `references/guides/diagrams/deployment-diagrams.md` | Infrastructure, cloud architecture, K8s, serverless, network topology | "Show AWS architecture", "Document GCP deployment", "Create K8s diagram" | | Architecture Diagrams | `references/guides/diagrams/architecture-diagrams.md` | System architecture, component design, high-level structure | "Show system components", "Document microservices", "Architecture overview" | | Sequence Diagrams | `references/guides/diagrams/sequence-diagrams.md` | API interactions, service communication, request/response flows | "Show API call sequence", "Document auth flow", "Service interactions" | | WikiTicket / GitHub / Confluence | `references/guides/wiki-ticket-and-github.md` | Design docs, walkthroughs, requirements, wiki publish, Confluence images | "architecture doc", "code walkthrough", "wiki", "Confluence" | Default for WikiTicket and GitHub wiki is this skill, including `classDiagram`, `erDiagram`, and `stateDiagram-v2`. Do not send those to PlantUML. If GitHub fails to render C4 / architecture-beta / block-beta, fall back to `flowchart TD`. ### Code-to-Diagram Guide & Examples | Resource | Full Path | What It Provides | |----------|-----------|------------------| | **Master Guide** | `references/guides/code-to-diagram/README.md` | Complete workflow for analyzing any codebase and extracting diagrams | | **Spring Boot** | `examples/spring-boot/README.md` | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic | | **FastAPI** | `examples/fastapi/README.md` | Python async patterns, Pydantic models, dependency injection, cloud deployment | | **React** | `examples/react/README.md` | Component hierarchy, state management, data flow, build pipeline | | **Python ETL** | `examples/python-etl/README.md` | Data pipeline, transformation steps, error handling, scheduling | | **Node/Express** | `examples/node-webapp/README.md` | Middleware chain, route handlers, async patterns, deployment | | **Java Web App** | `examples/java-webapp/README.md` | Traditional MVC, servlet containers, WAR deployment | ### Design Document Templates | Template | Full Path | Use For | Load When | |----------|-----------|---------|-----------| | Architecture Design | `assets/architecture-design-template.md` | System-wide architecture | "Create architecture doc", "Document system design" | | API Design | `assets/api-design-template.md` | API specifications | "API design doc", "Document REST API" | | Feature Design | `assets/feature-design-template.md` | Feature planning | "Feature design", "Plan new feature" | | Database Design | `assets/database-design-template.md` | Database schema | "Database design", "Document schema" | | System Design | `assets/system-design-template.md` | Complete system | "System design doc", "Full system documentation" | ### Unicode Symbols Guide **Full Path:** `references/guides/unicode-symbols/guide.md` **Load when user mentions:** "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols" **Quick Reference:** - 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️ - ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨 - 💾 Data: 💾 📦 📊 📈 🗃️ 🧊 - 📨 Messaging: 📨 📬 📤 📥 🐰 📢 - 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫 - 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌ ### Python Scripts (`scripts/`) | Script | Use For | Load When | |--------|---------|-----------| | `extract_mermaid.py` | Extract diagrams from Markdown, validate syntax, replace with images | "extract diagrams", "validate mermaid", "find all diagrams" | | `mermaid_to_image.py` | Convert .mmd to PNG/SVG, batch conversion, custom themes | "convert to image", "render diagram", "create PNG" | | `resilient_diagram.py` | Full workflow: save .mmd, generate image, validate, error recovery | "generate diagram", "create diagram with validation", "resilient diagram" | ## GitHub wiki, WikiTicket, and Confluence Load `references/guides/wiki-ticket-and-github.md` for WikiTicket design docs, code walkthroughs, requirements, GitHub wiki, or Confluence. | Target | What to ship | |--------|----------------| | GitHub wiki / GFM | Fenced `mermaid` block. GitHub renders class, ER, state, sequence, flowchart, C4. | | Confluence / Notion / Word / PDF | Also render PNG or SVG (`scripts/resilient_diagram.py` or `mmdc`) and upload the image. Do not rely on Confluence to render Mermaid. | PlantUML is opt-in for Salt wireframes, use case, timing, ArchiMate, nwdiag, and WBS. Those always ship as PNG or SVG. ## Usage Patterns Common request patterns and guide selection. See [When to Use What](#when-to-use-what) for complete mapping. | Pattern | Example Request | Guides to Load | |---------|-----------------|----------------| | Single Diagram | "Create activity diagram for login flow" | Diagram type guide + Unicode symbols | | Code-to-Diagram | "Generate deployment from application.yml" | Framework example + Deployment guide | | Design Document | "Create API design document" | Template from assets/ + Relevant diagram guides | | Extract/Validate | "Extract diagrams from design.md" | Use `scripts/extract_mermaid.py` | | Batch Convert | "Convert all .mmd to PNG" | Use `scripts/mermaid_to_image.py` | ## Resilient Workflow **CRITICAL:** This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization. **Full Guide:** `references/guides/resilient-workflow.md` ### Workflow Overview ```mermaid flowchart LR A[1. Identify Type] --> B[2. Save .mmd + Image] B --> C{3. Valid?} C -->|Yes| D[4. Add to Markdown] C -->|No| E[5. Error Recovery] E --> F{Fix Found?} F -->|Yes| A F -->|No| G[Search External] G --> A classDef step fill:#90EE90,stroke:#333,color:darkgreen classDef decision fill:#FFD700,stroke:#333,color:black class A,B,D,E,G step class C,F decision ``` ### Key Principle **NEVER add a diagram to markdown until it passes validation.** This prevents broken diagrams in documentation. ### Using the Script (Recommended) ```bash # Generate with full error recovery python scripts/resilient_diagram.py \ --code "flowchart TD; A-->B" \ --markdown-file design_doc \ --diagram-num 1 \ --title "process_flow" \ --format png \ --json ``` **Output:** Both `.mmd` and `.png` files in `./diagrams/` directory. ### File Naming Convention ``` ./diagrams/___

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…