{"id":"42354cb9-6a63-4f64-9ce7-12f64d187596","shortId":"vzhX94","kind":"skill","title":"creating-mermaid-diagrams","tagline":"Generate Mermaid diagrams (.mmd) and export to PNG/SVG/PDF using mmdc CLI or Kroki API. USE THIS SKILL when user mentions diagram, flowchart, sequence diagram, class diagram, ER diagram, state machine, architecture, visualize, git graph, 画图, 架构图, 流程图, 时序图. PROACTIVELY USE when ex","description":"# Mermaid Diagrams\n\nGenerate `.mmd` text files and export to PNG/SVG/PDF using `mmdc` (local) or Kroki API (no install).\n\n**Key advantage:** Text-based syntax with **fully automatic layout** — no x/y coordinates needed.\n\n## Prerequisites\n\n**Option A: Local (mmdc)**\n```bash\nnpm install -g @mermaid-js/mermaid-cli\nmmdc --version\n```\n\n**Option B: Kroki API (no install)**\n```bash\ncurl --version  # Just need curl\n```\n\n## Workflow\n\n0. **Update check (notify, don't pull)** — first use per conversation. Throttle to once per 24 h via `<this-skill-dir>/.last_update`; never mutate the skill directory without explicit user consent.\n\n   - If `.last_update` exists and is <24 h old, skip this step entirely.\n   - Otherwise, fetch the latest tag from upstream:\n     ```bash\n     git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \\\n       | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1\n     ```\n   - Compare with this skill's `metadata.version` from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:\n     > \"A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to `git pull`?\"\n\n     If they say yes, run `git -C <this-skill-dir> pull --ff-only`. Refresh `.last_update` either way so the prompt doesn't repeat for 24 hours.\n   - If upstream is the same or older, refresh `.last_update` silently and continue.\n   - On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.\n1. **Check deps** — try `mmdc --version`, fallback to Kroki if unavailable\n2. **Pick diagram type** — choose from table below\n3. **Generate** — write `.mmd` file to disk\n4. **Validate** — run validation (REQUIRED before export)\n5. **Export** — use `mmdc` or Kroki API to produce PNG/SVG/PDF\n6. **Report** — tell user the output file paths\n\n## Validation (Required)\n\n**NEVER export a diagram without validating first.**\n\n```bash\n# Validate with mmdc (local)\nmmdc -i diagram.mmd -o /tmp/test.png 2>&1\n\n# Validate with Kroki (if mmdc unavailable)\ncurl -s -X POST -H \"Content-Type: text/plain\" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo \"Valid\" || echo \"Invalid\"\n\n# If error, fix the .mmd file and validate again\n# Only proceed to export after validation passes\n```\n\nCommon validation errors:\n- Missing quotes around labels with special characters\n- Wrong arrow syntax (use `->>` for sequence, `-->` for flowchart)\n- Undeclared participants in sequence diagrams\n\n## Diagram Types\n\n| Type | Keyword | Use for |\n|------|---------|---------|\n| Flowchart | `flowchart TD/LR` | processes, pipelines, decisions |\n| Sequence | `sequenceDiagram` | API calls, message passing |\n| Class | `classDiagram` | OOP models, data structures |\n| ER | `erDiagram` | database schemas |\n| State | `stateDiagram-v2` | state machines, lifecycle |\n| Gantt | `gantt` | project timelines |\n| Pie | `pie` | proportions |\n| Git Graph | `gitGraph` | branch strategies |\n| C4 Context | `C4Context` | high-level architecture |\n| Mind Map | `mindmap` | topic breakdowns |\n\n## Syntax Reference\n\n**Flowchart**: See [reference/FLOWCHART.md](reference/FLOWCHART.md)\n**Sequence**: See [reference/SEQUENCE.md](reference/SEQUENCE.md)\n**Class & ER**: See [reference/CLASS-ER.md](reference/CLASS-ER.md)\n**Other types**: See [reference/OTHER-TYPES.md](reference/OTHER-TYPES.md)\n\n## Examples\n\n### Example 1: API Authentication Flow\n\n**User prompt:**\n> Create a sequence diagram for JWT authentication\n\n**Generated `.mmd`:**\n```mermaid\nsequenceDiagram\n  participant C as Client\n  participant G as API Gateway\n  participant A as Auth Service\n  participant D as Database\n\n  C->>G: POST /login {email, password}\n  G->>A: validate(credentials)\n  A->>D: SELECT user WHERE email=?\n  D-->>A: user record\n  A-->>A: verify password hash\n  A-->>G: 200 OK + JWT token\n  G-->>C: {token: \"eyJhbG...\"}\n```\n\n**Output files:** `auth-flow.mmd` + `auth-flow.png`\n\n---\n\n### Example 2: Microservices Architecture\n\n**User prompt:**\n> Draw an e-commerce microservices architecture\n\n**Generated `.mmd`:**\n```mermaid\nflowchart TD\n  subgraph Clients\n    M[Mobile App]\n    W[Web App]\n  end\n\n  GW[API Gateway]\n\n  subgraph Services\n    US[User Service]\n    OS[Order Service]\n    PS[Product Service]\n    PAY[Payment Service]\n  end\n\n  subgraph Data\n    UDB[(User DB)]\n    ODB[(Order DB)]\n    PDB[(Product DB)]\n    REDIS[(Redis Cache)]\n  end\n\n  M & W --> GW\n  GW --> US & OS & PS & PAY\n  US --> UDB\n  OS --> ODB\n  PS --> PDB\n  PAY --> REDIS\n```\n\n**Output files:** `ecommerce-arch.mmd` + `ecommerce-arch.png`\n\n---\n\n### Example 3: Order State Machine\n\n**User prompt:**\n> Show order lifecycle states\n\n**Generated `.mmd`:**\n```mermaid\nstateDiagram-v2\n  [*] --> Pending : order created\n  Pending --> Confirmed : payment success\n  Pending --> Cancelled : timeout/cancel\n  Confirmed --> Shipped : dispatched\n  Shipped --> Delivered : received\n  Delivered --> [*]\n  Cancelled --> [*]\n```\n\n**Output files:** `order-states.mmd` + `order-states.png`\n\n## Export Commands\n\n### Option 1: Local Export (mmdc)\n\nRequires `mmdc` installed locally. Best for offline use.\n\n```bash\n# PNG (recommended: 2048px wide, white background)\nmmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white\n\n# PNG with theme (default | dark | neutral | forest | base)\nmmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral\n\n# SVG\nmmdc -i diagram.mmd -o diagram.svg\n\n# PDF\nmmdc -i diagram.mmd -o diagram.pdf\n```\n\n### Option 2: Kroki API (No Install Required)\n\nUse [Kroki](https://kroki.io) when `mmdc` is not available. No local dependencies needed.\n\n```bash\n# SVG via Kroki\ncurl -X POST -H \"Content-Type: text/plain\" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg\n\n# PNG via Kroki\ncurl -X POST -H \"Content-Type: text/plain\" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png\n\n# PDF via Kroki\ncurl -X POST -H \"Content-Type: text/plain\" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -o diagram.pdf\n```\n\n**Kroki advantages:**\n- No local installation required\n- Works on any system with `curl`\n- Supports 20+ diagram types (PlantUML, GraphViz, D2, etc.)\n\n**When to use Kroki:**\n- `mmdc` installation fails\n- Quick one-off diagrams\n- CI/CD pipelines without Node.js\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| `mmdc` not found | `npm install -g @mermaid-js/mermaid-cli` |\n| Wrong arrow in sequence | Use `->>` for request, `-->>` for response |\n| Special chars in label | Wrap in quotes: `A[\"Label: value\"]` |\n| Blank/small output | Add `-w 2048` flag |\n| Participant order wrong | Declare `participant` explicitly at top |\n| Subgraph name with spaces | Wrap in quotes: `subgraph \"My Layer\"` |","tags":["mermaid","skill","agents365-ai","agent-skill","agent-skills","claude-code","claude-code-skill","claude-skills","diagram","erd","flowchart","kroki"],"capabilities":["skill","source-agents365-ai","skill-mermaid-skill","topic-agent-skill","topic-agent-skills","topic-claude-code","topic-claude-code-skill","topic-claude-skills","topic-diagram","topic-erd","topic-flowchart","topic-kroki","topic-mermaid","topic-openclaw","topic-openclaw-skills"],"categories":["mermaid-skill"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Agents365-ai/mermaid-skill/mermaid-skill","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Agents365-ai/mermaid-skill","source_repo":"https://github.com/Agents365-ai/mermaid-skill","install_from":"skills.sh"}},"qualityScore":"0.473","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 47 github stars · SKILL.md body (6,810 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:58:09.105Z","embedding":null,"createdAt":"2026-05-17T12:56:56.634Z","updatedAt":"2026-05-18T18:58:09.105Z","lastSeenAt":"2026-05-18T18:58:09.105Z","tsv":"'-1':175 '/.last_update':125 '/dev/null':165 '/login':546 '/mermaid-cli':91,892 '/mermaid/pdf':840 '/mermaid/png':820 '/mermaid/svg':381,800 '/tmp/test.png':357 '/tmp/test.svg':383 '0':107 '1':288,359,508,704 '2':164,168,299,358,583,764 '20':856 '200':570 '2048':729,746,916 '2048px':719 '24':122,141,238 '3':307,663 '4':314 '5':321 '6':331 'add':914 'advantag':66,844 'api':18,62,97,327,441,509,532,610,766 'app':604,607 'architectur':35,480,585,594 'around':409 'arrow':415,894 'ask':199 'auth':537 'auth-flow.mmd':580 'auth-flow.png':581 'authent':510,520 'automat':73 'avail':207,777 'awk':166 'b':95 'background':722 'backgroundcolor':730,747 'base':69,739 'bash':84,100,155,348,716,782 'best':712 'binari':377,796,816,836 'blank/small':912 'branch':472 'breakdown':485 'c':157,221,526,543,575 'c4':474 'c4context':476 'cach':640 'call':442 'cancel':687,696 'char':903 'charact':413 'check':109,289 'checkout':260 'choos':303 'ci/cd':875 'class':29,445,496 'classdiagram':446 'clawhub':263 'clawhub-instal':262 'cli':15 'client':528,601 'command':702 'commerc':592 'common':404,879 'compar':176 'confirm':683,689 'consent':134 'content':372,791,811,831 'content-typ':371,790,810,830 'context':475 'continu':252,277 'convers':117 'coordin':77 'copi':265 'creat':2,514,681 'creating-mermaid-diagram':1 'credenti':552 'curl':101,105,366,786,806,826,854 'd':540,554,559 'd2':861 'dark':736 'data':376,449,628,795,815,835 'data-binari':375,794,814,834 'databas':453,542 'db':631,634,637 'decis':438 'declar':921 'default':735 'deliv':693,695 'dep':290 'depend':780 'diagram':4,7,25,28,30,32,48,301,344,426,427,517,857,874 'diagram.mmd':355,378,725,742,754,760,797,817,837 'diagram.pdf':762,842 'diagram.png':727,744,822 'diagram.svg':756,802 'directori':130 'disk':313 'dispatch':691 'doesn':234 'draw':588 'e':591 'e-commerc':590 'e.g':261 'echo':384,386 'ecommerce-arch.mmd':660 'ecommerce-arch.png':661 'either':229 'email':547,558 'end':608,626,641 'entir':147 'er':31,451,497 'erdiagram':452 'error':274,389,406 'etc':862 'ex':46 'exampl':506,507,582,662 'exist':138 'explicit':132,923 'export':10,54,320,322,342,400,701,706 'eyjhbg':577 'fail':869 'failur':255,287 'fallback':294 'fetch':149 'ff':224 'ff-on':223 'file':52,311,337,393,579,659,698 'first':114,347 'fix':390,882 'flag':917 'flow':511 'flowchart':26,421,433,434,488,598 'forest':738 'found':885 'frontmatt':184 'fulli':72 'g':87,530,544,549,569,574,888 'gantt':462,463 'gateway':533,611 'generat':5,49,308,521,595,673 'git':37,156,213,220,259,469 'gitgraph':471 'graph':38,470 'graphviz':860 'gw':609,644,645 'h':123,142,370,789,809,829 'hash':567 'high':478 'high-level':477 'hour':239 'instal':64,86,99,264,710,768,847,868,887 'invalid':387 'js':90,891 'jwt':519,572 'key':65 'keyword':430 'kroki':17,61,96,296,326,362,765,771,785,805,825,843,866 'kroki.io':380,772,799,819,839 'kroki.io/mermaid/pdf':838 'kroki.io/mermaid/png':818 'kroki.io/mermaid/svg':379,798 'label':410,905,910 'last':136,227,248 'latest':151 'layer':935 'layout':74 'level':479 'lifecycl':461,671 'line':197 'local':59,82,352,705,711,779,846 'ls':159 'ls-remot':158 'm':602,642 'machin':34,460,666 'map':482 'mention':24,285 'mermaid':3,6,47,89,523,597,675,890 'mermaid-j':88,889 'messag':443 'metadata.version':181 'microservic':584,593 'mind':481 'mindmap':483 'miss':407 'mistak':880,881 'mmd':8,50,310,392,522,596,674 'mmdc':14,58,83,92,292,324,351,353,364,707,709,723,740,752,758,774,867,883 'mobil':603 'model':448 'mutat':127 'name':927 'need':78,104,781 'neutral':737,750 'never':126,341 'newer':191,201 'node.js':878 'notifi':110 'npm':85,886 'o':356,382,726,743,755,761,801,821,841 'odb':632,653 'offlin':256,714 'ok':571 'old':143 'older':246 'one':196,872 'one-off':871 'oop':447 'option':80,94,703,763 'order':618,633,664,670,680,919 'order-states.mmd':699 'order-states.png':700 'origin':162 'os':617,647,652 'otherwis':148 'output':336,578,658,697,913 'particip':423,525,529,534,539,918,922 'pass':403,444 'password':548,566 'path':269,338 'pay':623,649,656 'payment':624,684 'pdb':635,655 'pdf':757,823 'pend':679,682,686 'per':116,121 'permiss':271 'pick':300 'pie':466,467 'pipelin':437,876 'plantuml':859 'png':717,732,803 'png/svg/pdf':12,56,330 'post':369,545,788,808,828 'prerequisit':79 'print':167 'proactiv':43 'proceed':398 'process':436 'produc':329 'product':621,636 'project':464 'prompt':233,513,587,668 'proport':468 'ps':620,648,654 'pull':113,214,222 'quick':870 'quot':408,908,932 'read':267 'read-on':266 'receiv':694 'recommend':718 'record':562 'redi':638,639,657 'refer':487 'reference/class-er.md':499,500 'reference/flowchart.md':490,491 'reference/other-types.md':504,505 'reference/sequence.md':494,495 'refresh':226,247 'refs/tags':171 'remot':160 'repeat':236 'report':332 'request':899 'requir':318,340,708,769,848 'respons':901 'run':219,316 'say':217 'schema':454 'sed':169 'see':489,493,498,503 'select':555 'semver':192 'sequenc':27,419,425,439,492,516,896 'sequencediagram':440,524 'servic':538,613,616,619,622,625 'ship':690,692 'show':669 'silent':250,275 'skill':21,129,179,205 'skill-mermaid-skill' 'skip':144 'sort':172 'source-agents365-ai' 'space':929 'special':412,902 'state':33,455,459,665,672 'statediagram':457,677 'statediagram-v2':456,676 'step':146 'strategi':473 'strict':190 'structur':450 'subgraph':600,612,627,926,933 'success':685 'support':855 'svg':751,783 'swallow':272 'syntax':70,416,486 'system':852 'tabl':305 'tag':152,161,188 'tail':174 'task':282 'td':599 'td/lr':435 'tell':193,333 'text':51,68 'text-bas':67 'text/plain':374,793,813,833 'theme':734,749 'throttl':118 'timelin':465 'timeout/cancel':688 'token':573,576 'top':925 'topic':484 'topic-agent-skill' 'topic-agent-skills' 'topic-claude-code' 'topic-claude-code-skill' 'topic-claude-skills' 'topic-diagram' 'topic-erd' 'topic-flowchart' 'topic-kroki' 'topic-mermaid' 'topic-openclaw' 'topic-openclaw-skills' 'tri':291 'type':302,373,428,429,502,792,812,832,858 'udb':629,651 'unavail':298,365 'undeclar':422 'updat':108,137,228,249 'upstream':154,187,241 'us':614,646,650 'use':13,19,44,57,115,323,417,431,715,770,865,897 'user':23,133,195,280,334,512,556,561,586,615,630,667 'v':163,173 'v2':458,678 'va.b.c':209 'valid':315,317,339,346,349,360,385,395,402,405,551 'valu':911 'verifi':565 'version':93,102,202,293 'via':124,784,804,824 'visual':36 'vx.y.z':208 'w':605,643,728,745,915 'want':210 'way':230 'web':606 'white':721,731,748 'wide':720 'without':131,345,877 'work':849 'workflow':106 'wrap':906,930 'write':309 'wrong':414,893,920 'x':368,787,807,827 'x/y':76 'yes':218 '时序图':42 '架构图':40 '流程图':41 '画图':39","prices":[{"id":"db08afd3-649b-419d-8112-1fa51dcb96ef","listingId":"42354cb9-6a63-4f64-9ce7-12f64d187596","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Agents365-ai","category":"mermaid-skill","install_from":"skills.sh"},"createdAt":"2026-05-17T12:56:56.634Z"}],"sources":[{"listingId":"42354cb9-6a63-4f64-9ce7-12f64d187596","source":"github","sourceId":"Agents365-ai/mermaid-skill/mermaid-skill","sourceUrl":"https://github.com/Agents365-ai/mermaid-skill/tree/main/skills/mermaid-skill","isPrimary":false,"firstSeenAt":"2026-05-17T12:56:56.634Z","lastSeenAt":"2026-05-18T18:58:09.105Z"}],"details":{"listingId":"42354cb9-6a63-4f64-9ce7-12f64d187596","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Agents365-ai","slug":"mermaid-skill","github":{"repo":"Agents365-ai/mermaid-skill","stars":47,"topics":["agent-skill","agent-skills","claude-code","claude-code-skill","claude-skills","diagram","erd","flowchart","kroki","mermaid","openclaw","openclaw-skills","sequence-diagram","skill-md","skillsmp"],"license":"mit","html_url":"https://github.com/Agents365-ai/mermaid-skill","pushed_at":"2026-05-17T08:52:34Z","description":"Mermaid diagrams (.mmd) from natural language with validation loop. 11+ types, multi-backend (mmdc / Kroki), PNG/SVG/PDF, multi-agent.","skill_md_sha":"e8d3603772660498b748d38a726de08f12d50e59","skill_md_path":"skills/mermaid-skill/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Agents365-ai/mermaid-skill/tree/main/skills/mermaid-skill"},"layout":"multi","source":"github","category":"mermaid-skill","frontmatter":{"name":"creating-mermaid-diagrams","description":"Generate Mermaid diagrams (.mmd) and export to PNG/SVG/PDF using mmdc CLI or Kroki API. USE THIS SKILL when user mentions diagram, flowchart, sequence diagram, class diagram, ER diagram, state machine, architecture, visualize, git graph, 画图, 架构图, 流程图, 时序图. PROACTIVELY USE when explaining ANY system with 3+ components, API flows, authentication sequences, class hierarchies, database schemas, or state machines. Supports 11+ diagram types with fully automatic layout."},"skills_sh_url":"https://skills.sh/Agents365-ai/mermaid-skill/mermaid-skill"},"updatedAt":"2026-05-18T18:58:09.105Z"}}