Diagram
Use this skill when the user wants a rendered static diagram, a validated diagram source artifact, or a revision to an existing diagram source.
Default to Mermaid unless the user asks for another format or the shape is a better fit for another adapter:
- Mermaid: sequence, flowchart, state, ER, class, gantt, git-graph, mindmap, and pie diagrams.
- PlantUML: UML sequence/component/activity/deployment diagrams when the user already uses PlantUML or asks for it.
- Graphviz DOT: topology, dependency graphs, and layouts where rank/direction control matters.
- Excalidraw JSON: hand-drawn-style editable sketches when the user asks for an editable canvas.
Tool Surface
Use the runtime tools directly:
diagram_create: create source, validate it, save source, and optionally render.
diagram_update: update existing source or source artifact, validate it, save a new source artifact, and optionally render.
diagram_validate: validate source only; do not render.
The tool output includes these fields:
{
"success": true,
"valid": true,
"source": "...",
"source_artifact_ref": "/workspace/.generated-diagrams/skills/diagram/diagram-...",
"rendered_artifact_ref": "/workspace/.generated-diagrams/skills/diagram/diagram-...",
"type": "flowchart",
"format": "mermaid",
"artifacts": [],
"runtime_events": [],
"warnings": []
}
On validation failure, success and valid are false and errors plus
suggested_fix may be present. When render_to is "none",
rendered_artifact_ref is null. Invalid source is still saved with
source_artifact_valid: false so the operator can inspect or repair it.
Default Workflow
- Pick the diagram type before writing syntax. If uncertain, set
type to auto, but prefer an explicit type when the user request clearly names one.
- For Mermaid, read references/mermaid-types.md when you need grammar examples or when the diagram type is not obvious.
- Draft complete source yourself when the user needs a specific diagram. Do not rely on the tool's generated starter unless the request is generic.
- Call
diagram_validate before rendering when you wrote or revised source manually.
- If validation fails, use the returned
errors and suggested_fix, revise once, then validate again. Make at most 2 fix-up attempts before surfacing the failure with the invalid source artifact. The runtime also caps automatic pre-render fix-up at 2 attempts.
- Call
diagram_create or diagram_update with render_to set to svg by default. Use png or pdf only when requested and the adapter can render that target.
- Return the source artifact and rendered artifact paths to the user.
Type Selection
Use these defaults:
| User intent |
Type |
| messages, API call flow, actors, request/response |
sequence |
| process, decision tree, pipeline, system flow |
flowchart |
| lifecycle, status machine, transitions |
state |
| database schema, entities, relationships |
er |
| classes, interfaces, inheritance, methods |
class |
| timeline, schedule, milestones, roadmap |
gantt |
| branches, commits, merges, release train |
git-graph |
| brainstorm, taxonomy, concept map, outline |
mindmap |
| shares, proportions, percentages |
pie |
Mermaid Rules
- Use the canonical header for the selected type.
- Keep labels short and ASCII-safe unless the user provided exact labels.
- Quote labels when Mermaid grammar requires it, especially pie chart slices.
- Avoid unsupported Markdown inside labels.
- Prefer
flowchart TD or flowchart LR; do not mix both in one source.
- In
sequenceDiagram, define participants when names are long or reused.
- In
gantt, include dateFormat and stable task ids when using dependencies.
- In
erDiagram, include cardinality on relationships.
Update Rules
For diagram_update, preserve the existing type and format unless the user explicitly asks to convert. When the user gives natural-language update instructions:
- Read the existing source artifact when needed.
- Apply the change to the source yourself.
- Validate the full updated source.
- Call
diagram_update with the complete updated source, original format/type, and desired render_to.
If the user only asks to annotate a diagram and exact placement does not matter, the tool can add a small update annotation when passed only artifact_ref plus instructions.
Adapter Notes
- Mermaid and Graphviz use local renderers when available. If a renderer is not installed, SVG requests fall back to source-backed SVG artifacts so the operator still gets an embed-ready file.
- Mermaid validation checks the diagram header and, for flowchart, state, and class diagrams, bracket and quote balance. Full syntax checking happens only when
mmdc renders the source, so re-read the diagram-type grammar before drafting when mmdc is not installed.
- PlantUML rendering uses
HYBRIDCLAW_PLANTUML_SERVER_URL or PLANTUML_SERVER_URL when configured. Without a server, SVG requests fall back to source-backed SVG artifacts. Operators are responsible for pointing this setting only at a trusted PlantUML server with appropriate network egress controls.
- Excalidraw defaults to
render_to: "none" because JSON is the editable deliverable. Use render_to: "svg" when a static preview is requested; the runtime renders the JSON elements directly to SVG.
- Local Mermaid and Graphviz renders use short-lived OS temp directories. Normal tool completion removes them; process-level termination such as SIGKILL may leave temporary source copies for the OS temp cleaner.
Diagram render usage is reported as a zero-cost budget hook; LLM tokens are only consumed when the model drafts or repairs source.
Runtime Hooks
Rendered diagrams include a diagram.rendered event in runtime_events.
Validation failures include a diagram.validation_failed event with the
validation errors and source artifact path when one was persisted. Diagram
artifacts are stored under the skill-scoped path
.generated-diagrams/skills/diagram/.
Stakes
Diagram rendering is F8 low stakes: the output is a file artifact the operator chooses to share. Do not treat generated diagrams as authoritative for security, legal, medical, or financial decisions without separate verification.
1---2name: diagram3description: Create, validate, update, and render diagram-as-code artifacts with Mermaid-first schema awareness plus PlantUML, Graphviz DOT, and Excalidraw JSON adapters.4user-invocable: true5disable-model-invocation: false6metadata:7 source: https://skillmd.com/skills/hybridaione/diagram8 hybridclaw:9 category: publishing10 short_description: "Validated diagram-as-code artifacts."11 tags:12 - diagram13 - mermaid14 - plantuml15 - graphviz16 - excalidraw17 - visualization18 related_skills:19 - excalidraw20 - manim-video21 - write-blog-post22---2324# Diagram2526Use this skill when the user wants a rendered static diagram, a validated diagram source artifact, or a revision to an existing diagram source.2728Default to Mermaid unless the user asks for another format or the shape is a better fit for another adapter:2930- Mermaid: sequence, flowchart, state, ER, class, gantt, git-graph, mindmap, and pie diagrams.31- PlantUML: UML sequence/component/activity/deployment diagrams when the user already uses PlantUML or asks for it.32- Graphviz DOT: topology, dependency graphs, and layouts where rank/direction control matters.33- Excalidraw JSON: hand-drawn-style editable sketches when the user asks for an editable canvas.3435## Tool Surface3637Use the runtime tools directly:3839- `diagram_create`: create source, validate it, save source, and optionally render.40- `diagram_update`: update existing source or source artifact, validate it, save a new source artifact, and optionally render.41- `diagram_validate`: validate source only; do not render.4243The tool output includes these fields:4445```json46{47 "success": true,48 "valid": true,49 "source": "...",50 "source_artifact_ref": "/workspace/.generated-diagrams/skills/diagram/diagram-...",51 "rendered_artifact_ref": "/workspace/.generated-diagrams/skills/diagram/diagram-...",52 "type": "flowchart",53 "format": "mermaid",54 "artifacts": [],55 "runtime_events": [],56 "warnings": []57}58```5960On validation failure, `success` and `valid` are false and `errors` plus61`suggested_fix` may be present. When `render_to` is `"none"`,62`rendered_artifact_ref` is `null`. Invalid source is still saved with63`source_artifact_valid: false` so the operator can inspect or repair it.6465## Default Workflow66671. Pick the diagram type before writing syntax. If uncertain, set `type` to `auto`, but prefer an explicit type when the user request clearly names one.682. For Mermaid, read [references/mermaid-types.md](references/mermaid-types.md) when you need grammar examples or when the diagram type is not obvious.693. Draft complete source yourself when the user needs a specific diagram. Do not rely on the tool's generated starter unless the request is generic.704. Call `diagram_validate` before rendering when you wrote or revised source manually.715. If validation fails, use the returned `errors` and `suggested_fix`, revise once, then validate again. Make at most 2 fix-up attempts before surfacing the failure with the invalid source artifact. The runtime also caps automatic pre-render fix-up at 2 attempts.726. Call `diagram_create` or `diagram_update` with `render_to` set to `svg` by default. Use `png` or `pdf` only when requested and the adapter can render that target.737. Return the source artifact and rendered artifact paths to the user.7475## Type Selection7677Use these defaults:7879| User intent | Type |80| --- | --- |81| messages, API call flow, actors, request/response | `sequence` |82| process, decision tree, pipeline, system flow | `flowchart` |83| lifecycle, status machine, transitions | `state` |84| database schema, entities, relationships | `er` |85| classes, interfaces, inheritance, methods | `class` |86| timeline, schedule, milestones, roadmap | `gantt` |87| branches, commits, merges, release train | `git-graph` |88| brainstorm, taxonomy, concept map, outline | `mindmap` |89| shares, proportions, percentages | `pie` |9091## Mermaid Rules9293- Use the canonical header for the selected type.94- Keep labels short and ASCII-safe unless the user provided exact labels.95- Quote labels when Mermaid grammar requires it, especially pie chart slices.96- Avoid unsupported Markdown inside labels.97- Prefer `flowchart TD` or `flowchart LR`; do not mix both in one source.98- In `sequenceDiagram`, define participants when names are long or reused.99- In `gantt`, include `dateFormat` and stable task ids when using dependencies.100- In `erDiagram`, include cardinality on relationships.101102## Update Rules103104For `diagram_update`, preserve the existing `type` and `format` unless the user explicitly asks to convert. When the user gives natural-language update instructions:1051061. Read the existing source artifact when needed.1072. Apply the change to the source yourself.1083. Validate the full updated source.1094. Call `diagram_update` with the complete updated source, original format/type, and desired `render_to`.110111If the user only asks to annotate a diagram and exact placement does not matter, the tool can add a small update annotation when passed only `artifact_ref` plus `instructions`.112113## Adapter Notes114115- Mermaid and Graphviz use local renderers when available. If a renderer is not installed, SVG requests fall back to source-backed SVG artifacts so the operator still gets an embed-ready file.116- Mermaid validation checks the diagram header and, for flowchart, state, and class diagrams, bracket and quote balance. Full syntax checking happens only when `mmdc` renders the source, so re-read the diagram-type grammar before drafting when `mmdc` is not installed.117- PlantUML rendering uses `HYBRIDCLAW_PLANTUML_SERVER_URL` or `PLANTUML_SERVER_URL` when configured. Without a server, SVG requests fall back to source-backed SVG artifacts. Operators are responsible for pointing this setting only at a trusted PlantUML server with appropriate network egress controls.118- Excalidraw defaults to `render_to: "none"` because JSON is the editable deliverable. Use `render_to: "svg"` when a static preview is requested; the runtime renders the JSON elements directly to SVG.119- Local Mermaid and Graphviz renders use short-lived OS temp directories. Normal tool completion removes them; process-level termination such as SIGKILL may leave temporary source copies for the OS temp cleaner.120Diagram render usage is reported as a zero-cost budget hook; LLM tokens are only consumed when the model drafts or repairs source.121122## Runtime Hooks123124Rendered diagrams include a `diagram.rendered` event in `runtime_events`.125Validation failures include a `diagram.validation_failed` event with the126validation errors and source artifact path when one was persisted. Diagram127artifacts are stored under the skill-scoped path128`.generated-diagrams/skills/diagram/`.129130## Stakes131132Diagram rendering is F8 low stakes: the output is a file artifact the operator chooses to share. Do not treat generated diagrams as authoritative for security, legal, medical, or financial decisions without separate verification.