{
  "markdown": "# Mermaid Architect - Comprehensive Diagram & Documentation Skill\n\n**Version 2.0** - Hierarchical architecture with intelligent orchestration\n\nA powerful Claude Code skill for creating Mermaid diagrams and design documents using on-demand guide loading, code-to-diagram generation, and Python utilities.\n\n## Installation\n\n### One-Click Install via Skilz Marketplace\n\nInstall this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):\n\n```bash\nskilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid\n```\n\n### Manual Installation\n\nClone directly into your Claude Code skills directory:\n\n```bash\n# Navigate to your skills directory\ncd ~/.claude/skills\n\n# Clone the repository\ngit clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git\n```\n\n### Verify Installation\n\nAfter installation, verify the skill is available:\n\n```bash\n# List installed skills\nls ~/.claude/skills/design-doc-mermaid\n\n# Or ask Claude Code\n# \"List my installed skills\"\n```\n\n## What This Skill Does\n\n**Intelligent Diagram Generation:**\n- Activity diagrams (workflows, processes, business logic)\n- Deployment diagrams (cloud infrastructure, K8s, serverless)\n- Architecture diagrams (system components, microservices)\n- Sequence diagrams (API flows, service interactions)\n- Complete design documents with embedded diagrams\n\n**Code-to-Diagram Conversion:**\n- Extract architecture from Spring Boot applications\n- Generate deployment diagrams from configuration files\n- Create sequence diagrams from method calls\n- Document ETL pipelines and data flows\n\n**Diagram Management:**\n- Extract Mermaid diagrams from Markdown files\n- Validate diagram syntax with mermaid-cli\n- Convert diagrams to PNG/SVG images\n- Batch process entire directories\n\n## Quick Start\n\n### Create an Activity Diagram\n\n```\nUser: \"Create an activity diagram for user registration with email verification\"\n```\n\nThe skill will:\n1. Load `references/guides/diagrams/activity-diagrams.md`\n2. Use the registration pattern template\n3. Add Unicode symbols (🔐 for security, 📧 for email, ✅ for success)\n4. Apply high-contrast styling\n5. Output complete Mermaid diagram\n\n### Generate from Code\n\n```\nUser: \"Here's my Spring Boot application.yml - generate a deployment diagram\"\n```\n\nThe skill will:\n1. Analyze configuration (datasource, cache, security)\n2. Load `references/guides/diagrams/deployment-diagrams.md`\n3. Load `examples/spring-boot/README.md`\n4. Map config to cloud resources\n5. Generate deployment diagram with resource specs\n\n### Create Design Document\n\n```\nUser: \"Create an API design document for the contacts API\"\n```\n\nThe skill will:\n1. Load `assets/api-design-template.md`\n2. Load relevant diagram guides (sequence, ER, architecture)\n3. Generate complete document with embedded diagrams\n4. Save to `docs/design/api-contacts-v1-2025-01-13.md`\n\n## Structure\n\n### Hierarchical Organization\n\n```\nmermaid-architect/\n├── SKILL.md                          # Main orchestrator with decision tree\n├── README.md                         # This file\n├── CLAUDE.md                         # Claude Code instructions\n│\n├── references/                       # Reference materials\n│   ├── mermaid-diagram-guide.md     # Legacy general guide\n│   └── guides/                       # Specialized guides (load on-demand)\n│       ├── diagrams/\n│       │   ├── activity-diagrams.md      # ✅ Complete\n│       │   ├── deployment-diagrams.md    # ✅ Complete\n│       │   ├── architecture-diagrams.md  # ✅ Complete\n│       │   └── sequence-diagrams.md      # ✅ Complete\n│       ├── code-to-diagram/\n│       │   └── README.md                 # ✅ Complete (master guide)\n│       ├── unicode-symbols/\n│       │   └── guide.md                  # ✅ Complete (100+ symbols)\n│       └── troubleshooting.md        # ✅ Complete (28 common errors)\n│\n├── scripts/                          # Python utilities\n│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams\n│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG\n│\n├── examples/                         # Language-specific patterns\n│   ├── spring-boot/                 # ✅ Complete\n│   ├── fastapi/                     # ✅ Complete\n│   ├── react/                       # ✅ Complete\n│   ├── python-etl/                  # ✅ Complete\n│   ├── node-webapp/                 # ✅ Complete\n│   └── java-webapp/                 # ✅ Complete\n│\n└── assets/                           # 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\n## Key Features\n\n### 1. Unicode Semantic Symbols\n\nEvery diagram uses meaningful Unicode symbols:\n\n```mermaid\ngraph TB\n    User[👤 Client] --> Gateway[🌐 API Gateway]\n    Gateway --> Auth[🔐 Auth Service]\n    Gateway --> API[⚙️ API Service]\n    API --> DB[(💾 Database)]\n    API --> Cache[(⚡ Redis)]\n    API --> Queue[📬 Message Queue]\n    Queue --> Worker[⚙️ Background Worker]\n```\n\n**Symbol Categories:**\n- Infrastructure: ☁️ 🌐 🔌 📡 🗄️\n- Compute: ⚙️ ⚡ 🔄 🚀 💨\n- Data: 💾 📦 📊 📈 🗃️\n- Messaging: 📨 📬 📤 📥 🐰\n- Security: 🔐 🔑 🛡️ 🚪 👤\n- Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌\n\n### 2. High-Contrast Styling\n\nAll diagrams use accessible, high-contrast colors - see SKILL.md for full details.\n\n### 3. Python Utilities\n\n#### Extract Diagrams\n\n```bash\n# List all diagrams in a file\npython scripts/extract_mermaid.py document.md --list-only\n\n# Extract to separate .mmd files\npython scripts/extract_mermaid.py document.md --output-dir diagrams/\n\n# Validate all diagrams\npython scripts/extract_mermaid.py document.md --validate\n\n# Replace diagrams with image references (for Confluence)\npython scripts/extract_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 file\npython scripts/mermaid_to_image.py diagram.mmd output.png\n\n# Custom theme and size\npython scripts/mermaid_to_image.py diagram.mmd output.svg \\\n  --theme dark --background white --width 1200\n\n# Batch convert directory\npython scripts/mermaid_to_image.py diagrams/ output/ \\\n  --format png --recursive\n\n# From stdin\necho \"graph TD; A-->B\" | python scripts/mermaid_to_image.py - output.png\n```\n\n## Requirements\n\n### For Diagram Generation\n- Claude Code skill system (automatic)\n- Guides and templates (included in this skill)\n\n### For Validation & Image Conversion\n```bash\n# Install mermaid-cli globally\nnpm install -g @mermaid-js/mermaid-cli\n\n# Verify installation\nmmdc --version\n```\n\n### For Python Scripts\n- Python 3.7+\n- No additional packages required (uses stdlib only)\n\n## Learning Path\n\n### New to Mermaid Diagrams?\n\n1. **Start with Activity Diagrams** - Read `references/guides/diagrams/activity-diagrams.md`\n2. **Learn Unicode Symbols** - Read `references/guides/unicode-symbols/guide.md`\n3. **Try an Example** - Use patterns from `examples/spring-boot/`\n4. **Validate Your Work** - Run `python scripts/extract_mermaid.py --validate`\n\n### Need to Document Existing Code?\n\n1. **Identify Framework** - Spring Boot, FastAPI, React, etc.\n2. **Load Example Guide** - Read `examples/{your-framework}/README.md`\n3. **Match Patterns** - Find similar code patterns in examples\n4. **Generate Diagrams** - Use templates from guides\n5. **Validate** - Use validation scripts\n\n### Creating Design Documents?\n\n1. **Choose Template Type** - Architecture, API, Feature, Database, or System\n2. **Load Template** - Read from `assets/{type}-design-template.md`\n3. **Fill Sections** - Replace placeholders with actual content\n4. **Add Diagrams** - Load diagram guides as needed for each section\n5. **Use Symbols** - Enhance with Unicode symbols throughout\n6. **Save** - Place in `docs/design/` with timestamp\n\n## How the Hierarchical System Works\n\n### Traditional Approach (Inefficient)\n- Load entire skill documentation (~50KB)\n- AI processes all templates and examples\n- High token usage\n- Slow response time\n\n### Hierarchical Approach (Efficient)\n1. **User makes request** → AI analyzes intent\n2. **Decision tree activates** → Determines needed guides\n3. **Load only what's needed** → Reads specific guide (~2-5KB)\n4. **Generate output** → Uses targeted templates\n5. **Token efficient** → 10x less context needed\n\n### Example Flow\n\n**User:** \"Create deployment diagram for my Docker Compose setup\"\n\n**Decision Tree:**\n```\n1. Analyze: \"deployment diagram\" + \"Docker Compose\"\n2. Determine: deployment-diagrams.md needed\n3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)\n4. Find pattern: Docker Compose template exists\n5. Generate: Using template + Unicode symbols\n6. Output: Complete diagram in <30 seconds\n```\n\n**Tokens Used:** ~2,000 (vs ~10,000 with traditional approach)\n\n## Completion Status\n\n✅ **Complete:**\n- Hierarchical decision tree orchestrator\n- Activity diagram guide with templates\n- Deployment diagram guide (AWS, GCP, K8s, serverless, Docker)\n- Unicode symbols guide (100+ symbols)\n- Extract Mermaid script with validation\n- Mermaid to image conversion script\n- Spring Boot code-to-diagram examples\n- Design document templates (5 types)\n- High-contrast styling system\n\n🚧 **In Progress:**\n- FastAPI examples\n- React component architecture examples\n- Python ETL pipeline examples\n\n📋 **Planned:**\n- Architecture diagrams guide\n- Sequence diagrams guide\n- Code-to-diagram master guide\n- Node.js/Express examples\n- Java web app examples\n\n## Contributing\n\nTo add a new diagram type guide:\n\n1. Create guide in `references/guides/diagrams/{type}-diagrams.md`\n2. Include:\n   - When to use\n   - Basic syntax\n   - Common patterns (3-5 templates)\n   - Unicode symbol examples\n   - Best practices\n3. Update `SKILL.md` decision tree\n4. Add examples with code mappings\n\nTo add a new language example:\n\n1. Create directory in `examples/{framework}/`\n2. Add `README.md` with:\n   - Framework overview\n   - Architecture diagram from structure\n   - Deployment diagram from config\n   - Sequence diagram from code\n   - Activity diagram from logic\n3. Update `SKILL.md` code-to-diagram table\n\n## License\n\nPart of Claude Code Skills - MIT License\n\n## Related Skills\n\n- **confluence** - Upload diagrams to Confluence\n- **plantuml** - Alternative diagram format\n\n## Links\n\n- [GitHub Repository](https://github.com/SpillwaveSolutions/design-doc-mermaid)\n- [Skilz Marketplace Listing](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)\n- [Mermaid Official Documentation](https://mermaid.js.org/)\n\n---\n\n**Version:** 2.0.0\n**Updated:** 2025-01-13\n**Maintained by:** SpillwaveSolutions\n",
  "bytes": 10637,
  "sha": "7e9a9cdde9bd7373ac006b5fe3f3be66447ecf328b88294d32b3b32e88ca4a6a",
  "repo_slug": "spillwavesolutions/design-doc-mermaid",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_spillwavesolutions_design_doc_mermaid_de_ad71280d/readme"
}