kroki-diagrams

A distributable agent skill for turning architecture ideas, flows, schemas, and dependency maps into clean, versionable diagrams.

What Is Kroki?

Kroki is a diagram rendering service. Instead of drawing boxes manually in a GUI, you write diagrams as text using engines like PlantUML, Mermaid, Graphviz, and ERD syntax, then Kroki renders them to SVG, PNG, PDF, or text output.

That gives you a few big advantages:

• diagrams live in your repo as source files
• changes are diffable in git
• diagrams can be regenerated automatically
• you can use the best diagram engine for each use case instead of forcing everything into one tool

This skill packages that workflow for coding agents so they do not just dump raw diagram syntax or pick a random engine. It helps them choose the right diagram type, style it sanely, render it, and optionally make it interactive.

Quick Demo

https://github.com/user-attachments/assets/e22072b9-ae73-4405-b6ad-659f2cefc868

What This Skill Actually Does

From start to finish, the skill:

1. reads your code, docs, or prompt
2. decides whether you need a sequence diagram, C4 diagram, graph, ERD, Mermaid flow, or even a plain text tree
3. chooses the most appropriate engine
4. applies layout and styling rules to avoid spaghetti diagrams
5. writes the diagram source file into a sensible repo-local folder
6. renders the source through Kroki
7. optionally builds an interactive.html viewer around the SVG
8. automatically updates an index.html page for the diagram collection

So it is not just “render this diagram.” It is a full diagram production workflow.

Feature Set

• Use-case-first diagram selection instead of engine-first guessing
• Support for plantuml, c4plantuml, graphviz, mermaid, and erd
• Readability rules for layout direction, grouping, spacing, and diagram splitting
• Engine-specific style templates so diagrams start from a sane visual baseline
• Interactive HTML wrappers for supported SVG outputs
• Auto-generated collection index.html pages with list and card views
• Repo-friendly output placement like docs/diagrams/<artifact-name>/
• Shareable Kroki URLs for generated diagram sources
• Cross-agent packaging for Claude Code, Codex, and Pi

Interactive Viewer Features

When you render an interactive wrapper, the generated HTML viewer can provide:

• a refined dark interface with a dark/light theme toggle
• click-to-select node highlighting in a calm, monochrome accent
• connected-node and edge emphasis
• directional edge flow when the SVG exposes source and target metadata
• neutral current-style edge animation when direction is not reliable
• dimming of unrelated nodes without making them disappear
• a live, searchable node list built from the diagram
• a minimap showing the current viewport region
• pan and zoom (drag, scroll, buttons, keyboard) with fit-to-view and 100% controls
• a copy-Kroki-URL action wired to the shareable link
• a generated diagram gallery for browsing many diagrams, with an engine filter rail, search, grid/list views, and a matching theme toggle

Support is strongest for:

• PlantUML
• C4-PlantUML
• Graphviz

Best-effort support exists for:

• Mermaid
• ERD

Supported Use Cases

This skill is built for tasks like:

• architecture diagrams
• request and sequence flows
• system context and container diagrams
• dependency graphs
• orchestration DAGs
• schema and data relationship diagrams
• planning structures and work breakdowns
• repo layout visualizations

Examples:

• “diagram our authentication flow”
• “show the runtime topology of this service”
• “generate a dependency graph for these modules”
• “make an ERD from this schema”
• “visualize this product workflow”

How It Works In Practice

The packaged skill payload lives at plugins/kroki-diagrams/.

Important pieces:

• SKILL.md The main workflow and decision rules.
• render_kroki_diagram.py Renders diagram source through Kroki, prints a shareable URL, writes metadata, and refreshes index.html.
• build_interactive_kroki_html.py Wraps rendered SVG output in an interactive HTML viewer (dark/light theme, node list, minimap, copy-URL).
• build_diagram_index.py Builds the collection gallery page for a directory of diagram artifacts (filter rail, search, grid/list, theme toggle).
• references/ Holds the selection matrix, style templates, layout rules, and support notes the agent reads on demand.

Typical Output Structure

The skill usually writes one folder per diagram artifact:

docs/diagrams/my-diagram/
  source.puml
  rendered.svg
  interactive.html
  .diagram-meta.json

And at the parent level it can maintain:

docs/diagrams/index.html

That index is useful once a repo accumulates a larger diagram library.

Example Render Flow

Normal SVG render:

python3 plugins/kroki-diagrams/scripts/render_kroki_diagram.py \
  --engine plantuml \
  --input /path/to/source.puml \
  --output /path/to/rendered.svg

SVG render plus interactive viewer:

python3 plugins/kroki-diagrams/scripts/render_kroki_diagram.py \
  --engine plantuml \
  --input /path/to/source.puml \
  --output /path/to/rendered.svg \
  --interactive-output /path/to/interactive.html

What you get back:

• rendered SVG output
• optional interactive HTML
• a shareable Kroki URL
• per-artifact metadata
• an updated collection index.html by default

Bundled Examples

This repo includes a ready-to-open sample set under examples/interactive-playground/.

It includes medium-complex examples across the main supported engines:

This is the beginning of the README. Read the rest at the original. Read the full README ↗