Diagram Generator

Diagram Generator

Purpose

Create clear, editable diagrams from messy or structured inputs. Prefer text-based diagram source first so the result can be reviewed, versioned, and refined. Render to files only when the user asks for an image/PDF or when a downloadable artifact would materially help.

Default workflow

1. Identify the user's intent, audience, and source material. 2. Choose the diagram family and language using the decision table below. 3. Normalize entities, relationships, labels, states, branches, and time/order information before writing diagram code. 4. Generate concise, readable diagram source. 5. Validate the syntax mentally and, when creating files, run scripts/render_diagram.py. 6. Return the diagram source plus a short note about assumptions. When files are generated, include links to the output files.

Do not over-ask for clarification. If the request is underspecified, make reasonable assumptions and label them briefly.

Diagram language decision table

Use Mermaid unless another language is clearly better.

Output policy

• Always provide editable source unless the user explicitly asks only for an image.
• Default to a single best diagram. Offer alternatives only when genuinely useful.
• Prefer stable, simple syntax over fancy features that may not render in older Mermaid/PlantUML versions.
• Use short labels. Split long text into notes outside the diagram when needed.
• Avoid ambiguous node IDs. Use ASCII IDs and human-readable labels.
• Preserve user terminology, but standardize capitalization within a diagram.
• For technical diagrams, include boundaries such as client, service, database, queue, external API, and operator/user when they are implied.
• For business-process diagrams, distinguish happy path, decision points, failures, retries, and manual steps when present.
• For diagrams created from uncertain text, include an Assumptions section after the code.

Mermaid generation rules

Consult references/diagram-patterns.md for compact templates.

General Mermaid rules:

• Start with the correct diagram directive, for example flowchart TD, sequenceDiagram, erDiagram, gantt, mindmap, or journey.
• For flowcharts, use flowchart TD unless the user asks for left-to-right; use flowchart LR for architecture and pipelines.
• Use subgraphs for swimlanes or architecture layers. Name subgraphs with readable labels.
• Keep node IDs stable and ASCII-only, for example ingest_service[Ingest Service].
• Quote labels that contain punctuation likely to confuse the parser.
• Use decision diamonds for branching: decision{Condition?}.
• Use consistent edge labels: -- yes -->, -- no -->, -. async .->, or == critical ==> only when meaningful.
• In sequence diagrams, declare participants before messages. Use actor for humans and participant for systems.
• Use alt/else/end, opt/end, loop/end, and par/and/end blocks for conditional, optional, repeated, and parallel flows.

Graphviz DOT generation rules

Use Graphviz for large, dense, or layout-sensitive relationship diagrams.

• Prefer digraph G for directed relationships and graph G for undirected networks.
• Set layout-friendly graph attributes at the top: rankdir=LR, nodesep, ranksep, and splines=true when helpful.
• Use subgraph cluster_name for boundaries and subsystems.
• Use plain labels and restrained styling.
• Use edge labels only when they add meaning.
• For many nodes, group by domain with clusters and avoid crossing-heavy all-to-all edges.

PlantUML generation rules

Use PlantUML when the user asks for UML or needs formal UML notation.

• Wrap diagrams with @startuml and @enduml.
• Use actor, participant, database, queue, collections, or component stereotypes when useful.
• Use package, rectangle, or node for architecture boundaries.
• For class diagrams, include only important fields/methods unless the user asks for exhaustive detail.
• For activity diagrams, use clear start/end markers and explicit branch labels.

SVG generation rules

Use SVG only when text diagram languages cannot express the requested visual reliably.

• Keep SVG simple, accessible, and editable.
• Include <title> and meaningful text labels.
• Prefer rectangles, lines, arrows, and groups over complex paths.
• Do not embed external fonts or remote images.

Rendering files

When the user asks for PNG/SVG/PDF, create a source file and run:

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> 是本包 skills/ 目录的实际路径，AI 应自动检测。

The renderer is intentionally dependency-tolerant. It tries common local tools and reports actionable installation hints if a renderer is unavailable. Do not claim an image was rendered unless the script completed successfully and the output file exists.

Validation checklist

Before finalizing:

• The diagram type matches the user's task.
• The source is syntactically plausible for the chosen language.
• Labels are short enough to fit.
• Edges and message order reflect the input accurately.
• Assumptions are called out when the input was incomplete.
• For generated files, the output exists and opens or has nonzero size.

Common response template

Use this structure for most diagram answers:

下面是可编辑的 [language] 版本：

[source]

Assumptions:
- [only if needed]

Rendered file: [link] [only if generated]

For English user requests, respond in English. For Chinese user requests, respond in Chinese unless they ask otherwise.

---

按需自举（On-Demand Bootstrap）

自动化能力边界

说明

本 skill 主要输出文本格式的图表源码（Mermaid/DOT/PlantUML），不一定需要本地渲染工具。只有当用户明确要求生成 PNG/SVG/PDF 文件时才需要对应的渲染器。

如果渲染器不可用，scripts/render_diagram.py 会输出安装提示而不是报错。

---

路由上下文

