How to Generate Technical Documentation and Attack Diagrams with Mermaid/PlantUML in reverse-skill

The reverse-skill repository treats diagram creation as a first-class skill, converting natural-language requests into editable Mermaid, PlantUML, or Graphviz source code through the diagram-generator skill located in skills/diagram-generator/.

The reverse-skill project by zhaoxuya520 provides a structured approach to generate technical documentation and attack diagrams with Mermaid/PlantUML through its dedicated skill system. This architecture maps user intent to specific diagram languages using decision tables and pattern templates, producing version-controllable source code that can be rendered on demand. All diagram logic resides under skills/diagram-generator/, integrating with the master routing table at skills/MASTER-ROUTING.md to handle requests containing keywords like "attack path" or "sequence diagram".

Architectural Components of the Diagram Generator

The diagram generation system operates across four distinct layers, each defined by specific files in the repository.

Skill Definition (skills/diagram-generator/SKILL.md) declares the capability, usage policy, and decision table that maps user intent to diagram languages. Pattern Library (skills/diagram-generator/references/diagram-patterns.md) stores compact templates for flowcharts, sequence diagrams, ER diagrams, state diagrams, and PlantUML equivalents. Renderer (skills/diagram-generator/scripts/render_diagram.py) provides optional local rendering via external tools like Mermaid-CLI (mmdc), Graphviz (dot), or PlantUML (java -jar plantuml.jar). Routing Integration (skills/MASTER-ROUTING.md) lists "diagram-generator" as the handler for requests containing Mermaid, PlantUML, or attack diagram keywords.

The Five-Step Diagram Generation Workflow

When you request a diagram, the skill executes a standardized pipeline defined in SKILL.md.

1. Intent Detection – The routing engine matches your request to the diagram-generator skill.
2. Diagram Family Selection – The skill consults the decision table to choose between Mermaid (for quick docs) or PlantUML (for formal UML).
3. Entity Normalization – Input entities, relationships, and states are normalized while preserving security terminology.
4. Source Generation – The skill fills templates from diagram-patterns.md to produce concise diagram source strings.
5. Optional Rendering – If you need static images, render_diagram.py invokes the appropriate external tool.

Generate Technical Documentation with Mermaid

Mermaid is selected when you need quick, Markdown-compatible diagrams for technical documentation or security attack paths. The skill pulls templates from skills/diagram-generator/references/diagram-patterns.md to generate the source code.

Flowcharts for System Architecture

Use the flowchart template to visualize component relationships. The skill generates flowchart TD (top-down) syntax for architectural overviews.

flowchart TD
    A[Client] --> B[Web Server]
    B --> C[Application]
    C --> D[Database]
    D -->|reads| E[Cache]
    E -->|updates| D

This output follows the flowchart template conventions defined in diagram-patterns.md.

Sequence Diagrams for Attack Paths

For narrating attack chains like phishing-to-C2, the skill selects the sequenceDiagram template from line 47 of diagram-patterns.md.

sequenceDiagram
    participant Attacker
    participant Target
    Attacker->>Target: Phishing email
    Target-->>Attacker: Click link
    Attacker->>Target: Execute payload
    Target->>Attacker: Command & Control channel opened

Create Formal UML Diagrams with PlantUML

When your request explicitly demands UML notation, the decision table in SKILL.md routes the generation to PlantUML. This produces formal component, class, or deployment diagrams suitable for technical specifications.

@startuml
package "Web Tier" {
    [Load Balancer] --> [Web Server 1]
    [Load Balancer] --> [Web Server 2]
}
package "App Tier" {
    [Web Server 1] --> [App Service]
    [Web Server 2] --> [App Service]
}
[App Service] --> [Database]
@enduml

PlantUML generation follows the rules specified in the "PlantUML generation rules" section of SKILL.md.

Rendering Diagrams to Static Images

While the primary output is editable source code, you can generate PNG, SVG, or PDF artifacts using the renderer script. The render_diagram.py file inspects input extensions to automatically select the correct rendering engine.

Render Mermaid to SVG

python "skills/diagram-generator/scripts/render_diagram.py" diagram.mmd --format svg --out diagram.svg

The script detects the .mmd extension and invokes the Mermaid-CLI (mmdc) to produce the vector graphic.

Render PlantUML to PNG

python "skills/diagram-generator/scripts/render_diagram.py" diagram.puml --format png --out diagram.png

For .puml files, the script falls back to java -jar plantuml.jar to generate the raster image.

Key Files Reference

File	Role
skills/diagram-generator/SKILL.md	Contains the decision table and usage policies for selecting diagram languages.
skills/diagram-generator/references/diagram-patterns.md	Stores templates for Mermaid flowcharts, sequence diagrams, and PlantUML components.
skills/diagram-generator/scripts/render_diagram.py	Python helper for converting source files to PNG, SVG, or PDF using external tools.
skills/MASTER-ROUTING.md	Global routing table that directs diagram-related keywords to this skill.
skills/diagram-generator/README.md	Human-readable documentation explaining the skill's purpose and AI assistant integration.

Summary

• The diagram-generator skill converts natural language into diagram source code using templates from skills/diagram-generator/references/diagram-patterns.md.
• Mermaid handles quick technical documentation and attack path diagrams, while PlantUML addresses formal UML requirements as defined in SKILL.md.
• The decision logic resides in skills/diagram-generator/SKILL.md, which contains the routing table mapping intents to specific diagram families.
• Use python skills/diagram-generator/scripts/render_diagram.py to convert source files to images via Mermaid-CLI (mmdc), Graphviz (dot), or PlantUML (java -jar).
• All output remains editable and version-controllable as plain text, supporting traceability in security documentation workflows.

Frequently Asked Questions

How does reverse-skill decide between Mermaid and PlantUML?

According to the decision table in skills/diagram-generator/SKILL.md, the skill selects Mermaid for quick documentation and Markdown-compatible outputs, and PlantUML when the request explicitly requires formal UML notation. This mapping occurs during the Diagram Family Selection phase of the workflow.

Can I generate attack path diagrams without installing rendering tools?

Yes. The skill generates editable source code (e.g., Mermaid sequenceDiagram syntax) that you can version-control in your repository. Local rendering via render_diagram.py is optional and only required when you need to produce static PNG, SVG, or PDF artifacts for reports.

What file types does the render_diagram.py script support?

The script inspects file extensions to select the appropriate renderer: .mmd files invoke Mermaid-CLI (mmdc), .dot files use Graphviz (dot), and .puml files trigger java -jar plantuml.jar. You specify the output format using the --format flag.

Where are the diagram templates stored?

All pattern templates for flowcharts, sequence diagrams, class diagrams, and PlantUML components are stored in skills/diagram-generator/references/diagram-patterns.md. The skill references these templates during the Source Generation phase to produce consistent, repository-standard diagram syntax.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}