mermaid-diagrams

---

name: mermaid-diagrams description: Generate Mermaid diagrams from code analysis and natural language descriptions using Bun/TypeScript license: MIT compatibility: opencode metadata: audience: developers workflow: documentation version: 1.0.0 language: typescript runtime: bun

What I do

• Generate professional Mermaid diagrams from code analysis (Python, JavaScript, TypeScript)
• Convert natural language descriptions into visual flowcharts and sequence diagrams
• Create multiple diagram types: flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, git graphs
• Validate and optimize Mermaid syntax automatically
• Support batch processing for multiple diagram generation
• Provide extensible architecture for custom analyzers and generators

When to use me

Use this skill when you need to:

• Document code architecture - Generate flowcharts from authentication flows, API endpoints, or business logic
• Create sequence diagrams - Visualize interactions between services, users, and systems
• Design system architecture - Generate class diagrams and component relationships
• Plan project timelines - Create Gantt charts for project management
• Visualize workflows - Convert text descriptions into clear visual processes
• Analyze existing codebases - Understand complex code structure through diagrams

I specialize in:

• Automated diagram generation from source code
• Natural language to visual conversion
• Syntax validation and optimization
• Batch processing for documentation generation
• Integration with modern Bun/TypeScript development workflows

How I work

Core Capabilities

1. Code Analysis Engine

   • Parse Python functions and classes
   • Extract JavaScript/TypeScript module structures
   • Identify function calls and dependencies
   • Generate node-edge relationships for diagrams

2. Text-to-Diagram Conversion

   • Parse natural language descriptions
   • Extract actors, actions, and decision points
   • Map concepts to appropriate diagram elements
   • Generate structured Mermaid syntax

3. Multiple Diagram Types

   • Flowcharts: Process flows, decision trees, authentication flows
   • Sequence Diagrams: Service interactions, API calls, user journeys
   • Class Diagrams: Software architecture, data models, class relationships
   • State Diagrams: State machines, application lifecycle, user states
   • Gantt Charts: Project timelines, task scheduling, milestone planning
   • Git Graphs: Version history, branch management, release patterns

4. Validation & Optimization

   • Syntax checking for all Mermaid diagram types
   • Layout optimization for better readability
   • Error detection and helpful suggestions
   • Performance optimization for large diagrams

Technical Implementation

The skill uses a modular architecture:

Copy// Core components
- MermaidDiagramsSkill: Main skill class
- CodeAnalyzer: Source code parsing and analysis
- TextAnalyzer: Natural language processing
- MermaidGenerator: Diagram code generation
- MermaidValidator: Syntax validation and optimization

Usage Patterns

From Code Analysis:

Copyconst skill = await createSkill();
const result = await skill.analyze("src/auth/", "flowchart");
console.log(result.mermaid_code);

From Text Description:

Copyconst result = await skill.generate(
  "User logs in, system validates credentials, redirects to dashboard"
);

Batch Generation:

Copyconst results = await skill.batchGenerate("config.json", "docs/");

Output Format

All results include:

• Generated Mermaid code (ready for markdown)
• Analysis metadata (source information)
• Validation results (errors, warnings, suggestions)
• Optional file output paths

Integration Points

I work well with:

• documentation-writer - for comprehensive documentation
• code-review - for visualizing code changes
• git-release - for release workflow diagrams

Requirements & Limitations

Requirements

• Bun runtime environment
• TypeScript support
• File system access for code analysis
• Node.js/Bun APIs for file operations

Limitations

• Supports Python, JavaScript, and TypeScript code analysis
• Text analysis works best with structured descriptions
• Large codebases may require selective analysis patterns
• Complex natural language may need clarification

Best Practices

• Use specific, focused code paths for analysis
• Provide clear, structured text descriptions
• Configure exclude patterns for large codebases
• Validate generated diagrams before use
• Use batch processing for documentation generation

Focus on providing clear, accurate visual representations that enhance understanding and communication of complex concepts.