diagram

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

1. 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.
2. For Mermaid, read references/mermaid-types.md when you need grammar examples or when the diagram type is not obvious.
3. 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.
4. Call diagram_validate before rendering when you wrote or revised source manually.
5. 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.
6. 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.
7. Return the source artifact and rendered artifact paths to the user.