{
  "schemaVersion": "1.0",
  "item": {
    "slug": "skill-mermaid-diagrams",
    "name": "generate mermaid diagrams",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/chunhualiao/skill-mermaid-diagrams",
    "canonicalUrl": "https://clawhub.ai/chunhualiao/skill-mermaid-diagrams",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/skill-mermaid-diagrams",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=skill-mermaid-diagrams",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "package.json",
      "SKILL.md",
      "assets/class-diagram.mmd.txt",
      "assets/example-content.json",
      "assets/radial-concept.mmd.txt"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/skill-mermaid-diagrams"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/skill-mermaid-diagrams",
    "agentPageUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent",
    "manifestUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Mermaid Diagrams",
        "body": "Generate professional, consistently-styled Mermaid diagrams for technical content with automatic template selection, content generation, and quality validation."
      },
      {
        "title": "Quick Start",
        "body": "Subagent Pattern (Recommended):\n\nWhen user requests diagram generation, spawn a subagent:\n\nGenerate 3 Mermaid diagrams for /path/to/chapter-01.md and save to diagrams/chapter-01/\n\nThe subagent will:\n\nRead chapter content\nSelect appropriate templates\nGenerate placeholder content\nCreate content.json\nRun generation script\nValidate output\n\nManual Pattern:\n\n# 1. Create content.json (see assets/example-content.json)\n# 2. Render diagrams\nnode scripts/generate.mjs --content content.json --out diagrams/chapter-01\n\n# 3. Validate\nnode scripts/validate.mjs --dir diagrams/chapter-01"
      },
      {
        "title": "Automated Installation (Recommended)",
        "body": "Run the installation script to automatically install and verify mermaid-cli:\n\ncd $SKILL_DIR  # Path to skill-mermaid-diagrams directory\n./scripts/install-deps.sh\n\nThe script will:\n\nCheck Node.js version (>= 18.0.0 required)\nInstall or upgrade mermaid-cli to latest version\nVerify installation and version compatibility\nProvide troubleshooting guidance if needed"
      },
      {
        "title": "Manual Installation",
        "body": "Alternatively, install Mermaid CLI globally:\n\nnpm install -g @mermaid-js/mermaid-cli\n\nVerify installation:\n\nmmdc --version  # Should be >= 11.0.0"
      },
      {
        "title": "Subagent Workflow (Primary Pattern)",
        "body": "When a user requests diagram generation, spawn a subagent to handle the complete workflow:\n\nTask: Generate 3 Mermaid diagrams for chapter 5\n\nSteps:\n1. Read $CONTENT_DIR/chapters/chapter-05.md\n2. Analyze content and select 3 appropriate diagram templates from: architecture, flowchart, sequence, concept-map, timeline, comparison\n3. For each selected template:\n   - Read template from $SKILL_DIR/assets/\n   - Extract placeholders ({{PLACEHOLDER_NAME}} format)\n   - Generate concise labels (max 8 words each) based on chapter content\n4. Create content.json with structure:\n   {\n     \"chapter\": \"chapter-05.md\",\n     \"diagrams\": [\n       {\n         \"template\": \"architecture\",\n         \"placeholders\": { \"SYSTEM_NAME\": \"...\", ... }\n       },\n       ...\n     ]\n   }\n5. Save to $CONTENT_DIR/diagrams/chapter-05/content.json\n6. Run: node $SKILL_DIR/scripts/generate.mjs --content content.json --out $CONTENT_DIR/diagrams/chapter-05\n7. Validate: node $SKILL_DIR/scripts/validate.mjs --dir $CONTENT_DIR/diagrams/chapter-05\n8. Report success with file count\n\nNote: Replace $SKILL_DIR and $CONTENT_DIR with actual paths:\n- SKILL_DIR: Path to skill-mermaid-diagrams directory\n- CONTENT_DIR: Path to your content/project directory"
      },
      {
        "title": "Manual Content Generation",
        "body": "If generating content.json manually:\n\n# 1. Create content.json (see assets/example-content.json)\n# 2. Render\ncd $SKILL_DIR  # Path to skill-mermaid-diagrams directory\nnode scripts/generate.mjs \\\n  --content /path/to/content.json \\\n  --out /path/to/output\n\n# 3. Validate\nnode scripts/validate.mjs --dir /path/to/output\n\nParameters:\n\n--content / -c: Content JSON file (required)\n--out / -o: Output directory (default: ./diagrams)"
      },
      {
        "title": "Validate All Generated Diagrams",
        "body": "for dir in diagrams/chapter-*/; do\n  node scripts/validate.mjs --dir \"$dir\"\ndone"
      },
      {
        "title": "Available Templates",
        "body": "The skill includes 12 professionally-themed templates with consistent color schemes:\n\narchitecture.mmd - System architecture, component diagrams, tool integration\n\nUse for: System components, tool pipelines, agent interactions\nFixed node IDs (space-safe): Uses C1, C2, C3 internally, only labels are customizable\n\n\n\nflowchart.mmd - Decision flows, processes, workflows, debugging steps\n\nUse for: Decision trees, process flows, validation workflows\n\n\n\nsequence.mmd - Actor interactions, message passing, session patterns\n\nUse for: API call sequences, actor communication, message flows\n\n\n\nconcept-map.mmd - Key concepts, mental models, paradigms, relationships\n\nUse for: Hierarchical concepts, mental models, knowledge graphs\nImproved version (graph-based, not mindmap): Full color control, readable text\n\n\n\nradial-concept.mmd - Layered concepts radiating from center   - Use for: Progressive summarization, abstraction layers, hierarchical models\n\n4 color-coded levels: green → orange → blue → purple\n\n\n\ntimeline.mmd - Temporal progression, optimization stages, evolution\n\nUse for: Project phases, evolution timelines, staged processes\n\n\n\ncomparison.mmd - Trade-offs, quadrant analysis (2D plotting)\n\nUse for: Cost vs performance, effort vs impact (X/Y coordinate plotting)\nRequires X/Y coordinates for items\n\n\n\ncomparison-table.mmd - Side-by-side feature comparison\n\nUse for: AI vs Script decisions, option comparisons, feature matrices\nAlternative to quadrant when you need simple side-by-side, not 2D plotting\n\n\n\ngantt.mmd - Project timelines, task scheduling   - Use for: Project planning, milestone tracking, task dependencies\n\nSupports: Multiple sections, task status (done/active/crit), date ranges\n\n\n\nmindmap.mmd - Organic radial mind maps    - Use for: Brainstorming, organic thought structures, free-form concept mapping\n\nLimitation: Auto-assigns colors/text (limited theme control)\nAlternative: Use radial-concept.mmd for better color control\n\n\n\nclass-diagram.mmd - UML class diagrams\n\nUse for: Object models, database schemas, system architecture (OOP)\nSupports: Attributes, methods, relationships (inheritance, composition, association)\n\n\n\nstate-diagram.mmd - State machines, lifecycle diagrams\n\nUse for: Process states, object lifecycles, workflow stages\nSupports: Transitions with labels, notes on states, start/end markers"
      },
      {
        "title": "Template Placeholder Reference",
        "body": "Each template requires specific placeholders. All placeholders must be provided to avoid rendering errors.\n\nTemplatePlaceholdersComplexityRequired Fieldsarchitecture10MediumSYSTEM_NAME, COMPONENT_1-3_LABEL, EXTERNAL_1-2_LABEL, FLOW_1-4flowchart11MediumSTART_LABEL, DECISION_1-2, ACTION_1-4, CHOICE_1-2_YES/NO, END_LABELsequence8MediumACTOR_1-3, MESSAGE_1-5concept-map15HighCENTRAL_CONCEPT, BRANCH_1-4, BRANCH_X_SUB_1-3radial-concept13MediumCENTRAL_CONCEPT, LEVEL_1-4_LABEL, LEVEL_X_NODE_1-3timeline6LowEVENT_1-6, DATE_1-6comparison18HighCOMPARISON_TITLE, X/Y_AXIS_LOW/HIGH, QUADRANT_1-4_LABEL, ITEM_1-5 + X/Y coordscomparison-table10LowOPTION_1-2_TITLE, OPTION_X_CRITERION_1-4gantt14HighCHART_TITLE, SECTION_1-3_TITLE, TASK_X_Y (name/id/start/duration)mindmap13MediumROOT_CONCEPT, BRANCH_1-4, BRANCH_X_CHILD_1-3class-diagram21HighCLASS_1-3_NAME, CLASS_X_ATTR_1-3, CLASS_X_METHOD_1-3, REL_1-3_TYPE/LABELstate-diagram18MediumSTATE_1-8, TRANSITION_1-7_LABEL, STATE_1/4/7_NOTE\n\nImportant Notes:\n\narchitecture.mmd: Uses fixed node IDs (C1, C2, C3, E1, E2) internally. Only *_LABEL placeholders are customizable. Labels can contain spaces (space-safe).\nconcept-map.mmd: Improved graph-based version (replaced mindmap). Better color control and readability.\ncomparison.mmd: QuadrantChart requires X/Y coordinates. Use comparison-table.mmd for simple side-by-side comparisons.\ngantt.mmd: Task status options: done, active, crit, or blank. Date format: YYYY-MM-DD. Duration: Nd (days) or YYYY-MM-DD.\nmindmap.mmd: Limited theme control (auto-colors, auto-text). For controlled colors/text, use radial-concept.mmd instead.\nclass-diagram.mmd: Relationship types: <|-- (inheritance), *-- (composition), o-- (aggregation), --> (association), ..> (dependency).\nstate-diagram.mmd: Uses stateDiagram-v2 syntax. States are simple identifiers (no spaces). Notes attach to states 1, 4, and 7.\nText length limits: Generator warns if labels exceed recommended length (25-50 chars depending on template).\n\nPlaceholder Naming Convention:\n\nComponent labels: COMPONENT_1_LABEL, COMPONENT_2_LABEL\nBranch hierarchy: BRANCH_1, BRANCH_1_SUB_1, BRANCH_1_SUB_2\nLevel-based: LEVEL_1_LABEL, LEVEL_1_NODE_1"
      },
      {
        "title": "v2.0 (2026-02-15) - Root Cause Fixes",
        "body": "Breaking Changes:\n\narchitecture.mmd - Fixed node ID handling (space-safe)\n\nBefore: Used placeholder values as node IDs → failed when labels contained spaces\nAfter: Uses fixed node IDs (C1, C2, C3) → labels can contain any characters\nMigration: Remove COMPONENT_1, COMPONENT_2, COMPONENT_3 from content.json (only *_LABEL variants needed)\n\n\n\nconcept-map.mmd - Replaced mindmap with graph-based version\n\nBefore: Mindmap syntax with auto-colors, black-on-purple text (unreadable)\nAfter: Graph LR syntax with explicit styling, white text on dark backgrounds\nResult: +100% contrast improvement (2.6:1 → 5.2:1 on purple nodes)\nNew Features:\n\nradial-concept.mmd - Progressive summarization diagrams with 4 color-coded levels\ncomparison-table.mmd - Side-by-side feature comparison (alternative to quadrant chart)\nValidation - Generator now warns about text length, unresolved placeholders, special characters\n\nAll changes target root causes (template design flaws, missing validation) rather than surface symptoms."
      },
      {
        "title": "Color Scheme (Consistent Across All Templates)",
        "body": "Primary Blue: #4A90E2 - Main components, actions\nSecondary Purple: #7B68EE - Supporting elements\nTertiary Green: #90EE90 - External actors, success states\nWarning Yellow: #FFD700 - Decisions, cautions\nError Red: #FF6B6B - Failures, critical paths"
      },
      {
        "title": "Output Structure",
        "body": "After generation, each chapter directory contains:\n\ndiagrams/chapter-01/\n├── diagram-01-architecture.mmd   # Mermaid source\n├── diagram-01-architecture.svg   # Vector output\n├── diagram-01-architecture.png   # Raster output (1200px wide)\n├── diagram-02-flowchart.mmd\n├── diagram-02-flowchart.svg\n├── diagram-02-flowchart.png\n├── diagram-03-concept-map.mmd\n├── diagram-03-concept-map.svg\n├── diagram-03-concept-map.png\n└── summary.json                   # Generation metadata"
      },
      {
        "title": "Error Handling",
        "body": "The generator includes robust error handling:\n\nTemplate Selection Failure: Falls back to first N templates in order\nContent Generation Failure: Skips diagram, continues with next\nRendering Failure: Reports error, saves .mmd source for manual debugging\nMissing mmdc CLI: Exits early with installation instructions"
      },
      {
        "title": "Quality Validation",
        "body": "The validator checks each diagram for:\n\n✅ File readable and valid UTF-8\n✅ Theme configuration present\n✅ No unresolved placeholders ({{PLACEHOLDER}})\n✅ SVG file rendered\n✅ PNG file rendered\n✅ Syntax valid (can re-render without errors)\n\nValidation workflow:\n\n# Generate diagrams\nnode scripts/generate.mjs --content content.json --out diagrams/chapter-01\n\n# Validate output\nnode scripts/validate.mjs --dir diagrams/chapter-01\n\n# Fix any failures and re-run"
      },
      {
        "title": "Cost Analysis",
        "body": "Per Chapter (3 diagrams):\n\nSubagent LLM usage:\n\nChapter reading: ~3000 tokens input\nTemplate selection: ~500 tokens output\nContent generation (3 diagrams): ~1500 tokens output\nTotal: 5000 tokens ($0.002)\n\n\nRendering: Free (local mmdc)\n\nAt scale (e.g. 14 chapters × 3 diagrams = 42 diagrams):\n\n14 × $0.002 = ~$0.03 total\n\nComparison to AI image generation (42 images):\n\nMermaid diagrams: ~$0.03\nGLM images: ~$0.63\nDALL-E images: ~$2.52\nSavings: 95-99% vs AI image generation"
      },
      {
        "title": "Modify Color Scheme",
        "body": "Edit theme variables in any template file (assets/*.mmd):\n\n%%{init: {'theme':'base', 'themeVariables': {\n  'primaryColor':'#NEW_COLOR',\n  'secondaryColor':'#NEW_COLOR',\n  ...\n}}}%%"
      },
      {
        "title": "Add New Template",
        "body": "Create assets/new-template.mmd with theme and placeholders\nAdd entry to TEMPLATES object in scripts/generate.mjs:\n\nconst TEMPLATES = {\n  ...\n  \"new-template\": \"Description of when to use this template\",\n};\n\nTest with content:\n\nnode scripts/generate.mjs --content test-content.json --out test-output"
      },
      {
        "title": "Troubleshooting",
        "body": "\"mmdc not found\"\n\nInstall: npm install -g @mermaid-js/mermaid-cli\nVerify: which mmdc\n\n\"Template not found\"\n\nCheck template name in content.json matches file in assets/ (case-sensitive)\nAvailable templates: architecture, flowchart, sequence, concept-map, radial-concept, timeline, comparison, comparison-table, gantt, mindmap, class-diagram, state-diagram\n\n\"Rendering failed\"\n\nCheck .mmd file for syntax errors\nManually test: mmdc -i diagram.mmd -o test.svg\nValidate with: node scripts/validate.mjs --dir output_dir\n\nUnresolved placeholders in output ({{PLACEHOLDER}})\n\nSubagent didn't generate all required placeholder values\nCheck template file to see required placeholders\nManually add missing values to content.json and re-run generate.mjs\n\nSubagent failed\n\nCheck chapter file path is correct\nVerify skill path is accessible from subagent\nEnsure mmdc is installed globally (subagent needs it too)"
      },
      {
        "title": "Generated Architecture Diagram",
        "body": "%%{init: {'theme':'base', ...}}%%\ngraph TB\n    subgraph \"Agent System\"\n        Gateway[Gateway Process]\n        Session[Session Manager]\n        Tools[Tool Registry]\n    end\n\n    User((User))\n    Provider((LLM Provider))\n\n    User -->|Request| Gateway\n    Gateway -->|Route| Session\n    Session -->|Select Tool| Tools\n    Tools -->|Execute| Provider\n\nOutput: Clean, consistent, professional diagram with uniform styling across all chapters."
      },
      {
        "title": "Best Practices",
        "body": "Consistent counts: Use same --max value for all chapters (e.g., 3)\nReview before commit: Run validator on all outputs before pushing\nVersion control: Commit both .mmd source and .svg/.png renders\nIterate templates: If diagrams look wrong, adjust template then regenerate\nManual touch-ups: Edit .mmd files directly for fine-tuning, then re-render with mmdc"
      },
      {
        "title": "Installation Test",
        "body": "./scripts/install-deps.sh\n\nVerifies that mermaid-cli is installed and meets version requirements."
      },
      {
        "title": "Functional Test",
        "body": "Create test content: assets/example-content.json (already included)\nGenerate diagrams: node scripts/generate.mjs --content assets/example-content.json --out test-output\nValidate output: node scripts/validate.mjs --dir test-output\nVerify all checks pass"
      },
      {
        "title": "Local Documentation",
        "body": "Mermaid Syntax Guide: references/mermaid-syntax.md - Quick reference for diagram syntax, theming, and common patterns\nExample Content: assets/example-content.json - Real-world content structure example"
      },
      {
        "title": "External Resources",
        "body": "Mermaid Docs: https://mermaid.js.org/\nSyntax Reference: https://mermaid.js.org/intro/syntax-reference.html\nTheming Guide: https://mermaid.js.org/config/theming.html\nCLI Documentation: https://github.com/mermaid-js/mermaid-cli\nLive Editor: https://mermaid.live/ (interactive testing)"
      }
    ],
    "body": "Mermaid Diagrams\n\nGenerate professional, consistently-styled Mermaid diagrams for technical content with automatic template selection, content generation, and quality validation.\n\nQuick Start\n\nSubagent Pattern (Recommended):\n\nWhen user requests diagram generation, spawn a subagent:\n\nGenerate 3 Mermaid diagrams for /path/to/chapter-01.md and save to diagrams/chapter-01/\n\n\nThe subagent will:\n\nRead chapter content\nSelect appropriate templates\nGenerate placeholder content\nCreate content.json\nRun generation script\nValidate output\n\nManual Pattern:\n\n# 1. Create content.json (see assets/example-content.json)\n# 2. Render diagrams\nnode scripts/generate.mjs --content content.json --out diagrams/chapter-01\n\n# 3. Validate\nnode scripts/validate.mjs --dir diagrams/chapter-01\n\nPrerequisites\nAutomated Installation (Recommended)\n\nRun the installation script to automatically install and verify mermaid-cli:\n\ncd $SKILL_DIR  # Path to skill-mermaid-diagrams directory\n./scripts/install-deps.sh\n\n\nThe script will:\n\nCheck Node.js version (>= 18.0.0 required)\nInstall or upgrade mermaid-cli to latest version\nVerify installation and version compatibility\nProvide troubleshooting guidance if needed\nManual Installation\n\nAlternatively, install Mermaid CLI globally:\n\nnpm install -g @mermaid-js/mermaid-cli\n\n\nVerify installation:\n\nmmdc --version  # Should be >= 11.0.0\n\nUsage Patterns\nSubagent Workflow (Primary Pattern)\n\nWhen a user requests diagram generation, spawn a subagent to handle the complete workflow:\n\nTask: Generate 3 Mermaid diagrams for chapter 5\n\nSteps:\n1. Read $CONTENT_DIR/chapters/chapter-05.md\n2. Analyze content and select 3 appropriate diagram templates from: architecture, flowchart, sequence, concept-map, timeline, comparison\n3. For each selected template:\n   - Read template from $SKILL_DIR/assets/\n   - Extract placeholders ({{PLACEHOLDER_NAME}} format)\n   - Generate concise labels (max 8 words each) based on chapter content\n4. Create content.json with structure:\n   {\n     \"chapter\": \"chapter-05.md\",\n     \"diagrams\": [\n       {\n         \"template\": \"architecture\",\n         \"placeholders\": { \"SYSTEM_NAME\": \"...\", ... }\n       },\n       ...\n     ]\n   }\n5. Save to $CONTENT_DIR/diagrams/chapter-05/content.json\n6. Run: node $SKILL_DIR/scripts/generate.mjs --content content.json --out $CONTENT_DIR/diagrams/chapter-05\n7. Validate: node $SKILL_DIR/scripts/validate.mjs --dir $CONTENT_DIR/diagrams/chapter-05\n8. Report success with file count\n\nNote: Replace $SKILL_DIR and $CONTENT_DIR with actual paths:\n- SKILL_DIR: Path to skill-mermaid-diagrams directory\n- CONTENT_DIR: Path to your content/project directory\n\nManual Content Generation\n\nIf generating content.json manually:\n\n# 1. Create content.json (see assets/example-content.json)\n# 2. Render\ncd $SKILL_DIR  # Path to skill-mermaid-diagrams directory\nnode scripts/generate.mjs \\\n  --content /path/to/content.json \\\n  --out /path/to/output\n\n# 3. Validate\nnode scripts/validate.mjs --dir /path/to/output\n\n\nParameters:\n\n--content / -c: Content JSON file (required)\n--out / -o: Output directory (default: ./diagrams)\nValidate All Generated Diagrams\nfor dir in diagrams/chapter-*/; do\n  node scripts/validate.mjs --dir \"$dir\"\ndone\n\nAvailable Templates\n\nThe skill includes 12 professionally-themed templates with consistent color schemes:\n\narchitecture.mmd - System architecture, component diagrams, tool integration\n\nUse for: System components, tool pipelines, agent interactions\nFixed node IDs (space-safe): Uses C1, C2, C3 internally, only labels are customizable\n\nflowchart.mmd - Decision flows, processes, workflows, debugging steps\n\nUse for: Decision trees, process flows, validation workflows\n\nsequence.mmd - Actor interactions, message passing, session patterns\n\nUse for: API call sequences, actor communication, message flows\n\nconcept-map.mmd - Key concepts, mental models, paradigms, relationships\n\nUse for: Hierarchical concepts, mental models, knowledge graphs\nImproved version (graph-based, not mindmap): Full color control, readable text\n\nradial-concept.mmd - Layered concepts radiating from center - Use for: Progressive summarization, abstraction layers, hierarchical models\n\n4 color-coded levels: green → orange → blue → purple\n\ntimeline.mmd - Temporal progression, optimization stages, evolution\n\nUse for: Project phases, evolution timelines, staged processes\n\ncomparison.mmd - Trade-offs, quadrant analysis (2D plotting)\n\nUse for: Cost vs performance, effort vs impact (X/Y coordinate plotting)\nRequires X/Y coordinates for items\n\ncomparison-table.mmd - Side-by-side feature comparison\n\nUse for: AI vs Script decisions, option comparisons, feature matrices\nAlternative to quadrant when you need simple side-by-side, not 2D plotting\n\ngantt.mmd - Project timelines, task scheduling - Use for: Project planning, milestone tracking, task dependencies\n\nSupports: Multiple sections, task status (done/active/crit), date ranges\n\nmindmap.mmd - Organic radial mind maps - Use for: Brainstorming, organic thought structures, free-form concept mapping\n\nLimitation: Auto-assigns colors/text (limited theme control)\nAlternative: Use radial-concept.mmd for better color control\n\nclass-diagram.mmd - UML class diagrams\n\nUse for: Object models, database schemas, system architecture (OOP)\nSupports: Attributes, methods, relationships (inheritance, composition, association)\n\nstate-diagram.mmd - State machines, lifecycle diagrams\n\nUse for: Process states, object lifecycles, workflow stages\nSupports: Transitions with labels, notes on states, start/end markers\nTemplate Placeholder Reference\n\nEach template requires specific placeholders. All placeholders must be provided to avoid rendering errors.\n\nTemplate\tPlaceholders\tComplexity\tRequired Fields\narchitecture\t10\tMedium\tSYSTEM_NAME, COMPONENT_1-3_LABEL, EXTERNAL_1-2_LABEL, FLOW_1-4\nflowchart\t11\tMedium\tSTART_LABEL, DECISION_1-2, ACTION_1-4, CHOICE_1-2_YES/NO, END_LABEL\nsequence\t8\tMedium\tACTOR_1-3, MESSAGE_1-5\nconcept-map\t15\tHigh\tCENTRAL_CONCEPT, BRANCH_1-4, BRANCH_X_SUB_1-3\nradial-concept\t13\tMedium\tCENTRAL_CONCEPT, LEVEL_1-4_LABEL, LEVEL_X_NODE_1-3\ntimeline\t6\tLow\tEVENT_1-6, DATE_1-6\ncomparison\t18\tHigh\tCOMPARISON_TITLE, X/Y_AXIS_LOW/HIGH, QUADRANT_1-4_LABEL, ITEM_1-5 + X/Y coords\ncomparison-table\t10\tLow\tOPTION_1-2_TITLE, OPTION_X_CRITERION_1-4\ngantt\t14\tHigh\tCHART_TITLE, SECTION_1-3_TITLE, TASK_X_Y (name/id/start/duration)\nmindmap\t13\tMedium\tROOT_CONCEPT, BRANCH_1-4, BRANCH_X_CHILD_1-3\nclass-diagram\t21\tHigh\tCLASS_1-3_NAME, CLASS_X_ATTR_1-3, CLASS_X_METHOD_1-3, REL_1-3_TYPE/LABEL\nstate-diagram\t18\tMedium\tSTATE_1-8, TRANSITION_1-7_LABEL, STATE_1/4/7_NOTE\n\nImportant Notes:\n\narchitecture.mmd: Uses fixed node IDs (C1, C2, C3, E1, E2) internally. Only *_LABEL placeholders are customizable. Labels can contain spaces (space-safe).\nconcept-map.mmd: Improved graph-based version (replaced mindmap). Better color control and readability.\ncomparison.mmd: QuadrantChart requires X/Y coordinates. Use comparison-table.mmd for simple side-by-side comparisons.\ngantt.mmd: Task status options: done, active, crit, or blank. Date format: YYYY-MM-DD. Duration: Nd (days) or YYYY-MM-DD.\nmindmap.mmd: Limited theme control (auto-colors, auto-text). For controlled colors/text, use radial-concept.mmd instead.\nclass-diagram.mmd: Relationship types: <|-- (inheritance), *-- (composition), o-- (aggregation), --> (association), ..> (dependency).\nstate-diagram.mmd: Uses stateDiagram-v2 syntax. States are simple identifiers (no spaces). Notes attach to states 1, 4, and 7.\nText length limits: Generator warns if labels exceed recommended length (25-50 chars depending on template).\n\nPlaceholder Naming Convention:\n\nComponent labels: COMPONENT_1_LABEL, COMPONENT_2_LABEL\nBranch hierarchy: BRANCH_1, BRANCH_1_SUB_1, BRANCH_1_SUB_2\nLevel-based: LEVEL_1_LABEL, LEVEL_1_NODE_1\nChangelog & Migration Notes\nv2.0 (2026-02-15) - Root Cause Fixes\n\nBreaking Changes:\n\narchitecture.mmd - Fixed node ID handling (space-safe)\n\nBefore: Used placeholder values as node IDs → failed when labels contained spaces\nAfter: Uses fixed node IDs (C1, C2, C3) → labels can contain any characters\nMigration: Remove COMPONENT_1, COMPONENT_2, COMPONENT_3 from content.json (only *_LABEL variants needed)\n\nconcept-map.mmd - Replaced mindmap with graph-based version\n\nBefore: Mindmap syntax with auto-colors, black-on-purple text (unreadable)\nAfter: Graph LR syntax with explicit styling, white text on dark backgrounds\nResult: +100% contrast improvement (2.6:1 → 5.2:1 on purple nodes) New Features:\nradial-concept.mmd - Progressive summarization diagrams with 4 color-coded levels\ncomparison-table.mmd - Side-by-side feature comparison (alternative to quadrant chart)\nValidation - Generator now warns about text length, unresolved placeholders, special characters\n\nAll changes target root causes (template design flaws, missing validation) rather than surface symptoms.\n\nColor Scheme (Consistent Across All Templates)\nPrimary Blue: #4A90E2 - Main components, actions\nSecondary Purple: #7B68EE - Supporting elements\nTertiary Green: #90EE90 - External actors, success states\nWarning Yellow: #FFD700 - Decisions, cautions\nError Red: #FF6B6B - Failures, critical paths\nOutput Structure\n\nAfter generation, each chapter directory contains:\n\ndiagrams/chapter-01/\n├── diagram-01-architecture.mmd   # Mermaid source\n├── diagram-01-architecture.svg   # Vector output\n├── diagram-01-architecture.png   # Raster output (1200px wide)\n├── diagram-02-flowchart.mmd\n├── diagram-02-flowchart.svg\n├── diagram-02-flowchart.png\n├── diagram-03-concept-map.mmd\n├── diagram-03-concept-map.svg\n├── diagram-03-concept-map.png\n└── summary.json                   # Generation metadata\n\nError Handling\n\nThe generator includes robust error handling:\n\nTemplate Selection Failure: Falls back to first N templates in order\nContent Generation Failure: Skips diagram, continues with next\nRendering Failure: Reports error, saves .mmd source for manual debugging\nMissing mmdc CLI: Exits early with installation instructions\nQuality Validation\n\nThe validator checks each diagram for:\n\n✅ File readable and valid UTF-8\n✅ Theme configuration present\n✅ No unresolved placeholders ({{PLACEHOLDER}})\n✅ SVG file rendered\n✅ PNG file rendered\n✅ Syntax valid (can re-render without errors)\n\nValidation workflow:\n\n# Generate diagrams\nnode scripts/generate.mjs --content content.json --out diagrams/chapter-01\n\n# Validate output\nnode scripts/validate.mjs --dir diagrams/chapter-01\n\n# Fix any failures and re-run\n\nCost Analysis\n\nPer Chapter (3 diagrams):\n\nSubagent LLM usage:\nChapter reading: ~3000 tokens input\nTemplate selection: ~500 tokens output\nContent generation (3 diagrams): ~1500 tokens output\nTotal: 5000 tokens ($0.002)\nRendering: Free (local mmdc)\n\nAt scale (e.g. 14 chapters × 3 diagrams = 42 diagrams):\n\n14 × $0.002 = ~$0.03 total\n\nComparison to AI image generation (42 images):\n\nMermaid diagrams: ~$0.03\nGLM images: ~$0.63\nDALL-E images: ~$2.52\nSavings: 95-99% vs AI image generation\nCustomization\nModify Color Scheme\n\nEdit theme variables in any template file (assets/*.mmd):\n\n%%{init: {'theme':'base', 'themeVariables': {\n  'primaryColor':'#NEW_COLOR',\n  'secondaryColor':'#NEW_COLOR',\n  ...\n}}}%%\n\nAdd New Template\nCreate assets/new-template.mmd with theme and placeholders\nAdd entry to TEMPLATES object in scripts/generate.mjs:\nconst TEMPLATES = {\n  ...\n  \"new-template\": \"Description of when to use this template\",\n};\n\nTest with content:\nnode scripts/generate.mjs --content test-content.json --out test-output\n\nTroubleshooting\n\n\"mmdc not found\"\n\nInstall: npm install -g @mermaid-js/mermaid-cli\nVerify: which mmdc\n\n\"Template not found\"\n\nCheck template name in content.json matches file in assets/ (case-sensitive)\nAvailable templates: architecture, flowchart, sequence, concept-map, radial-concept, timeline, comparison, comparison-table, gantt, mindmap, class-diagram, state-diagram\n\n\"Rendering failed\"\n\nCheck .mmd file for syntax errors\nManually test: mmdc -i diagram.mmd -o test.svg\nValidate with: node scripts/validate.mjs --dir output_dir\n\nUnresolved placeholders in output ({{PLACEHOLDER}})\n\nSubagent didn't generate all required placeholder values\nCheck template file to see required placeholders\nManually add missing values to content.json and re-run generate.mjs\n\nSubagent failed\n\nCheck chapter file path is correct\nVerify skill path is accessible from subagent\nEnsure mmdc is installed globally (subagent needs it too)\nExamples\nGenerated Architecture Diagram\n%%{init: {'theme':'base', ...}}%%\ngraph TB\n    subgraph \"Agent System\"\n        Gateway[Gateway Process]\n        Session[Session Manager]\n        Tools[Tool Registry]\n    end\n\n    User((User))\n    Provider((LLM Provider))\n\n    User -->|Request| Gateway\n    Gateway -->|Route| Session\n    Session -->|Select Tool| Tools\n    Tools -->|Execute| Provider\n\n\nOutput: Clean, consistent, professional diagram with uniform styling across all chapters.\n\nBest Practices\nConsistent counts: Use same --max value for all chapters (e.g., 3)\nReview before commit: Run validator on all outputs before pushing\nVersion control: Commit both .mmd source and .svg/.png renders\nIterate templates: If diagrams look wrong, adjust template then regenerate\nManual touch-ups: Edit .mmd files directly for fine-tuning, then re-render with mmdc\nTesting\nInstallation Test\n./scripts/install-deps.sh\n\n\nVerifies that mermaid-cli is installed and meets version requirements.\n\nFunctional Test\nCreate test content: assets/example-content.json (already included)\nGenerate diagrams: node scripts/generate.mjs --content assets/example-content.json --out test-output\nValidate output: node scripts/validate.mjs --dir test-output\nVerify all checks pass\nReferences\nLocal Documentation\nMermaid Syntax Guide: references/mermaid-syntax.md - Quick reference for diagram syntax, theming, and common patterns\nExample Content: assets/example-content.json - Real-world content structure example\nExternal Resources\nMermaid Docs: https://mermaid.js.org/\nSyntax Reference: https://mermaid.js.org/intro/syntax-reference.html\nTheming Guide: https://mermaid.js.org/config/theming.html\nCLI Documentation: https://github.com/mermaid-js/mermaid-cli\nLive Editor: https://mermaid.live/ (interactive testing)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/chunhualiao/skill-mermaid-diagrams",
    "publisherUrl": "https://clawhub.ai/chunhualiao/skill-mermaid-diagrams",
    "owner": "chunhualiao",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams",
    "downloadUrl": "https://openagent3.xyz/downloads/skill-mermaid-diagrams",
    "agentUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent",
    "manifestUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/skill-mermaid-diagrams/agent.md"
  }
}