上游入口: skills/SKILL.md（总控）、routing.md 触发条件: 用户说"画图"、"流程图"、"架构图"、"攻击路径图"、"时序图"、"Mermaid"、"Graphviz"、"PlantUML" 下游出口:

• 生成的图表可嵌入 docs-generator/ 的报告中
• 攻击路径图可配合 pentest-tools/ 的渗透报告

同级关联模块: docs-generator/（报告中嵌入图表）

Diagram Generator Skill

This skill helps AI assistants create editable diagrams in Mermaid, Graphviz DOT, PlantUML, and SVG, and optionally render them with local tools.

Diagram Patterns

Use these compact patterns when generating diagram source. Prefer adapting the pattern instead of inventing complex syntax.

Mermaid flowchart

flowchart TD
  start([Start]) --> receive[Receive request]
  receive --> valid{Valid?}
  valid -- yes --> process[Process request]
  valid -- no --> fix[Ask for missing info]
  process --> finish([Finish])

Mermaid swimlane-style flowchart

flowchart LR
  subgraph customer[Customer]
    c1[Submit order]
  end
  subgraph app[Application]
    a1[Validate order]
    a2[Create invoice]
  end
  subgraph ops[Operations]
    o1[Review exception]
  end
  c1 --> a1
  a1 -- valid --> a2
  a1 -- invalid --> o1

Mermaid architecture

flowchart LR
  user[User] --> web[Web App]
  web --> api[API Service]
  api --> db[(Database)]
  api -. async .-> queue[[Queue]]
  queue --> worker[Worker]
  worker --> object_store[(Object Store)]

Mermaid sequence diagram

sequenceDiagram
  actor User
  participant Web
  participant API
  database DB
  User->>Web: Submit request
  Web->>API: POST /request
  API->>DB: Save record
  DB-->>API: OK
  API-->>Web: 201 Created
  Web-->>User: Show confirmation

Mermaid ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : appears_in
  CUSTOMER {
    string id PK
    string email
  }
  ORDER {
    string id PK
    string customer_id FK
    datetime created_at
  }

Mermaid state diagram

stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted: submit
  Submitted --> Approved: approve
  Submitted --> Rejected: reject
  Approved --> [*]
  Rejected --> Draft: revise

Mermaid class diagram

classDiagram
  class User {
    +string id
    +string email
    +login()
  }
  class Order {
    +string id
    +decimal total
    +submit()
  }
  User "1" --> "0..*" Order : places

Mermaid gantt

gantt
  title Delivery Plan
  dateFormat  YYYY-MM-DD
  section Discovery
  Requirements        :a1, 2026-01-01, 5d
  Design              :after a1, 4d
  section Build
  Implementation      :2026-01-10, 10d
  QA                  :2026-01-22, 5d

Mermaid mindmap

mindmap
  root((Product Launch))
    Research
      Customer interviews
      Market scan
    Build
      Prototype
      QA
    Go-to-market
      Pricing
      Campaign

Mermaid user journey

journey
  title Trial Signup Journey
  section Discover
    Visit landing page: 4: User
    Compare pricing: 3: User
  section Activate
    Create account: 5: User
    Invite teammate: 4: User

Graphviz dependency graph

digraph G {
  rankdir=LR;
  node [shape=box, style=rounded];
  app -> api;
  api -> auth;
  api -> db;
  worker -> queue;
  worker -> db;
}

Graphviz clustered architecture

digraph G {
  rankdir=LR;
  compound=true;
  node [shape=box, style=rounded];

  subgraph cluster_client {
    label="Client";
    web;
    mobile;
  }

  subgraph cluster_platform {
    label="Platform";
    api;
    worker;
    queue [shape=cylinder];
    db [shape=cylinder];
  }

  web -> api;
  mobile -> api;
  api -> db;
  api -> queue;
  queue -> worker;
  worker -> db;
}

PlantUML sequence

@startuml
actor User
participant Web
participant API
database DB
User -> Web: Submit request
Web -> API: POST /request
API -> DB: Save record
DB --> API: OK
API --> Web: 201 Created
Web --> User: Confirmation
@enduml

PlantUML component architecture

@startuml
actor User
rectangle "Client" {
  [Web App]
}
rectangle "Backend" {
  [API Service]
  queue "Queue"
  [Worker]
  database "Database"
}
User --> [Web App]
[Web App] --> [API Service]
[API Service] --> Database
[API Service] --> Queue
Queue --> [Worker]
[Worker] --> Database
@enduml

SVG fallback

<svg xmlns="http://www.w3.org/2000/svg" width="900" height="360" viewBox="0 0 900 360" role="img">
  <title>Simple process diagram</title>
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
      <path d="M0,0 L0,6 L9,3 z" />
    </marker>
  </defs>
  <rect x="40" y="120" width="160" height="70" rx="10" fill="white" stroke="black" />
  <text x="120" y="160" text-anchor="middle">Start</text>
  <line x1="200" y1="155" x2="320" y2="155" stroke="black" marker-end="url(#arrow)" />
  <rect x="320" y="120" width="180" height="70" rx="10" fill="white" stroke="black" />
  <text x="410" y="160" text-anchor="middle">Process</text>
</svg>