Skip to content
Back to search

design-doc-mermaid

design-doc-mermaid Claude Skill

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spillwavesolutions--design-doc-mermaid/badge.svg)](/listings/spillwavesolutions--design-doc-mermaid)

HTML

<a href="/listings/spillwavesolutions--design-doc-mermaid"><img src="/api/listings/spillwavesolutions--design-doc-mermaid/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One-Click Install via Skilz Marketplace

Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Manual Installation

Clone directly into your Claude Code skills directory:

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verify Installation

After installation, verify the skill is available:

# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 519 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: design-doc-mermaid
  3. 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.
  4. ---
  5. # Mermaid Architect - Hierarchical Diagram and Documentation Skill
  6. Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities.
  7. ## Table of Contents
  8. - [Decision Tree](#decision-tree)
  9. - [GitHub wiki, WikiTicket, and Confluence](#github-wiki-wikiticket-and-confluence)
  10. - [Available Guides and Resources](#available-guides-and-resources)
  11. - [Usage Patterns](#usage-patterns)
  12. - [Resilient Workflow](#resilient-workflow)
  13. - [Unicode Semantic Symbols](#unicode-semantic-symbols)
  14. - [Python Utilities](#python-utilities)
  15. - [Decision Tree Examples](#decision-tree-examples)
  16. - [High-Contrast Styling](#high-contrast-styling)
  17. - [File Organization](#file-organization)
  18. - [Workflow Summary](#workflow-summary)
  19. - [When to Use What](#when-to-use-what)
  20. - [Best Practices](#best-practices)
  21. - [Learning Path](#learning-path)
  22. ## Decision Tree
  23. **How this skill works:**
  24. 1. **User makes a request** → Skill analyzes intent
  25. 2. **Skill determines diagram/document type** → Loads appropriate guide(s)
  26. 3. **AI reads specialized guide** → Generates diagram/document using templates
  27. 4. **Result delivered** → With validation and export options
  28. **User Intent Analysis:**
  29. ```mermaid
  30. flowchart TD
  31. Start([User Request]) --> Analyze{Analyze Intent}
  32. Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md]
  33. Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md]
  34. Analyze -->|"system architecture, components"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md]
  35. Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md]
  36. Analyze -->|"class, ER, state, wiki, walkthrough"| WikiGuide[Load WikiTicket GitHub Guide<br/>references/guides/wiki-ticket-and-github.md]
  37. Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/]
  38. Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md]
  39. Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md]
  40. Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]
  41. Activity --> Generate[Generate Diagram]
  42. Deploy --> Generate
  43. Arch --> Generate
  44. Sequence --> Generate
  45. WikiGuide --> Generate
  46. CodeToDiag --> Generate
  47. DesignDoc --> Generate
  48. Unicode --> Generate
  49. Scripts --> Execute[Execute Script]
  50. Generate --> Validate{Validate?}
  51. Validate -->|Yes| RunValidation[Run mmdc validation]
  52. Validate -->|No| Output
  53. RunValidation --> Output[Output Result]
  54. Execute --> Output
  55. classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
  56. classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
  57. classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
  58. class Analyze,Validate decision
  59. class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
  60. class Generate,Execute,RunValidation,Output action
  61. ```
  62. ## Available Guides and Resources
  63. ### Diagram Type Guides (`references/guides/diagrams/`)
  64. | Guide | Full Path | Load When User Wants | Examples |
  65. |-------|-----------|---------------------|----------|
  66. | 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" |
  67. | Deployment Diagrams | `references/guides/diagrams/deployment-diagrams.md` | Infrastructure, cloud architecture, K8s, serverless, network topology | "Show AWS architecture", "Document GCP deployment", "Create K8s diagram" |
  68. | Architecture Diagrams | `references/guides/diagrams/architecture-diagrams.md` | System architecture, component design, high-level structure | "Show system components", "Document microservices", "Architecture overview" |
  69. | Sequence Diagrams | `references/guides/diagrams/sequence-diagrams.md` | API interactions, service communication, request/response flows | "Show API call sequence", "Document auth flow", "Service interactions" |
  70. | WikiTicket / GitHub / Confluence | `references/guides/wiki-ticket-and-github.md` | Design docs, walkthroughs, requirements, wiki publish, Confluence images | "architecture doc", "code walkthrough", "wiki", "Confluence" |
  71. 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`.
  72. ### Code-to-Diagram Guide & Examples
  73. | Resource | Full Path | What It Provides |
  74. |----------|-----------|------------------|
  75. | **Master Guide** | `references/guides/code-to-diagram/README.md` | Complete workflow for analyzing any codebase and extracting diagrams |
  76. | **Spring Boot** | `examples/spring-boot/README.md` | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic |
  77. | **FastAPI** | `examples/fastapi/README.md` | Python async patterns, Pydantic models, dependency injection, cloud deployment |
  78. | **React** | `examples/react/README.md` | Component hierarchy, state management, data flow, build pipeline |
  79. | **Python ETL** | `examples/python-etl/README.md` | Data pipeline, transformation steps, error handling, scheduling |
  80. | **Node/Express** | `examples/node-webapp/README.md` | Middleware chain, route handlers, async patterns, deployment |
  81. | **Java Web App** | `examples/java-webapp/README.md` | Traditional MVC, servlet containers, WAR deployment |
  82. ### Design Document Templates
  83. | Template | Full Path | Use For | Load When |
  84. |----------|-----------|---------|-----------|
  85. | Architecture Design | `assets/architecture-design-template.md` | System-wide architecture | "Create architecture doc", "Document system design" |
  86. | API Design | `assets/api-design-template.md` | API specifications | "API design doc", "Document REST API" |
  87. | Feature Design | `assets/feature-design-template.md` | Feature planning | "Feature design", "Plan new feature" |
  88. | Database Design | `assets/database-design-template.md` | Database schema | "Database design", "Document schema" |
  89. | System Design | `assets/system-design-template.md` | Complete system | "System design doc", "Full system documentation" |
  90. ### Unicode Symbols Guide
  91. **Full Path:** `references/guides/unicode-symbols/guide.md`
  92. **Load when user mentions:** "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols"
  93. **Quick Reference:**
  94. - 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️
  95. - ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
  96. - 💾 Data: 💾 📦 📊 📈 🗃️ 🧊
  97. - 📨 Messaging: 📨 📬 📤 📥 🐰 📢
  98. - 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫
  99. - 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌
  100. ### Python Scripts (`scripts/`)
  101. | Script | Use For | Load When |
  102. |--------|---------|-----------|
  103. | `extract_mermaid.py` | Extract diagrams from Markdown, validate syntax, replace with images | "extract diagrams", "validate mermaid", "find all diagrams" |
  104. | `mermaid_to_image.py` | Convert .mmd to PNG/SVG, batch conversion, custom themes | "convert to image", "render diagram", "create PNG" |
  105. | `resilient_diagram.py` | Full workflow: save .mmd, generate image, validate, error recovery | "generate diagram", "create diagram with validation", "resilient diagram" |
  106. ## GitHub wiki, WikiTicket, and Confluence
  107. Load `references/guides/wiki-ticket-and-github.md` for WikiTicket design docs,
  108. code walkthroughs, requirements, GitHub wiki, or Confluence.
  109. | Target | What to ship |
  110. |--------|----------------|
  111. | GitHub wiki / GFM | Fenced `mermaid` block. GitHub renders class, ER, state, sequence, flowchart, C4. |
  112. | 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. |
  113. PlantUML is opt-in for Salt wireframes, use case, timing, ArchiMate, nwdiag, and WBS. Those always ship as PNG or SVG.
  114. ## Usage Patterns
  115. Common request patterns and guide selection. See [When to Use What](#when-to-use-what) for complete mapping.
  116. | Pattern | Example Request | Guides to Load |
  117. |---------|-----------------|----------------|
  118. | Single Diagram | "Create activity diagram for login flow" | Diagram type guide + Unicode symbols |
  119. | Code-to-Diagram | "Generate deployment from application.yml" | Framework example + Deployment guide |
  120. | Design Document | "Create API design document" | Template from assets/ + Relevant diagram guides |
  121. | Extract/Validate | "Extract diagrams from design.md" | Use `scripts/extract_mermaid.py` |
  122. | Batch Convert | "Convert all .mmd to PNG" | Use `scripts/mermaid_to_image.py` |
  123. ## Resilient Workflow
  124. **CRITICAL:** This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization.
  125. **Full Guide:** `references/guides/resilient-workflow.md`
  126. ### Workflow Overview
  127. ```mermaid
  128. flowchart LR
  129. A[1. Identify Type] --> B[2. Save .mmd + Image]
  130. B --> C{3. Valid?}
  131. C -->|Yes| D[4. Add to Markdown]
  132. C -->|No| E[5. Error Recovery]
  133. E --> F{Fix Found?}
  134. F -->|Yes| A
  135. F -->|No| G[Search External]
  136. G --> A
  137. classDef step fill:#90EE90,stroke:#333,color:darkgreen
  138. classDef decision fill:#FFD700,stroke:#333,color:black
  139. class A,B,D,E,G step
  140. class C,F decision
  141. ```
  142. ### Key Principle
  143. **NEVER add a diagram to markdown until it passes validation.** This prevents broken diagrams in documentation.
  144. ### Using the Script (Recommended)
  145. ```bash
  146. # Generate with full error recovery
  147. python scripts/resilient_diagram.py \
  148. --code "flowchart TD; A-->B" \
  149. --markdown-file design_doc \
  150. --diagram-num 1 \
  151. --title "process_flow" \
  152. --format png \
  153. --json
  154. ```
  155. **Output:** Both `.mmd` and `.png` files in `./diagrams/` directory.
  156. ### File Naming Convention
  157. ```
  158. ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
  159. ./diagrams/<markdown_file>_<num>_<type>_<title>.png
  160. ```
  161. **Example:** `./diagrams/api_design_01_sequence_auth_flow.png`
  162. ### Error Recovery Priority
  163. When validation fails, the workflow automatically:
  164. 1. **Check troubleshooting guide** - `references/guides/troubleshooting.md` (28 documented errors)
  165. 2. **Search with perplexity** - `perplexity_ask` MCP for syntax questions
  166. 3. **Search with brave** - `brave_web_search` MCP for recent solutions
  167. 4. **Ask gemini** - `gemini` skill for alternative perspective
  168. 5. **General search** - `WebSearch` tool as fallback
  169. ### Manual Fallback Steps
  170. If the script is unavailable:
  171. 1. **Identify diagram type** from first line (flowchart, sequence, etc.)
  172. 2. **Load reference guide** from `references/guides/diagrams/`
  173. 3. **Save to** `./diagrams/<markdown_file>_<num>_<type>_<title>.mmd`
  174. 4. **Validate:** `mmdc -i file.mmd -o file.png -b transparent`
  175. 5. **On error:** Search `references/guides/troubleshooting.md` for matching error
  176. 6. **If not found:** Use search tools in priority order above
  177. 7. **Add reference:** `![Description](./diagrams/filename.png)`
  178. ### Pattern 6: Resilient Diagram Generation
  179. **User:** "Create a sequence diagram and add it to the design doc"
  180. **Skill Actions:**
  181. 1. Identify intent: **diagram generation** + **markdown integration**
  182. 2. Load workflow guide: `references/guides/resilient-workflow.md`
  183. 3. Identify diagram type: **sequence**
  184. 4. Load diagram guide: `references/guides/diagrams/sequence-diagrams.md`
  185. 5. Generate Mermaid code using templates
  186. 6. Execute resilient workflow:
  187. ```bash
  188. python scripts/resilient_diagram.py \
  189. --code "[generated code]" \
  190. --markdown-file design_doc \
  191. --diagram-num 1 \
  192. --title "api_sequence" \
  193. --json
  194. ```
  195. 7. If validation fails → Apply troubleshooting fix → Retry
  196. 8. On success → Add `![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png)` to markdown
  197. ## Unicode Semantic Symbols
  198. Always use Unicode symbols to enhance diagram clarity. Common patterns:
  199. ### Infrastructure & Deployment
  200. ```mermaid
  201. graph TB
  202. Client[👤 User] --> LB[🌐 Load Balancer]
  203. LB --> App1[⚙️ App Server 1]
  204. LB --> App2[⚙️ App Server 2]
  205. App1 --> DB[(💾 Database)]
  206. App1 --> Cache[(⚡ Redis)]
  207. ```
  208. ### Activity Flow with States
  209. ```mermaid
  210. flowchart TD
  211. Start([🚀 Start]) --> Process[⚙️ Process Data]
  212. Process --> Check{✓ Valid?}
  213. Check -->|Yes| Save[💾 Save]
  214. Check -->|No| Error[❌ Error]
  215. Save --> Complete([✅ Complete])
  216. ```
  217. ### Microservices Architecture
  218. ```mermaid
  219. graph TB
  220. API[🌐 API Gateway] --> Auth[🔐 Auth Service]
  221. API --> Orders[📋 Order Service]
  222. Orders --> Queue[📬 Message Queue]
  223. Queue --> Worker[⚙️ Background Worker]
  224. Worker --> Storage[📦 Object Storage]
  225. ```
  226. **For complete symbol reference, load:** `references/guides/unicode-symbols/guide.md`
  227. ## Python Utilities
  228. ### Extract Mermaid Diagrams
  229. ```bash
  230. # List all diagrams
  231. python scripts/extract_mermaid.py document.md --list-only
  232. # Extract to separate files
  233. python scripts/extract_mermaid.py document.md --output-dir diagrams/
  234. # Validate all diagrams
  235. python scripts/extract_mermaid.py document.md --validate
  236. # Replace with image references (for Confluence upload)
  237. python scripts/extract_mermaid.py document.md --replace-with-images \
  238. --image-format png --output-markdown output.md
  239. ```
  240. ### Convert to Images
  241. ```bash
  242. # Single conversion
  243. python scripts/mermaid_to_image.py diagram.mmd output.png
  244. # With custom settings
  245. python scripts/mermaid_to_image.py diagram.mmd output.svg \
  246. --theme dark --background white --width 1200
  247. # Batch convert directory
  248. python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive
  249. # From stdin
  250. echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
  251. ```
  252. ## Decision Tree Examples
  253. ### Example 1: User Asks for Workflow Diagram
  254. **Input:** "Show the checkout process workflow"
  255. **Skill Decision Path:**
  256. ```
  257. 1. Analyze: workflow, process → ACTIVITY DIAGRAM
  258. 2. Load guide: guides/diagrams/activity-diagrams.md
  259. 3. Find pattern: E-commerce checkout (template exists in guide)
  260. 4. Generate using template + Unicode symbols
  261. 5. Output activity diagram with decision points
  262. ```
  263. **Output:** Complete activity diagram with Unicode symbols for cart, payment, order states.
  264. ### Example 2: User Provides Spring Boot Code
  265. **Input:** "Here's my Spring Boot controller, create diagrams"
  266. **Skill Decision Path:**
  267. ```
  268. 1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT
  269. 2. Load guides:
  270. - examples/spring-boot/README.md
  271. - guides/diagrams/architecture-diagrams.md (for structure)
  272. - guides/diagrams/sequence-diagrams.md (for method calls)
  273. - guides/diagrams/activity-diagrams.md (for business logic)
  274. 3. Generate multiple diagrams:
  275. a. Architecture diagram from @RestController/@Service/@Repository annotations
  276. b. Sequence diagram from method call chain
  277. c. Activity diagram from business logic flow
  278. 4. Output all diagrams with explanations
  279. ```
  280. **Output:** 3-4 diagrams showing different views of the Spring Boot application.
  281. ### Example 3: User Wants Infrastructure Documentation
  282. **Input:** "Document my GCP Cloud Run deployment with AlloyDB"
  283. **Skill Decision Path:**
  284. ```
  285. 1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM
  286. 2. Load guides:
  287. - guides/diagrams/deployment-diagrams.md
  288. - examples/spring-boot/ or examples/fastapi/ (if code provided)
  289. 3. Check for IaC files (Pulumi, Terraform, docker-compose)
  290. 4. Generate deployment diagram with:
  291. - Cloud Run services with specs
  292. - VPC connector
  293. - AlloyDB cluster
  294. - Security (IAM, Secret Manager)
  295. - Monitoring
  296. 5. Apply Unicode symbols for clarity
  297. 6. Output with resource specifications
  298. ```
  299. **Output:** Complete GCP deployment diagram with all resources labeled.
  300. ## High-Contrast Styling
  301. **ALL diagrams MUST use high-contrast colors:**
  302. ```mermaid
  303. graph TB
  304. classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
  305. classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
  306. classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
  307. classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black
  308. %% Every classDef MUST have color: property
  309. ```
  310. **Rules:**
  311. - Light background → Dark text color
  312. - Dark background → Light text color
  313. - Always specify `color:` in every `classDef`
  314. ## File Organization
  315. ```
  316. design-doc-mermaid/
  317. ├── SKILL.md # This file - Main orchestrator
  318. ├── README.md # User documentation
  319. ├── CLAUDE.md # Claude Code instructions
  320. │
  321. ├── references/ # Reference materials
  322. │ ├── mermaid-diagram-guide.md # Legacy general guide
  323. │ └── guides/ # Specialized guides (load on-demand)
  324. │ ├── diagrams/
  325. │ │ ├── activity-diagrams.md # Workflows, processes
  326. │ │ ├── deployment-diagrams.md # Infrastructure, cloud
  327. │ │ ├── architecture-diagrams.md # System architecture
  328. │ │ └── sequence-diagrams.md # API interactions
  329. │ ├── code-to-diagram/
  330. │ │ └── README.md # Master guide for code analysis
  331. │ ├── unicode-symbols/
  332. │ │ └── guide.md # Complete symbol reference
  333. │ └── troubleshooting.md # Common syntax errors & fixes
  334. │
  335. ├── assets/ # Design document templates
  336. │ ├── architecture-design-template.md
  337. │ ├── api-design-template.md
  338. │ ├── feature-design-template.md
  339. │ ├── database-design-template.md
  340. │ └── system-design-template.md
  341. │
  342. ├── scripts/ # Python utilities
  343. │ ├── extract_mermaid.py # Extract & validate diagrams
  344. │ └── mermaid_to_image.py # Convert to PNG/SVG
  345. │
  346. ├── examples/ # Language-specific patterns
  347. │ ├── spring-boot/ # Spring Boot patterns
  348. │ ├── fastapi/ # FastAPI patterns
  349. │ ├── react/ # React patterns
  350. │ ├── python-etl/ # Data pipeline patterns
  351. │ ├── node-webapp/ # Express.js patterns
  352. │ └── java-webapp/ # Traditional Java patterns
  353. │
  354. └── references/ # General Mermaid reference
  355. └── mermaid-diagram-guide.md # Complete Mermaid syntax guide
  356. ```
  357. ## Workflow Summary
  358. 1. **Analyze user intent** → Determine diagram type, document type, or action needed
  359. 2. **Load appropriate guide(s)** → Read only what's needed (token efficient)
  360. 3. **Apply templates and patterns** → Use examples from guides
  361. 4. **Generate output** → Create diagram or document
  362. 5. **Validate** (optional) → Use scripts to verify
  363. 6. **Convert** (optional) → Export to images if needed
  364. ## When to Use What
  365. | User Request | Load This |
  366. |--------------|-----------|
  367. | "activity diagram", "workflow", "process flow" | `references/guides/diagrams/activity-diagrams.md` |
  368. | "deployment", "infrastructure", "cloud", "k8s" | `references/guides/diagrams/deployment-diagrams.md` |
  369. | "architecture", "system design", "components" | `references/guides/diagrams/architecture-diagrams.md` + design template |
  370. | "API", "sequence", "interactions", "flow" | `references/guides/diagrams/sequence-diagrams.md` |
  371. | "class diagram", "ER", "state machine", "wiki", "walkthrough", "architecture doc" | `references/guides/wiki-ticket-and-github.md` plus the matching type guide |
  372. | "Confluence", "upload image", "PNG", "SVG" | `scripts/resilient_diagram.py` or `scripts/mermaid_to_image.py` |
  373. | "Spring Boot code" | `examples/spring-boot/` + relevant diagram guides |
  374. | "FastAPI code", "Python API" | `examples/fastapi/` + relevant diagram guides |
  375. | "React app", "frontend" | `examples/react/` + architecture guide |
  376. | "ETL", "data pipeline", "Python batch" | `examples/python-etl/` + activity guide |
  377. | "symbols", "unicode", "emoji" | `references/guides/unicode-symbols/guide.md` |
  378. | "syntax error", "diagram won't render", "troubleshoot" | `references/guides/troubleshooting.md` |
  379. | "extract diagrams" | `scripts/extract_mermaid.py` |
  380. | "convert to image", "PNG", "SVG" | `scripts/mermaid_to_image.py` |
  381. | "create diagram", "generate diagram", "add diagram to markdown" | `scripts/resilient_diagram.py` + `references/guides/resilient-workflow.md` |
  382. | "design document", "full docs" | `assets/*-design-template.md` + diagram guides |
  383. ## Best Practices
  384. 1. **Single Responsibility**: One diagram = One concept
  385. 2. **Unicode Enhancement**: Always use semantic symbols for clarity
  386. 3. **High Contrast**: Never skip the `color:` property in styles
  387. 4. **Validate Early**: Use scripts to catch syntax errors
  388. 5. **Template Reuse**: Leverage existing templates and examples
  389. 6. **Load On-Demand**: Only read guides needed for the specific request
  390. 7. **Token Efficiency**: Use hierarchical loading instead of reading everything
  391. ## Learning Path
  392. **New to Mermaid?** Start here:
  393. 1. Read `references/guides/unicode-symbols/guide.md` for symbol meanings
  394. 2. Read `references/guides/diagrams/activity-diagrams.md` for basic patterns
  395. 3. Try examples in `examples/spring-boot/` or `examples/fastapi/`
  396. 4. Use `scripts/extract_mermaid.py --validate` to check your work
  397. **Need to document code?** Follow this:
  398. 1. Identify your framework → Load relevant `examples/{framework}/`
  399. 2. Match code pattern to diagram type
  400. 3. Use templates from guide
  401. 4. Validate with scripts
  402. **Creating design docs?** Follow this:
  403. 1. Choose document type → Load template from `assets/`
  404. 2. Fill in text sections
  405. 3. Load diagram guides as needed for each section
  406. 4. Use Unicode symbols throughout
  407. 5. Save to `docs/design/` with timestamp
  408. ---
  409. **Version:** 2.0 (Hierarchical Architecture)
  410. **Last Updated:** 2025-01-13
  411. **Maintained by:** Claude Code Skills
README.md · README · 357 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Mermaid Architect - Comprehensive Diagram & Documentation Skill
  2. **Version 2.0** - Hierarchical architecture with intelligent orchestration
  3. A powerful Claude Code skill for creating Mermaid diagrams and design documents using on-demand guide loading, code-to-diagram generation, and Python utilities.
  4. ## Installation
  5. ### One-Click Install via Skilz Marketplace
  6. Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):
  7. ```bash
  8. skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
  9. ```
  10. ### Manual Installation
  11. Clone directly into your Claude Code skills directory:
  12. ```bash
  13. # Navigate to your skills directory
  14. cd ~/.claude/skills
  15. # Clone the repository
  16. git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
  17. ```
  18. ### Verify Installation
  19. After installation, verify the skill is available:
  20. ```bash
  21. # List installed skills
  22. ls ~/.claude/skills/design-doc-mermaid
  23. # Or ask Claude Code
  24. # "List my installed skills"
  25. ```
  26. ## What This Skill Does
  27. **Intelligent Diagram Generation:**
  28. - Activity diagrams (workflows, processes, business logic)
  29. - Deployment diagrams (cloud infrastructure, K8s, serverless)
  30. - Architecture diagrams (system components, microservices)
  31. - Sequence diagrams (API flows, service interactions)
  32. - Complete design documents with embedded diagrams
  33. **Code-to-Diagram Conversion:**
  34. - Extract architecture from Spring Boot applications
  35. - Generate deployment diagrams from configuration files
  36. - Create sequence diagrams from method calls
  37. - Document ETL pipelines and data flows
  38. **Diagram Management:**
  39. - Extract Mermaid diagrams from Markdown files
  40. - Validate diagram syntax with mermaid-cli
  41. - Convert diagrams to PNG/SVG images
  42. - Batch process entire directories
  43. ## Quick Start
  44. ### Create an Activity Diagram
  45. ```
  46. User: "Create an activity diagram for user registration with email verification"
  47. ```
  48. The skill will:
  49. 1. Load `references/guides/diagrams/activity-diagrams.md`
  50. 2. Use the registration pattern template
  51. 3. Add Unicode symbols (🔐 for security, 📧 for email, ✅ for success)
  52. 4. Apply high-contrast styling
  53. 5. Output complete Mermaid diagram
  54. ### Generate from Code
  55. ```
  56. User: "Here's my Spring Boot application.yml - generate a deployment diagram"
  57. ```
  58. The skill will:
  59. 1. Analyze configuration (datasource, cache, security)
  60. 2. Load `references/guides/diagrams/deployment-diagrams.md`
  61. 3. Load `examples/spring-boot/README.md`
  62. 4. Map config to cloud resources
  63. 5. Generate deployment diagram with resource specs
  64. ### Create Design Document
  65. ```
  66. User: "Create an API design document for the contacts API"
  67. ```
  68. The skill will:
  69. 1. Load `assets/api-design-template.md`
  70. 2. Load relevant diagram guides (sequence, ER, architecture)
  71. 3. Generate complete document with embedded diagrams
  72. 4. Save to `docs/design/api-contacts-v1-2025-01-13.md`
  73. ## Structure
  74. ### Hierarchical Organization
  75. ```
  76. mermaid-architect/
  77. ├── SKILL.md # Main orchestrator with decision tree
  78. ├── README.md # This file
  79. ├── CLAUDE.md # Claude Code instructions
  80. │
  81. ├── references/ # Reference materials
  82. │ ├── mermaid-diagram-guide.md # Legacy general guide
  83. │ └── guides/ # Specialized guides (load on-demand)
  84. │ ├── diagrams/
  85. │ │ ├── activity-diagrams.md # ✅ Complete
  86. │ │ ├── deployment-diagrams.md # ✅ Complete
  87. │ │ ├── architecture-diagrams.md # ✅ Complete
  88. │ │ └── sequence-diagrams.md # ✅ Complete
  89. │ ├── code-to-diagram/
  90. │ │ └── README.md # ✅ Complete (master guide)
  91. │ ├── unicode-symbols/
  92. │ │ └── guide.md # ✅ Complete (100+ symbols)
  93. │ └── troubleshooting.md # ✅ Complete (28 common errors)
  94. │
  95. ├── scripts/ # Python utilities
  96. │ ├── extract_mermaid.py # ✅ Extract & validate diagrams
  97. │ └── mermaid_to_image.py # ✅ Convert to PNG/SVG
  98. │
  99. ├── examples/ # Language-specific patterns
  100. │ ├── spring-boot/ # ✅ Complete
  101. │ ├── fastapi/ # ✅ Complete
  102. │ ├── react/ # ✅ Complete
  103. │ ├── python-etl/ # ✅ Complete
  104. │ ├── node-webapp/ # ✅ Complete
  105. │ └── java-webapp/ # ✅ Complete
  106. │
  107. └── assets/ # Design document templates
  108. ├── architecture-design-template.md
  109. ├── api-design-template.md
  110. ├── feature-design-template.md
  111. ├── database-design-template.md
  112. └── system-design-template.md
  113. ```
  114. ## Key Features
  115. ### 1. Unicode Semantic Symbols
  116. Every diagram uses meaningful Unicode symbols:
  117. ```mermaid
  118. graph TB
  119. User[👤 Client] --> Gateway[🌐 API Gateway]
  120. Gateway --> Auth[🔐 Auth Service]
  121. Gateway --> API[⚙️ API Service]
  122. API --> DB[(💾 Database)]
  123. API --> Cache[(⚡ Redis)]
  124. API --> Queue[📬 Message Queue]
  125. Queue --> Worker[⚙️ Background Worker]
  126. ```
  127. **Symbol Categories:**
  128. - Infrastructure: ☁️ 🌐 🔌 📡 🗄️
  129. - Compute: ⚙️ ⚡ 🔄 🚀 💨
  130. - Data: 💾 📦 📊 📈 🗃️
  131. - Messaging: 📨 📬 📤 📥 🐰
  132. - Security: 🔐 🔑 🛡️ 🚪 👤
  133. - Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌
  134. ### 2. High-Contrast Styling
  135. All diagrams use accessible, high-contrast colors - see SKILL.md for full details.
  136. ### 3. Python Utilities
  137. #### Extract Diagrams
  138. ```bash
  139. # List all diagrams in a file
  140. python scripts/extract_mermaid.py document.md --list-only
  141. # Extract to separate .mmd files
  142. python scripts/extract_mermaid.py document.md --output-dir diagrams/
  143. # Validate all diagrams
  144. python scripts/extract_mermaid.py document.md --validate
  145. # Replace diagrams with image references (for Confluence)
  146. python scripts/extract_mermaid.py document.md --replace-with-images \
  147. --image-format png --output-markdown output.md
  148. ```
  149. #### Convert to Images
  150. ```bash
  151. # Single file
  152. python scripts/mermaid_to_image.py diagram.mmd output.png
  153. # Custom theme and size
  154. python scripts/mermaid_to_image.py diagram.mmd output.svg \
  155. --theme dark --background white --width 1200
  156. # Batch convert directory
  157. python scripts/mermaid_to_image.py diagrams/ output/ \
  158. --format png --recursive
  159. # From stdin
  160. echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
  161. ```
  162. ## Requirements
  163. ### For Diagram Generation
  164. - Claude Code skill system (automatic)
  165. - Guides and templates (included in this skill)
  166. ### For Validation & Image Conversion
  167. ```bash
  168. # Install mermaid-cli globally
  169. npm install -g @mermaid-js/mermaid-cli
  170. # Verify installation
  171. mmdc --version
  172. ```
  173. ### For Python Scripts
  174. - Python 3.7+
  175. - No additional packages required (uses stdlib only)
  176. ## Learning Path
  177. ### New to Mermaid Diagrams?
  178. 1. **Start with Activity Diagrams** - Read `references/guides/diagrams/activity-diagrams.md`
  179. 2. **Learn Unicode Symbols** - Read `references/guides/unicode-symbols/guide.md`
  180. 3. **Try an Example** - Use patterns from `examples/spring-boot/`
  181. 4. **Validate Your Work** - Run `python scripts/extract_mermaid.py --validate`
  182. ### Need to Document Existing Code?
  183. 1. **Identify Framework** - Spring Boot, FastAPI, React, etc.
  184. 2. **Load Example Guide** - Read `examples/{your-framework}/README.md`
  185. 3. **Match Patterns** - Find similar code patterns in examples
  186. 4. **Generate Diagrams** - Use templates from guides
  187. 5. **Validate** - Use validation scripts
  188. ### Creating Design Documents?
  189. 1. **Choose Template Type** - Architecture, API, Feature, Database, or System
  190. 2. **Load Template** - Read from `assets/{type}-design-template.md`
  191. 3. **Fill Sections** - Replace placeholders with actual content
  192. 4. **Add Diagrams** - Load diagram guides as needed for each section
  193. 5. **Use Symbols** - Enhance with Unicode symbols throughout
  194. 6. **Save** - Place in `docs/design/` with timestamp
  195. ## How the Hierarchical System Works
  196. ### Traditional Approach (Inefficient)
  197. - Load entire skill documentation (~50KB)
  198. - AI processes all templates and examples
  199. - High token usage
  200. - Slow response time
  201. ### Hierarchical Approach (Efficient)
  202. 1. **User makes request** → AI analyzes intent
  203. 2. **Decision tree activates** → Determines needed guides
  204. 3. **Load only what's needed** → Reads specific guide (~2-5KB)
  205. 4. **Generate output** → Uses targeted templates
  206. 5. **Token efficient** → 10x less context needed
  207. ### Example Flow
  208. **User:** "Create deployment diagram for my Docker Compose setup"
  209. **Decision Tree:**
  210. ```
  211. 1. Analyze: "deployment diagram" + "Docker Compose"
  212. 2. Determine: deployment-diagrams.md needed
  213. 3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
  214. 4. Find pattern: Docker Compose template exists
  215. 5. Generate: Using template + Unicode symbols
  216. 6. Output: Complete diagram in <30 seconds
  217. ```
  218. **Tokens Used:** ~2,000 (vs ~10,000 with traditional approach)
  219. ## Completion Status
  220. ✅ **Complete:**
  221. - Hierarchical decision tree orchestrator
  222. - Activity diagram guide with templates
  223. - Deployment diagram guide (AWS, GCP, K8s, serverless, Docker)
  224. - Unicode symbols guide (100+ symbols)
  225. - Extract Mermaid script with validation
  226. - Mermaid to image conversion script
  227. - Spring Boot code-to-diagram examples
  228. - Design document templates (5 types)
  229. - High-contrast styling system
  230. 🚧 **In Progress:**
  231. - FastAPI examples
  232. - React component architecture examples
  233. - Python ETL pipeline examples
  234. 📋 **Planned:**
  235. - Architecture diagrams guide
  236. - Sequence diagrams guide
  237. - Code-to-diagram master guide
  238. - Node.js/Express examples
  239. - Java web app examples
  240. ## Contributing
  241. To add a new diagram type guide:
  242. 1. Create guide in `references/guides/diagrams/{type}-diagrams.md`
  243. 2. Include:
  244. - When to use
  245. - Basic syntax
  246. - Common patterns (3-5 templates)
  247. - Unicode symbol examples
  248. - Best practices
  249. 3. Update `SKILL.md` decision tree
  250. 4. Add examples with code mappings
  251. To add a new language example:
  252. 1. Create directory in `examples/{framework}/`
  253. 2. Add `README.md` with:
  254. - Framework overview
  255. - Architecture diagram from structure
  256. - Deployment diagram from config
  257. - Sequence diagram from code
  258. - Activity diagram from logic
  259. 3. Update `SKILL.md` code-to-diagram table
  260. ## License
  261. Part of Claude Code Skills - MIT License
  262. ## Related Skills
  263. - **confluence** - Upload diagrams to Confluence
  264. - **plantuml** - Alternative diagram format
  265. ## Links
  266. - [GitHub Repository](https://github.com/SpillwaveSolutions/design-doc-mermaid)
  267. - [Skilz Marketplace Listing](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
  268. - [Mermaid Official Documentation](https://mermaid.js.org/)
  269. ---
  270. **Version:** 2.0.0
  271. **Updated:** 2025-01-13
  272. **Maintained by:** SpillwaveSolutions

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.