agentleFS
Sign inStart free
HybridAIOneHybridAIOne/hybridclaw/skills/diagram/SKILL.md

diagram

Skill159 starsChanged 6 months agoMITView on GitHub

Create, validate, update, and render diagram-as-code artifacts with Mermaid-first schema awareness plus PlantUML, Graphviz DOT, and Excalidraw JSON adapters.

We split this skill into the rules it gives an agent

13 rules. 0 are common, 7 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 36 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when the user wants a rendered static diagram, a validated diagram source artifact, or a revision to an existing diagram …

    line 25
  2. Distinctive:

    Default to Mermaid unless the user asks for another format or the shape is a better fit for another adapter:

    line 27
  3. Distinctive:

    Use the runtime tools directly:

    line 36
  4. Very specific:

    Call diagram_validate before rendering when you wrote or revised source manually.

    line 69
  5. Very specific:

    If validation fails, use the returned errors and suggested_fix, revise once, then validate again.

    line 70
  6. Very specific:

    Call diagram_create or diagram_update with render_to set to svg by default.

    line 71
  7. Distinctive:

    Use the canonical header for the selected type.

    line 92
  8. Distinctive:

    Keep labels short and ASCII-safe unless the user provided exact labels.

    line 93
  9. Distinctive:

    Avoid unsupported Markdown inside labels.

    line 95
  10. Very specific:

    Prefer flowchart TD or flowchart LR.

    line 96
  11. Distinctive:

    Read the existing source artifact when needed.

    line 105
  12. Very specific:

    Call diagram_update with the complete updated source, original format/type, and desired render_to.

    line 108
  13. Very specific:

    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 …

    line 110

“Common” is measured: kept by at least 6 in 10 of the 36 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Type Selection

Use these defaults:

User intentType
messages, API call flow, actors, request/responsesequence
process, decision tree, pipeline, system flowflowchart
lifecycle, status machine, transitionsstate
database schema, entities, relationshipser
classes, interfaces, inheritance, methodsclass
timeline, schedule, milestones, roadmapgantt
branches, commits, merges, release traingit-graph
brainstorm, taxonomy, concept map, outlinemindmap
shares, proportions, percentagespie

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:

  1. Read the existing source artifact when needed.
  2. Apply the change to the source yourself.
  3. Validate the full updated source.
  4. 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free