[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ACFR59WD4V0F0WHYNZEDWA":3,"skill-same:01M7ACFR59WD4V0F0WHYNZEDWA":155},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7ACFR59WD4V0F0WHYNZEDWA","design-doc-mermaid",null,"Create Mermaid diagrams (activity, deployment, sequence, architecture) from text descriptions or source code. Use when asked to \"create a diagram\", \"generate mermaid\", \"document architecture\", \"code to diagram\", \"create design doc\", or \"convert code to diagram\". Supports hierarchical on-demand guide loading, Unicode semantic symbols, and Python utilities for diagram extraction and image conversion.","venkataratnamb20\u002Fcursor_experiments","venkataratnamb20","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F58448762?v=4","01M7ACE8RHQ71FBZHY64YTTF3C","Venkata Ratnam Bhumireddy","01M7ACE8SQ3H7B3GEKTY63DRCP",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: design-doc-mermaid\ndescription: Create Mermaid diagrams (activity, deployment, sequence, architecture) from text descriptions or source code. Use when asked to \"create a diagram\", \"generate mermaid\", \"document architecture\", \"code to diagram\", \"create design doc\", or \"convert code to diagram\". Supports hierarchical on-demand guide loading, Unicode semantic symbols, and Python utilities for diagram extraction and image conversion.\n---\n\n# Mermaid Architect - Hierarchical Diagram and Documentation Skill\n\nMermaid diagram and documentation system with specialized guides and code-to-diagram capabilities.\n\n## Table of Contents\n\n- [Decision Tree](#decision-tree)\n- [Available Guides and Resources](#available-guides-and-resources)\n- [Usage Patterns](#usage-patterns)\n- [Resilient Workflow](#resilient-workflow)\n- [Unicode Semantic Symbols](#unicode-semantic-symbols)\n- [Python Utilities](#python-utilities)\n- [Decision Tree Examples](#decision-tree-examples)\n- [High-Contrast Styling](#high-contrast-styling)\n- [File Organization](#file-organization)\n- [Workflow Summary](#workflow-summary)\n- [When to Use What](#when-to-use-what)\n- [Best Practices](#best-practices)\n- [Learning Path](#learning-path)\n\n## Decision Tree\n\n**How this skill works:**\n\n1. **User makes a request** → Skill analyzes intent\n2. **Skill determines diagram\u002Fdocument type** → Loads appropriate guide(s)\n3. **AI reads specialized guide** → Generates diagram\u002Fdocument using templates\n4. **Result delivered** → With validation and export options\n\n**User Intent Analysis:**\n\n```mermaid\nflowchart TD\n    Start([User Request]) --> Analyze{Analyze Intent}\n\n    Analyze -->|\"workflow, process, business logic\"| Activity[Load Activity Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md]\n    Analyze -->|\"infrastructure, deployment, cloud\"| Deploy[Load Deployment Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md]\n    Analyze -->|\"system architecture, components\"| Arch[Load Architecture Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md]\n    Analyze -->|\"API flow, interactions\"| Sequence[Load Sequence Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md]\n    Analyze -->|\"code to diagram\"| CodeToDiag[Load Code-to-Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fcode-to-diagram\u002F + examples\u002F]\n    Analyze -->|\"design document, full docs\"| DesignDoc[Load Design Document Template\u003Cbr\u002F>assets\u002F*-design-template.md]\n    Analyze -->|\"unicode symbols, icons\"| Unicode[Load Unicode Symbols Guide\u003Cbr\u002F>references\u002Fguides\u002Funicode-symbols\u002Fguide.md]\n    Analyze -->|\"extract, validate, convert\"| Scripts[Use Python Scripts\u003Cbr\u002F>scripts\u002Fextract_mermaid.py\u003Cbr\u002F>scripts\u002Fmermaid_to_image.py]\n\n    Activity --> Generate[Generate Diagram]\n    Deploy --> Generate\n    Arch --> Generate\n    Sequence --> Generate\n    CodeToDiag --> Generate\n    DesignDoc --> Generate\n    Unicode --> Generate\n    Scripts --> Execute[Execute Script]\n\n    Generate --> Validate{Validate?}\n    Validate -->|Yes| RunValidation[Run mmdc validation]\n    Validate -->|No| Output\n    RunValidation --> Output[Output Result]\n    Execute --> Output\n\n    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black\n    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen\n    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue\n\n    class Analyze,Validate decision\n    class Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide\n    class Generate,Execute,RunValidation,Output action\n```\n\n## Available Guides and Resources\n\n### Diagram Type Guides (`references\u002Fguides\u002Fdiagrams\u002F`)\n\n| Guide | Full Path | Load When User Wants | Examples |\n|-------|-----------|---------------------|----------|\n| Activity Diagrams | `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` | Workflows, processes, business logic, user flows, decision trees | \"Show checkout flow\", \"Document ETL pipeline\", \"Create approval workflow\" |\n| Deployment Diagrams | `references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md` | Infrastructure, cloud architecture, K8s, serverless, network topology | \"Show AWS architecture\", \"Document GCP deployment\", \"Create K8s diagram\" |\n| Architecture Diagrams | `references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md` | System architecture, component design, high-level structure | \"Show system components\", \"Document microservices\", \"Architecture overview\" |\n| Sequence Diagrams | `references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md` | API interactions, service communication, request\u002Fresponse flows | \"Show API call sequence\", \"Document auth flow\", \"Service interactions\" |\n\n### Code-to-Diagram Guide & Examples\n\n| Resource | Full Path | What It Provides |\n|----------|-----------|------------------|\n| **Master Guide** | `references\u002Fguides\u002Fcode-to-diagram\u002FREADME.md` | Complete workflow for analyzing any codebase and extracting diagrams |\n| **Spring Boot** | `examples\u002Fspring-boot\u002FREADME.md` | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic |\n| **FastAPI** | `examples\u002Ffastapi\u002FREADME.md` | Python async patterns, Pydantic models, dependency injection, cloud deployment |\n| **React** | `examples\u002Freact\u002FREADME.md` | Component hierarchy, state management, data flow, build pipeline |\n| **Python ETL** | `examples\u002Fpython-etl\u002FREADME.md` | Data pipeline, transformation steps, error handling, scheduling |\n| **Node\u002FExpress** | `examples\u002Fnode-webapp\u002FREADME.md` | Middleware chain, route handlers, async patterns, deployment |\n| **Java Web App** | `examples\u002Fjava-webapp\u002FREADME.md` | Traditional MVC, servlet containers, WAR deployment |\n\n### Design Document Templates\n\n| Template | Full Path | Use For | Load When |\n|----------|-----------|---------|-----------|\n| Architecture Design | `assets\u002Farchitecture-design-template.md` | System-wide architecture | \"Create architecture doc\", \"Document system design\" |\n| API Design | `assets\u002Fapi-design-template.md` | API specifications | \"API design doc\", \"Document REST API\" |\n| Feature Design | `assets\u002Ffeature-design-template.md` | Feature planning | \"Feature design\", \"Plan new feature\" |\n| Database Design | `assets\u002Fdatabase-design-template.md` | Database schema | \"Database design\", \"Document schema\" |\n| System Design | `assets\u002Fsystem-design-template.md` | Complete system | \"System design doc\", \"Full system documentation\" |\n\n### Unicode Symbols Guide\n\n**Full Path:** `references\u002Fguides\u002Funicode-symbols\u002Fguide.md`\n\n**Load when user mentions:** \"unicode symbols\", \"emoji in diagrams\", \"semantic icons\", \"add symbols\"\n\n**Quick Reference:**\n- 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️\n- ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨\n- 💾 Data: 💾 📦 📊 📈 🗃️ 🧊\n- 📨 Messaging: 📨 📬 📤 📥 🐰 📢\n- 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫\n- 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌\n\n### Python Scripts (`scripts\u002F`)\n\n| Script | Use For | Load When |\n|--------|---------|-----------|\n| `extract_mermaid.py` | Extract diagrams from Markdown, validate syntax, replace with images | \"extract diagrams\", \"validate mermaid\", \"find all diagrams\" |\n| `mermaid_to_image.py` | Convert .mmd to PNG\u002FSVG, batch conversion, custom themes | \"convert to image\", \"render diagram\", \"create PNG\" |\n| `resilient_diagram.py` | Full workflow: save .mmd, generate image, validate, error recovery | \"generate diagram\", \"create diagram with validation\", \"resilient diagram\" |\n\n## Usage Patterns\n\nCommon request patterns and guide selection. See [When to Use What](#when-to-use-what) for complete mapping.\n\n| Pattern | Example Request | Guides to Load |\n|---------|-----------------|----------------|\n| Single Diagram | \"Create activity diagram for login flow\" | Diagram type guide + Unicode symbols |\n| Code-to-Diagram | \"Generate deployment from application.yml\" | Framework example + Deployment guide |\n| Design Document | \"Create API design document\" | Template from assets\u002F + Relevant diagram guides |\n| Extract\u002FValidate | \"Extract diagrams from design.md\" | Use `scripts\u002Fextract_mermaid.py` |\n| Batch Convert | \"Convert all .mmd to PNG\" | Use `scripts\u002Fmermaid_to_image.py` |\n\n## Resilient Workflow\n\n**CRITICAL:** This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization.\n\n**Full Guide:** `references\u002Fguides\u002Fresilient-workflow.md`\n\n### Workflow Overview\n\n```mermaid\nflowchart LR\n    A[1. Identify Type] --> B[2. Save .mmd + Image]\n    B --> C{3. Valid?}\n    C -->|Yes| D[4. Add to Markdown]\n    C -->|No| E[5. Error Recovery]\n    E --> F{Fix Found?}\n    F -->|Yes| A\n    F -->|No| G[Search External]\n    G --> A\n\n    classDef step fill:#90EE90,stroke:#333,color:darkgreen\n    classDef decision fill:#FFD700,stroke:#333,color:black\n    class A,B,D,E,G step\n    class C,F decision\n```\n\n### Key Principle\n\n**NEVER add a diagram to markdown until it passes validation.** This prevents broken diagrams in documentation.\n\n### Using the Script (Recommended)\n\n```bash\n# Generate with full error recovery\npython scripts\u002Fresilient_diagram.py \\\n    --code \"flowchart TD; A-->B\" \\\n    --markdown-file design_doc \\\n    --diagram-num 1 \\\n    --title \"process_flow\" \\\n    --format png \\\n    --json\n```\n\n**Output:** Both `.mmd` and `.png` files in `.\u002Fdiagrams\u002F` directory.\n\n### File Naming Convention\n\n```\n.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.mmd\n.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.png\n```\n\n**Example:** `.\u002Fdiagrams\u002Fapi_design_01_sequence_auth_flow.png`\n\n### Error Recovery Priority\n\nWhen validation fails, the workflow automatically:\n\n1. **Check troubleshooting guide** - `references\u002Fguides\u002Ftroubleshooting.md` (28 documented errors)\n2. **Search with perplexity** - `perplexity_ask` MCP for syntax questions\n3. **Search with brave** - `brave_web_search` MCP for recent solutions\n4. **Ask gemini** - `gemini` skill for alternative perspective\n5. **General search** - `WebSearch` tool as fallback\n\n### Manual Fallback Steps\n\nIf the script is unavailable:\n\n1. **Identify diagram type** from first line (flowchart, sequence, etc.)\n2. **Load reference guide** from `references\u002Fguides\u002Fdiagrams\u002F`\n3. **Save to** `.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.mmd`\n4. **Validate:** `mmdc -i file.mmd -o file.png -b transparent`\n5. **On error:** Search `references\u002Fguides\u002Ftroubleshooting.md` for matching error\n6. **If not found:** Use search tools in priority order above\n7. **Add reference:** `![Description](.\u002Fdiagrams\u002Ffilename.png)`\n\n### Pattern 6: Resilient Diagram Generation\n\n**User:** \"Create a sequence diagram and add it to the design doc\"\n\n**Skill Actions:**\n1. Identify intent: **diagram generation** + **markdown integration**\n2. Load workflow guide: `references\u002Fguides\u002Fresilient-workflow.md`\n3. Identify diagram type: **sequence**\n4. Load diagram guide: `references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md`\n5. Generate Mermaid code using templates\n6. Execute resilient workflow:\n   ```bash\n   python scripts\u002Fresilient_diagram.py \\\n       --code \"[generated code]\" \\\n       --markdown-file design_doc \\\n       --diagram-num 1 \\\n       --title \"api_sequence\" \\\n       --json\n   ```\n7. If validation fails → Apply troubleshooting fix → Retry\n8. On success → Add `![API Sequence](.\u002Fdiagrams\u002Fdesign_doc_01_sequence_api_sequence.png)` to markdown\n\n## Unicode Semantic Symbols\n\nAlways use Unicode symbols to enhance diagram clarity. Common patterns:\n\n### Infrastructure & Deployment\n```mermaid\ngraph TB\n    Client[👤 User] --> LB[🌐 Load Balancer]\n    LB --> App1[⚙️ App Server 1]\n    LB --> App2[⚙️ App Server 2]\n    App1 --> DB[(💾 Database)]\n    App1 --> Cache[(⚡ Redis)]\n```\n\n### Activity Flow with States\n```mermaid\nflowchart TD\n    Start([🚀 Start]) --> Process[⚙️ Process Data]\n    Process --> Check{✓ Valid?}\n    Check -->|Yes| Save[💾 Save]\n    Check -->|No| Error[❌ Error]\n    Save --> Complete([✅ Complete])\n```\n\n### Microservices Architecture\n```mermaid\ngraph TB\n    API[🌐 API Gateway] --> Auth[🔐 Auth Service]\n    API --> Orders[📋 Order Service]\n    Orders --> Queue[📬 Message Queue]\n    Queue --> Worker[⚙️ Background Worker]\n    Worker --> Storage[📦 Object Storage]\n```\n\n**For complete symbol reference, load:** `references\u002Fguides\u002Funicode-symbols\u002Fguide.md`\n\n## Python Utilities\n\n### Extract Mermaid Diagrams\n\n```bash\n# List all diagrams\npython scripts\u002Fextract_mermaid.py document.md --list-only\n\n# Extract to separate files\npython scripts\u002Fextract_mermaid.py document.md --output-dir diagrams\u002F\n\n# Validate all diagrams\npython scripts\u002Fextract_mermaid.py document.md --validate\n\n# Replace with image references (for Confluence upload)\npython scripts\u002Fextract_mermaid.py document.md --replace-with-images \\\n  --image-format png --output-markdown output.md\n```\n\n### Convert to Images\n\n```bash\n# Single conversion\npython scripts\u002Fmermaid_to_image.py diagram.mmd output.png\n\n# With custom settings\npython scripts\u002Fmermaid_to_image.py diagram.mmd output.svg \\\n  --theme dark --background white --width 1200\n\n# Batch convert directory\npython scripts\u002Fmermaid_to_image.py diagrams\u002F output\u002F --format png --recursive\n\n# From stdin\necho \"graph TD; A-->B\" | python scripts\u002Fmermaid_to_image.py - output.png\n```\n\n## Decision Tree Examples\n\n### Example 1: User Asks for Workflow Diagram\n\n**Input:** \"Show the checkout process workflow\"\n\n**Skill Decision Path:**\n```\n1. Analyze: workflow, process → ACTIVITY DIAGRAM\n2. Load guide: guides\u002Fdiagrams\u002Factivity-diagrams.md\n3. Find pattern: E-commerce checkout (template exists in guide)\n4. Generate using template + Unicode symbols\n5. Output activity diagram with decision points\n```\n\n**Output:** Complete activity diagram with Unicode symbols for cart, payment, order states.\n\n### Example 2: User Provides Spring Boot Code\n\n**Input:** \"Here's my Spring Boot controller, create diagrams\"\n\n**Skill Decision Path:**\n```\n1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT\n2. Load guides:\n   - examples\u002Fspring-boot\u002FREADME.md\n   - guides\u002Fdiagrams\u002Farchitecture-diagrams.md (for structure)\n   - guides\u002Fdiagrams\u002Fsequence-diagrams.md (for method calls)\n   - guides\u002Fdiagrams\u002Factivity-diagrams.md (for business logic)\n3. Generate multiple diagrams:\n   a. Architecture diagram from @RestController\u002F@Service\u002F@Repository annotations\n   b. Sequence diagram from method call chain\n   c. Activity diagram from business logic flow\n4. Output all diagrams with explanations\n```\n\n**Output:** 3-4 diagrams showing different views of the Spring Boot application.\n\n### Example 3: User Wants Infrastructure Documentation\n\n**Input:** \"Document my GCP Cloud Run deployment with AlloyDB\"\n\n**Skill Decision Path:**\n```\n1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM\n2. Load guides:\n   - guides\u002Fdiagrams\u002Fdeployment-diagrams.md\n   - examples\u002Fspring-boot\u002F or examples\u002Ffastapi\u002F (if code provided)\n3. Check for IaC files (Pulumi, Terraform, docker-compose)\n4. Generate deployment diagram with:\n   - Cloud Run services with specs\n   - VPC connector\n   - AlloyDB cluster\n   - Security (IAM, Secret Manager)\n   - Monitoring\n5. Apply Unicode symbols for clarity\n6. Output with resource specifications\n```\n\n**Output:** Complete GCP deployment diagram with all resources labeled.\n\n## High-Contrast Styling\n\n**ALL diagrams MUST use high-contrast colors:**\n\n```mermaid\ngraph TB\n    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen\n    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue\n    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue\n    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black\n\n    %% Every classDef MUST have color: property\n```\n\n**Rules:**\n- Light background → Dark text color\n- Dark background → Light text color\n- Always specify `color:` in every `classDef`\n\n## File Organization\n\n```\ndesign-doc-mermaid\u002F\n├── SKILL.md                          # This file - Main orchestrator\n├── README.md                         # User documentation\n├── CLAUDE.md                         # Claude Code instructions\n│\n├── references\u002F                       # Reference materials\n│   ├── mermaid-diagram-guide.md     # Legacy general guide\n│   └── guides\u002F                       # Specialized guides (load on-demand)\n│       ├── diagrams\u002F\n│       │   ├── activity-diagrams.md      # Workflows, processes\n│       │   ├── deployment-diagrams.md    # Infrastructure, cloud\n│       │   ├── architecture-diagrams.md  # System architecture\n│       │   └── sequence-diagrams.md      # API interactions\n│       ├── code-to-diagram\u002F\n│       │   └── README.md                 # Master guide for code analysis\n│       ├── unicode-symbols\u002F\n│       │   └── guide.md                  # Complete symbol reference\n│       └── troubleshooting.md        # Common syntax errors & fixes\n│\n├── assets\u002F                           # Design document templates\n│   ├── architecture-design-template.md\n│   ├── api-design-template.md\n│   ├── feature-design-template.md\n│   ├── database-design-template.md\n│   └── system-design-template.md\n│\n├── scripts\u002F                          # Python utilities\n│   ├── extract_mermaid.py           # Extract & validate diagrams\n│   └── mermaid_to_image.py          # Convert to PNG\u002FSVG\n│\n├── examples\u002F                         # Language-specific patterns\n│   ├── spring-boot\u002F                 # Spring Boot patterns\n│   ├── fastapi\u002F                     # FastAPI patterns\n│   ├── react\u002F                       # React patterns\n│   ├── python-etl\u002F                  # Data pipeline patterns\n│   ├── node-webapp\u002F                 # Express.js patterns\n│   └── java-webapp\u002F                 # Traditional Java patterns\n│\n└── references\u002F                       # General Mermaid reference\n    └── mermaid-diagram-guide.md     # Complete Mermaid syntax guide\n```\n\n## Workflow Summary\n\n1. **Analyze user intent** → Determine diagram type, document type, or action needed\n2. **Load appropriate guide(s)** → Read only what's needed (token efficient)\n3. **Apply templates and patterns** → Use examples from guides\n4. **Generate output** → Create diagram or document\n5. **Validate** (optional) → Use scripts to verify\n6. **Convert** (optional) → Export to images if needed\n\n## When to Use What\n\n| User Request | Load This |\n|--------------|-----------|\n| \"activity diagram\", \"workflow\", \"process flow\" | `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` |\n| \"deployment\", \"infrastructure\", \"cloud\", \"k8s\" | `references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md` |\n| \"architecture\", \"system design\", \"components\" | `references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md` + design template |\n| \"API\", \"sequence\", \"interactions\", \"flow\" | `references\u002Fmermaid-diagram-guide.md` (sequence section) |\n| \"Spring Boot code\" | `examples\u002Fspring-boot\u002F` + relevant diagram guides |\n| \"FastAPI code\", \"Python API\" | `examples\u002Ffastapi\u002F` + relevant diagram guides |\n| \"React app\", \"frontend\" | `examples\u002Freact\u002F` + architecture guide |\n| \"ETL\", \"data pipeline\", \"Python batch\" | `examples\u002Fpython-etl\u002F` + activity guide |\n| \"symbols\", \"unicode\", \"emoji\" | `references\u002Fguides\u002Funicode-symbols\u002Fguide.md` |\n| \"syntax error\", \"diagram won't render\", \"troubleshoot\" | `references\u002Fguides\u002Ftroubleshooting.md` |\n| \"extract diagrams\" | `scripts\u002Fextract_mermaid.py` |\n| \"convert to image\", \"PNG\", \"SVG\" | `scripts\u002Fmermaid_to_image.py` |\n| \"create diagram\", \"generate diagram\", \"add diagram to markdown\" | `scripts\u002Fresilient_diagram.py` + `references\u002Fguides\u002Fresilient-workflow.md` |\n| \"design document\", \"full docs\" | `assets\u002F*-design-template.md` + diagram guides |\n\n## Best Practices\n\n1. **Single Responsibility**: One diagram = One concept\n2. **Unicode Enhancement**: Always use semantic symbols for clarity\n3. **High Contrast**: Never skip the `color:` property in styles\n4. **Validate Early**: Use scripts to catch syntax errors\n5. **Template Reuse**: Leverage existing templates and examples\n6. **Load On-Demand**: Only read guides needed for the specific request\n7. **Token Efficiency**: Use hierarchical loading instead of reading everything\n\n## Learning Path\n\n**New to Mermaid?** Start here:\n1. Read `references\u002Fguides\u002Funicode-symbols\u002Fguide.md` for symbol meanings\n2. Read `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` for basic patterns\n3. Try examples in `examples\u002Fspring-boot\u002F` or `examples\u002Ffastapi\u002F`\n4. Use `scripts\u002Fextract_mermaid.py --validate` to check your work\n\n**Need to document code?** Follow this:\n1. Identify your framework → Load relevant `examples\u002F{framework}\u002F`\n2. Match code pattern to diagram type\n3. Use templates from guide\n4. Validate with scripts\n\n**Creating design docs?** Follow this:\n1. Choose document type → Load template from `assets\u002F`\n2. Fill in text sections\n3. Load diagram guides as needed for each section\n4. Use Unicode symbols throughout\n5. Save to `docs\u002Fdesign\u002F` with timestamp\n\n---\n\n**Version:** 2.0 (Hierarchical Architecture)\n**Last Updated:** 2025-01-13\n**Maintained by:** Claude Code Skills\n","# Mermaid Architect - Hierarchical Diagram and Documentation Skill\n\nMermaid diagram and documentation system with specialized guides and code-to-diagram capabilities.\n\n## Table of Contents\n\n- [Decision Tree](#decision-tree)\n- [Available Guides and Resources](#available-guides-and-resources)\n- [Usage Patterns](#usage-patterns)\n- [Resilient Workflow](#resilient-workflow)\n- [Unicode Semantic Symbols](#unicode-semantic-symbols)\n- [Python Utilities](#python-utilities)\n- [Decision Tree Examples](#decision-tree-examples)\n- [High-Contrast Styling](#high-contrast-styling)\n- [File Organization](#file-organization)\n- [Workflow Summary](#workflow-summary)\n- [When to Use What](#when-to-use-what)\n- [Best Practices](#best-practices)\n- [Learning Path](#learning-path)\n\n## Decision Tree\n\n**How this skill works:**\n\n1. **User makes a request** → Skill analyzes intent\n2. **Skill determines diagram\u002Fdocument type** → Loads appropriate guide(s)\n3. **AI reads specialized guide** → Generates diagram\u002Fdocument using templates\n4. **Result delivered** → With validation and export options\n\n**User Intent Analysis:**\n\n```mermaid\nflowchart TD\n    Start([User Request]) --> Analyze{Analyze Intent}\n\n    Analyze -->|\"workflow, process, business logic\"| Activity[Load Activity Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md]\n    Analyze -->|\"infrastructure, deployment, cloud\"| Deploy[Load Deployment Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md]\n    Analyze -->|\"system architecture, components\"| Arch[Load Architecture Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md]\n    Analyze -->|\"API flow, interactions\"| Sequence[Load Sequence Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md]\n    Analyze -->|\"code to diagram\"| CodeToDiag[Load Code-to-Diagram Guide\u003Cbr\u002F>references\u002Fguides\u002Fcode-to-diagram\u002F + examples\u002F]\n    Analyze -->|\"design document, full docs\"| DesignDoc[Load Design Document Template\u003Cbr\u002F>assets\u002F*-design-template.md]\n    Analyze -->|\"unicode symbols, icons\"| Unicode[Load Unicode Symbols Guide\u003Cbr\u002F>references\u002Fguides\u002Funicode-symbols\u002Fguide.md]\n    Analyze -->|\"extract, validate, convert\"| Scripts[Use Python Scripts\u003Cbr\u002F>scripts\u002Fextract_mermaid.py\u003Cbr\u002F>scripts\u002Fmermaid_to_image.py]\n\n    Activity --> Generate[Generate Diagram]\n    Deploy --> Generate\n    Arch --> Generate\n    Sequence --> Generate\n    CodeToDiag --> Generate\n    DesignDoc --> Generate\n    Unicode --> Generate\n    Scripts --> Execute[Execute Script]\n\n    Generate --> Validate{Validate?}\n    Validate -->|Yes| RunValidation[Run mmdc validation]\n    Validate -->|No| Output\n    RunValidation --> Output[Output Result]\n    Execute --> Output\n\n    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black\n    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen\n    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue\n\n    class Analyze,Validate decision\n    class Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide\n    class Generate,Execute,RunValidation,Output action\n```\n\n## Available Guides and Resources\n\n### Diagram Type Guides (`references\u002Fguides\u002Fdiagrams\u002F`)\n\n| Guide | Full Path | Load When User Wants | Examples |\n|-------|-----------|---------------------|----------|\n| Activity Diagrams | `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` | Workflows, processes, business logic, user flows, decision trees | \"Show checkout flow\", \"Document ETL pipeline\", \"Create approval workflow\" |\n| Deployment Diagrams | `references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md` | Infrastructure, cloud architecture, K8s, serverless, network topology | \"Show AWS architecture\", \"Document GCP deployment\", \"Create K8s diagram\" |\n| Architecture Diagrams | `references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md` | System architecture, component design, high-level structure | \"Show system components\", \"Document microservices\", \"Architecture overview\" |\n| Sequence Diagrams | `references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md` | API interactions, service communication, request\u002Fresponse flows | \"Show API call sequence\", \"Document auth flow\", \"Service interactions\" |\n\n### Code-to-Diagram Guide & Examples\n\n| Resource | Full Path | What It Provides |\n|----------|-----------|------------------|\n| **Master Guide** | `references\u002Fguides\u002Fcode-to-diagram\u002FREADME.md` | Complete workflow for analyzing any codebase and extracting diagrams |\n| **Spring Boot** | `examples\u002Fspring-boot\u002FREADME.md` | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic |\n| **FastAPI** | `examples\u002Ffastapi\u002FREADME.md` | Python async patterns, Pydantic models, dependency injection, cloud deployment |\n| **React** | `examples\u002Freact\u002FREADME.md` | Component hierarchy, state management, data flow, build pipeline |\n| **Python ETL** | `examples\u002Fpython-etl\u002FREADME.md` | Data pipeline, transformation steps, error handling, scheduling |\n| **Node\u002FExpress** | `examples\u002Fnode-webapp\u002FREADME.md` | Middleware chain, route handlers, async patterns, deployment |\n| **Java Web App** | `examples\u002Fjava-webapp\u002FREADME.md` | Traditional MVC, servlet containers, WAR deployment |\n\n### Design Document Templates\n\n| Template | Full Path | Use For | Load When |\n|----------|-----------|---------|-----------|\n| Architecture Design | `assets\u002Farchitecture-design-template.md` | System-wide architecture | \"Create architecture doc\", \"Document system design\" |\n| API Design | `assets\u002Fapi-design-template.md` | API specifications | \"API design doc\", \"Document REST API\" |\n| Feature Design | `assets\u002Ffeature-design-template.md` | Feature planning | \"Feature design\", \"Plan new feature\" |\n| Database Design | `assets\u002Fdatabase-design-template.md` | Database schema | \"Database design\", \"Document schema\" |\n| System Design | `assets\u002Fsystem-design-template.md` | Complete system | \"System design doc\", \"Full system documentation\" |\n\n### Unicode Symbols Guide\n\n**Full Path:** `references\u002Fguides\u002Funicode-symbols\u002Fguide.md`\n\n**Load when user mentions:** \"unicode symbols\", \"emoji in diagrams\", \"semantic icons\", \"add symbols\"\n\n**Quick Reference:**\n- 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️\n- ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨\n- 💾 Data: 💾 📦 📊 📈 🗃️ 🧊\n- 📨 Messaging: 📨 📬 📤 📥 🐰 📢\n- 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫\n- 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌\n\n### Python Scripts (`scripts\u002F`)\n\n| Script | Use For | Load When |\n|--------|---------|-----------|\n| `extract_mermaid.py` | Extract diagrams from Markdown, validate syntax, replace with images | \"extract diagrams\", \"validate mermaid\", \"find all diagrams\" |\n| `mermaid_to_image.py` | Convert .mmd to PNG\u002FSVG, batch conversion, custom themes | \"convert to image\", \"render diagram\", \"create PNG\" |\n| `resilient_diagram.py` | Full workflow: save .mmd, generate image, validate, error recovery | \"generate diagram\", \"create diagram with validation\", \"resilient diagram\" |\n\n## Usage Patterns\n\nCommon request patterns and guide selection. See [When to Use What](#when-to-use-what) for complete mapping.\n\n| Pattern | Example Request | Guides to Load |\n|---------|-----------------|----------------|\n| Single Diagram | \"Create activity diagram for login flow\" | Diagram type guide + Unicode symbols |\n| Code-to-Diagram | \"Generate deployment from application.yml\" | Framework example + Deployment guide |\n| Design Document | \"Create API design document\" | Template from assets\u002F + Relevant diagram guides |\n| Extract\u002FValidate | \"Extract diagrams from design.md\" | Use `scripts\u002Fextract_mermaid.py` |\n| Batch Convert | \"Convert all .mmd to PNG\" | Use `scripts\u002Fmermaid_to_image.py` |\n\n## Resilient Workflow\n\n**CRITICAL:** This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization.\n\n**Full Guide:** `references\u002Fguides\u002Fresilient-workflow.md`\n\n### Workflow Overview\n\n```mermaid\nflowchart LR\n    A[1. Identify Type] --> B[2. Save .mmd + Image]\n    B --> C{3. Valid?}\n    C -->|Yes| D[4. Add to Markdown]\n    C -->|No| E[5. Error Recovery]\n    E --> F{Fix Found?}\n    F -->|Yes| A\n    F -->|No| G[Search External]\n    G --> A\n\n    classDef step fill:#90EE90,stroke:#333,color:darkgreen\n    classDef decision fill:#FFD700,stroke:#333,color:black\n    class A,B,D,E,G step\n    class C,F decision\n```\n\n### Key Principle\n\n**NEVER add a diagram to markdown until it passes validation.** This prevents broken diagrams in documentation.\n\n### Using the Script (Recommended)\n\n```bash\n# Generate with full error recovery\npython scripts\u002Fresilient_diagram.py \\\n    --code \"flowchart TD; A-->B\" \\\n    --markdown-file design_doc \\\n    --diagram-num 1 \\\n    --title \"process_flow\" \\\n    --format png \\\n    --json\n```\n\n**Output:** Both `.mmd` and `.png` files in `.\u002Fdiagrams\u002F` directory.\n\n### File Naming Convention\n\n```\n.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.mmd\n.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.png\n```\n\n**Example:** `.\u002Fdiagrams\u002Fapi_design_01_sequence_auth_flow.png`\n\n### Error Recovery Priority\n\nWhen validation fails, the workflow automatically:\n\n1. **Check troubleshooting guide** - `references\u002Fguides\u002Ftroubleshooting.md` (28 documented errors)\n2. **Search with perplexity** - `perplexity_ask` MCP for syntax questions\n3. **Search with brave** - `brave_web_search` MCP for recent solutions\n4. **Ask gemini** - `gemini` skill for alternative perspective\n5. **General search** - `WebSearch` tool as fallback\n\n### Manual Fallback Steps\n\nIf the script is unavailable:\n\n1. **Identify diagram type** from first line (flowchart, sequence, etc.)\n2. **Load reference guide** from `references\u002Fguides\u002Fdiagrams\u002F`\n3. **Save to** `.\u002Fdiagrams\u002F\u003Cmarkdown_file>_\u003Cnum>_\u003Ctype>_\u003Ctitle>.mmd`\n4. **Validate:** `mmdc -i file.mmd -o file.png -b transparent`\n5. **On error:** Search `references\u002Fguides\u002Ftroubleshooting.md` for matching error\n6. **If not found:** Use search tools in priority order above\n7. **Add reference:** `![Description](.\u002Fdiagrams\u002Ffilename.png)`\n\n### Pattern 6: Resilient Diagram Generation\n\n**User:** \"Create a sequence diagram and add it to the design doc\"\n\n**Skill Actions:**\n1. Identify intent: **diagram generation** + **markdown integration**\n2. Load workflow guide: `references\u002Fguides\u002Fresilient-workflow.md`\n3. Identify diagram type: **sequence**\n4. Load diagram guide: `references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md`\n5. Generate Mermaid code using templates\n6. Execute resilient workflow:\n   ```bash\n   python scripts\u002Fresilient_diagram.py \\\n       --code \"[generated code]\" \\\n       --markdown-file design_doc \\\n       --diagram-num 1 \\\n       --title \"api_sequence\" \\\n       --json\n   ```\n7. If validation fails → Apply troubleshooting fix → Retry\n8. On success → Add `![API Sequence](.\u002Fdiagrams\u002Fdesign_doc_01_sequence_api_sequence.png)` to markdown\n\n## Unicode Semantic Symbols\n\nAlways use Unicode symbols to enhance diagram clarity. Common patterns:\n\n### Infrastructure & Deployment\n```mermaid\ngraph TB\n    Client[👤 User] --> LB[🌐 Load Balancer]\n    LB --> App1[⚙️ App Server 1]\n    LB --> App2[⚙️ App Server 2]\n    App1 --> DB[(💾 Database)]\n    App1 --> Cache[(⚡ Redis)]\n```\n\n### Activity Flow with States\n```mermaid\nflowchart TD\n    Start([🚀 Start]) --> Process[⚙️ Process Data]\n    Process --> Check{✓ Valid?}\n    Check -->|Yes| Save[💾 Save]\n    Check -->|No| Error[❌ Error]\n    Save --> Complete([✅ Complete])\n```\n\n### Microservices Architecture\n```mermaid\ngraph TB\n    API[🌐 API Gateway] --> Auth[🔐 Auth Service]\n    API --> Orders[📋 Order Service]\n    Orders --> Queue[📬 Message Queue]\n    Queue --> Worker[⚙️ Background Worker]\n    Worker --> Storage[📦 Object Storage]\n```\n\n**For complete symbol reference, load:** `references\u002Fguides\u002Funicode-symbols\u002Fguide.md`\n\n## Python Utilities\n\n### Extract Mermaid Diagrams\n\n```bash\n# List all diagrams\npython scripts\u002Fextract_mermaid.py document.md --list-only\n\n# Extract to separate files\npython scripts\u002Fextract_mermaid.py document.md --output-dir diagrams\u002F\n\n# Validate all diagrams\npython scripts\u002Fextract_mermaid.py document.md --validate\n\n# Replace with image references (for Confluence upload)\npython scripts\u002Fextract_mermaid.py document.md --replace-with-images \\\n  --image-format png --output-markdown output.md\n```\n\n### Convert to Images\n\n```bash\n# Single conversion\npython scripts\u002Fmermaid_to_image.py diagram.mmd output.png\n\n# With custom settings\npython scripts\u002Fmermaid_to_image.py diagram.mmd output.svg \\\n  --theme dark --background white --width 1200\n\n# Batch convert directory\npython scripts\u002Fmermaid_to_image.py diagrams\u002F output\u002F --format png --recursive\n\n# From stdin\necho \"graph TD; A-->B\" | python scripts\u002Fmermaid_to_image.py - output.png\n```\n\n## Decision Tree Examples\n\n### Example 1: User Asks for Workflow Diagram\n\n**Input:** \"Show the checkout process workflow\"\n\n**Skill Decision Path:**\n```\n1. Analyze: workflow, process → ACTIVITY DIAGRAM\n2. Load guide: guides\u002Fdiagrams\u002Factivity-diagrams.md\n3. Find pattern: E-commerce checkout (template exists in guide)\n4. Generate using template + Unicode symbols\n5. Output activity diagram with decision points\n```\n\n**Output:** Complete activity diagram with Unicode symbols for cart, payment, order states.\n\n### Example 2: User Provides Spring Boot Code\n\n**Input:** \"Here's my Spring Boot controller, create diagrams\"\n\n**Skill Decision Path:**\n```\n1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT\n2. Load guides:\n   - examples\u002Fspring-boot\u002FREADME.md\n   - guides\u002Fdiagrams\u002Farchitecture-diagrams.md (for structure)\n   - guides\u002Fdiagrams\u002Fsequence-diagrams.md (for method calls)\n   - guides\u002Fdiagrams\u002Factivity-diagrams.md (for business logic)\n3. Generate multiple diagrams:\n   a. Architecture diagram from @RestController\u002F@Service\u002F@Repository annotations\n   b. Sequence diagram from method call chain\n   c. Activity diagram from business logic flow\n4. Output all diagrams with explanations\n```\n\n**Output:** 3-4 diagrams showing different views of the Spring Boot application.\n\n### Example 3: User Wants Infrastructure Documentation\n\n**Input:** \"Document my GCP Cloud Run deployment with AlloyDB\"\n\n**Skill Decision Path:**\n```\n1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM\n2. Load guides:\n   - guides\u002Fdiagrams\u002Fdeployment-diagrams.md\n   - examples\u002Fspring-boot\u002F or examples\u002Ffastapi\u002F (if code provided)\n3. Check for IaC files (Pulumi, Terraform, docker-compose)\n4. Generate deployment diagram with:\n   - Cloud Run services with specs\n   - VPC connector\n   - AlloyDB cluster\n   - Security (IAM, Secret Manager)\n   - Monitoring\n5. Apply Unicode symbols for clarity\n6. Output with resource specifications\n```\n\n**Output:** Complete GCP deployment diagram with all resources labeled.\n\n## High-Contrast Styling\n\n**ALL diagrams MUST use high-contrast colors:**\n\n```mermaid\ngraph TB\n    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen\n    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue\n    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue\n    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black\n\n    %% Every classDef MUST have color: property\n```\n\n**Rules:**\n- Light background → Dark text color\n- Dark background → Light text color\n- Always specify `color:` in every `classDef`\n\n## File Organization\n\n```\ndesign-doc-mermaid\u002F\n├── SKILL.md                          # This file - Main orchestrator\n├── README.md                         # User documentation\n├── CLAUDE.md                         # Claude Code instructions\n│\n├── references\u002F                       # Reference materials\n│   ├── mermaid-diagram-guide.md     # Legacy general guide\n│   └── guides\u002F                       # Specialized guides (load on-demand)\n│       ├── diagrams\u002F\n│       │   ├── activity-diagrams.md      # Workflows, processes\n│       │   ├── deployment-diagrams.md    # Infrastructure, cloud\n│       │   ├── architecture-diagrams.md  # System architecture\n│       │   └── sequence-diagrams.md      # API interactions\n│       ├── code-to-diagram\u002F\n│       │   └── README.md                 # Master guide for code analysis\n│       ├── unicode-symbols\u002F\n│       │   └── guide.md                  # Complete symbol reference\n│       └── troubleshooting.md        # Common syntax errors & fixes\n│\n├── assets\u002F                           # Design document templates\n│   ├── architecture-design-template.md\n│   ├── api-design-template.md\n│   ├── feature-design-template.md\n│   ├── database-design-template.md\n│   └── system-design-template.md\n│\n├── scripts\u002F                          # Python utilities\n│   ├── extract_mermaid.py           # Extract & validate diagrams\n│   └── mermaid_to_image.py          # Convert to PNG\u002FSVG\n│\n├── examples\u002F                         # Language-specific patterns\n│   ├── spring-boot\u002F                 # Spring Boot patterns\n│   ├── fastapi\u002F                     # FastAPI patterns\n│   ├── react\u002F                       # React patterns\n│   ├── python-etl\u002F                  # Data pipeline patterns\n│   ├── node-webapp\u002F                 # Express.js patterns\n│   └── java-webapp\u002F                 # Traditional Java patterns\n│\n└── references\u002F                       # General Mermaid reference\n    └── mermaid-diagram-guide.md     # Complete Mermaid syntax guide\n```\n\n## Workflow Summary\n\n1. **Analyze user intent** → Determine diagram type, document type, or action needed\n2. **Load appropriate guide(s)** → Read only what's needed (token efficient)\n3. **Apply templates and patterns** → Use examples from guides\n4. **Generate output** → Create diagram or document\n5. **Validate** (optional) → Use scripts to verify\n6. **Convert** (optional) → Export to images if needed\n\n## When to Use What\n\n| User Request | Load This |\n|--------------|-----------|\n| \"activity diagram\", \"workflow\", \"process flow\" | `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` |\n| \"deployment\", \"infrastructure\", \"cloud\", \"k8s\" | `references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md` |\n| \"architecture\", \"system design\", \"components\" | `references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md` + design template |\n| \"API\", \"sequence\", \"interactions\", \"flow\" | `references\u002Fmermaid-diagram-guide.md` (sequence section) |\n| \"Spring Boot code\" | `examples\u002Fspring-boot\u002F` + relevant diagram guides |\n| \"FastAPI code\", \"Python API\" | `examples\u002Ffastapi\u002F` + relevant diagram guides |\n| \"React app\", \"frontend\" | `examples\u002Freact\u002F` + architecture guide |\n| \"ETL\", \"data pipeline\", \"Python batch\" | `examples\u002Fpython-etl\u002F` + activity guide |\n| \"symbols\", \"unicode\", \"emoji\" | `references\u002Fguides\u002Funicode-symbols\u002Fguide.md` |\n| \"syntax error\", \"diagram won't render\", \"troubleshoot\" | `references\u002Fguides\u002Ftroubleshooting.md` |\n| \"extract diagrams\" | `scripts\u002Fextract_mermaid.py` |\n| \"convert to image\", \"PNG\", \"SVG\" | `scripts\u002Fmermaid_to_image.py` |\n| \"create diagram\", \"generate diagram\", \"add diagram to markdown\" | `scripts\u002Fresilient_diagram.py` + `references\u002Fguides\u002Fresilient-workflow.md` |\n| \"design document\", \"full docs\" | `assets\u002F*-design-template.md` + diagram guides |\n\n## Best Practices\n\n1. **Single Responsibility**: One diagram = One concept\n2. **Unicode Enhancement**: Always use semantic symbols for clarity\n3. **High Contrast**: Never skip the `color:` property in styles\n4. **Validate Early**: Use scripts to catch syntax errors\n5. **Template Reuse**: Leverage existing templates and examples\n6. **Load On-Demand**: Only read guides needed for the specific request\n7. **Token Efficiency**: Use hierarchical loading instead of reading everything\n\n## Learning Path\n\n**New to Mermaid?** Start here:\n1. Read `references\u002Fguides\u002Funicode-symbols\u002Fguide.md` for symbol meanings\n2. Read `references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md` for basic patterns\n3. Try examples in `examples\u002Fspring-boot\u002F` or `examples\u002Ffastapi\u002F`\n4. Use `scripts\u002Fextract_mermaid.py --validate` to check your work\n\n**Need to document code?** Follow this:\n1. Identify your framework → Load relevant `examples\u002F{framework}\u002F`\n2. Match code pattern to diagram type\n3. Use templates from guide\n4. Validate with scripts\n\n**Creating design docs?** Follow this:\n1. Choose document type → Load template from `assets\u002F`\n2. Fill in text sections\n3. Load diagram guides as needed for each section\n4. Use Unicode symbols throughout\n5. Save to `docs\u002Fdesign\u002F` with timestamp\n\n---\n\n**Version:** 2.0 (Hierarchical Architecture)\n**Last Updated:** 2025-01-13\n**Maintained by:** Claude Code Skills\n",{"name":5,"description":7},"main","bc8b8fb00ca1ae80f60fcde47575fd707252387a","portfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20","2026-08-11 07:16:22",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add venkataratnamb20\u002Fcursor_experiments --skill design-doc-mermaid",{"tool":36,"command":37},"bunx","bunx skills add venkataratnamb20\u002Fcursor_experiments --skill design-doc-mermaid",{"tool":39,"command":40},"pnpm","pnpm dlx skills add venkataratnamb20\u002Fcursor_experiments --skill design-doc-mermaid","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002FSKILL.md",true,[44,49,55,59,63,67,71,77,81,85,89,93,97,101,105,109,113,117,121,125,129,133,137,141,147,151],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":14,"sourceHtmlUrl":48},".gitignore","OTHER","其他","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002F.gitignore",{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"assets\u002Fapi-design-template.md","ASSET","资产文件",10172,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fassets\u002Fapi-design-template.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"assets\u002Farchitecture-design-template.md",7858,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fassets\u002Farchitecture-design-template.md",{"path":60,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":61,"sourceHtmlUrl":62},"assets\u002Fdatabase-design-template.md",14284,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fassets\u002Fdatabase-design-template.md",{"path":64,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":65,"sourceHtmlUrl":66},"assets\u002Ffeature-design-template.md",11545,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fassets\u002Ffeature-design-template.md",{"path":68,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":69,"sourceHtmlUrl":70},"assets\u002Fsystem-design-template.md",16398,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fassets\u002Fsystem-design-template.md",{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"examples\u002Ffastapi\u002FREADME.md","REFERENCE","参考文档",20681,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Ffastapi\u002FREADME.md",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"examples\u002Fjava-webapp\u002FREADME.md",38993,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Fjava-webapp\u002FREADME.md",{"path":82,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":83,"sourceHtmlUrl":84},"examples\u002Fnode-webapp\u002FREADME.md",21686,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Fnode-webapp\u002FREADME.md",{"path":86,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":87,"sourceHtmlUrl":88},"examples\u002Fpython-etl\u002FREADME.md",26477,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Fpython-etl\u002FREADME.md",{"path":90,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":91,"sourceHtmlUrl":92},"examples\u002Freact\u002FREADME.md",18764,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Freact\u002FREADME.md",{"path":94,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":95,"sourceHtmlUrl":96},"examples\u002Fspring-boot\u002FREADME.md",13720,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fexamples\u002Fspring-boot\u002FREADME.md",{"path":98,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":99,"sourceHtmlUrl":100},"HIGH_CONTRAST_UPDATE.md",6378,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002FHIGH_CONTRAST_UPDATE.md",{"path":102,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":103,"sourceHtmlUrl":104},"README.md",11035,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002FREADME.md",{"path":106,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":107,"sourceHtmlUrl":108},"references\u002Fguides\u002Fcode-to-diagram\u002FREADME.md",26547,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fcode-to-diagram\u002FREADME.md",{"path":110,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":111,"sourceHtmlUrl":112},"references\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md",13916,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fdiagrams\u002Factivity-diagrams.md",{"path":114,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":115,"sourceHtmlUrl":116},"references\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md",33603,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fdiagrams\u002Farchitecture-diagrams.md",{"path":118,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":119,"sourceHtmlUrl":120},"references\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md",18045,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fdiagrams\u002Fdeployment-diagrams.md",{"path":122,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":123,"sourceHtmlUrl":124},"references\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md",27988,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fdiagrams\u002Fsequence-diagrams.md",{"path":126,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":127,"sourceHtmlUrl":128},"references\u002Fguides\u002Fresilient-workflow.md",16172,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Fresilient-workflow.md",{"path":130,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":131,"sourceHtmlUrl":132},"references\u002Fguides\u002Ftroubleshooting.md",16711,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Ftroubleshooting.md",{"path":134,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":135,"sourceHtmlUrl":136},"references\u002Fguides\u002Funicode-symbols\u002Fguide.md",13830,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fguides\u002Funicode-symbols\u002Fguide.md",{"path":138,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":139,"sourceHtmlUrl":140},"references\u002Fmermaid-diagram-guide.md",15332,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Freferences\u002Fmermaid-diagram-guide.md",{"path":142,"resourceType":143,"resourceTypeDesc":144,"sizeBytes":145,"sourceHtmlUrl":146},"scripts\u002Fextract_mermaid.py","SCRIPT","脚本",11479,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fscripts\u002Fextract_mermaid.py",{"path":148,"resourceType":143,"resourceTypeDesc":144,"sizeBytes":149,"sourceHtmlUrl":150},"scripts\u002Fmermaid_to_image.py",10849,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fscripts\u002Fmermaid_to_image.py",{"path":152,"resourceType":143,"resourceTypeDesc":144,"sizeBytes":153,"sourceHtmlUrl":154},"scripts\u002Fresilient_diagram.py",24212,"https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fdesign-doc-mermaid\u002Fscripts\u002Fresilient_diagram.py",[156,164,171,178,185,192],{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":160,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":19},"01M7ACJJAEWJBEWPCQNDW3YEJD","webapp-testing","Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":165,"name":166,"nameZh":6,"description":167,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":168,"categories":169,"keywords":170,"publishedAt":19},"01M7ACJDBPE1PJF2D5DCDH1HSQ","web-design-guidelines","Review UI code for Web Interface Guidelines compliance. Use when asked to \"review my UI\", \"check accessibility\", \"audit design\", \"review UX\", or \"check my site against best practices\".","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fweb-design-guidelines\u002FSKILL.md",[],[],{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":177,"publishedAt":19},"01M7ACJ5PZF5SCZ9J8QNNSBR35","ui-ux-pro-max","UI\u002FUX design intelligence for web and mobile. Searchable local database with 84 styles, 192 color palettes, 74 font pairings, 192 product types, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 stacks (React, Next.js, Vue, Nuxt, Svelte, Astro, SwiftUI, React Native, Flutter, Tailwind, shadcn\u002Fui, Jetpack Compose, Angular, Laravel, JavaFX, WPF, WinUI, Avalonia, Uno Platform, UWP, Three.js, and HTML\u002FCSS). Use when designing, building, or reviewing UI: pages, components, color schemes, typography, layout, accessibility, animation, or data visualization.","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Fui-ux-pro-max\u002FSKILL.md",[],[],{"skillNo":179,"name":180,"nameZh":6,"description":181,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":182,"categories":183,"keywords":184,"publishedAt":19},"01M7ACJ354FK5M4R2QQMG47ZWW","test-driven-development","Use when implementing any feature or bugfix, before writing implementation code","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":191,"publishedAt":19},"01M7ACJ0NB3FQHCWCHBH3PC579","tdd","Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions \"red-green-refactor\", or wants integration tests.","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Ftdd\u002FSKILL.md",[],[],{"skillNo":193,"name":194,"nameZh":6,"description":195,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":196,"categories":197,"keywords":198,"publishedAt":19},"01M7ACHXAV135NJG9SQ2MEA8AZ","tailwind-design-system","Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.","https:\u002F\u002Fgithub.com\u002Fvenkataratnamb20\u002Fcursor_experiments\u002Fblob\u002Fmain\u002Fportfolio\u002Fsinglepage_htmlcssjs\u002F.agents\u002Fskills\u002Ftailwind-design-system\u002FSKILL.md",[],[]]