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

> Easily generate technical documentation and attack diagrams with Mermaid and PlantUML. The reverse-skill repository converts natural language to editable diagram source code.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/diagram-patterns.md) to produce concise diagram source strings.
5. **Optional Rendering** – If you need static images, [`render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```mermaid
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/diagram-patterns.md).

```mermaid
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) routes the generation to PlantUML. This produces formal component, class, or deployment diagrams suitable for technical specifications.

```plantuml
@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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/render_diagram.py) file inspects input extensions to automatically select the correct rendering engine.

### Render Mermaid to SVG

```bash
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

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md) | Contains the decision table and usage policies for selecting diagram languages. |
| [`skills/diagram-generator/references/diagram-patterns.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/references/diagram-patterns.md) | Stores templates for Mermaid flowcharts, sequence diagrams, and PlantUML components. |
| [`skills/diagram-generator/scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Global routing table that directs diagram-related keywords to this skill. |
| [`skills/diagram-generator/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md).
- The decision logic resides in [`skills/diagram-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/references/diagram-patterns.md). The skill references these templates during the Source Generation phase to produce consistent, repository-standard diagram syntax.