Skip to main content
On this page

AI Agents

AI agent workflow sequence diagram

This page is the fastest path for agent-driven setup and usage.

60-Second Agent Flow

Ask your coding agent:

Set up diagramkit in this repo. Install the package, read node_modules/diagramkit/llms.txt, add a render:diagrams script to package.json, create diagramkit.config.json5 only if the repo needs non-default behavior, run npx diagramkit --install-skill, warm up Chromium unless the repo is Graphviz-only, and render all diagrams to SVG.

Expected commands:

Shell
npm add diagramkitnpx diagramkit --install-skillnpx diagramkit warmupnpm run render:diagrams

Note

npx diagramkit warmup is only required for Mermaid, Excalidraw, and Draw.io. Graphviz-only repos can skip it.

Which Agent Doc to Use

diagramkit ships three agent-readable files:

File Best for Includes
llms-quick.txt Fast autopilot tasks Minimal commands, defaults, troubleshooting
llms.txt Day-to-day usage CLI patterns, config layering summary
llms-full.txt Deep implementation work Full CLI + API + types + architecture

You can also run:

Shell
diagramkit --agent-help

This prints llms-full.txt so agents can ingest a single stream.

For repo bootstrap, start with node_modules/diagramkit/llms.txt. It is the best single file for install, config, and package-script guidance.

Install Project Skills

Use the CLI to install project-level skills for both Claude and Cursor:

Shell
npx diagramkit --install-skill

This creates:

  • .claude/skills/diagramkit/SKILL.md
  • .cursor/skills/diagramkit/SKILL.md

The generated skill tells agents to read node_modules/diagramkit/llms.txt, suggests "render:diagrams": "diagramkit render ." for package.json, and skips existing files instead of overwriting them.

  1. Execute: “Render all diagram files to SVG.”
  2. Optimize: “Now render PNG for docs/email where needed.”
  3. Harden: “Use —dry-run and show what will re-render before changing files.”
  4. Automate: “Add a CI step that runs diagramkit render . and fails on errors.”

Manual Fallback Rules

If your assistant does not support project skills yet, paste the equivalent guidance into the repo’s memory or rules files.

CLAUDE.md

Markdown
## Diagram RenderingWhen changing .mermaid, .mmd, .excalidraw, .drawio, .dot, or .gv files, run:```bashnpx diagramkit render <file-or-dir>```Use defaults unless asked otherwise:- format: svg- theme: both- outputs in .diagramkit/ next to source files

.cursor/rules

Text
When editing diagram files (.mermaid, .mmd, .excalidraw, .drawio, .dot, .gv), run:npx diagramkit render <file-or-dir>Prefer --dry-run before large batch renders.

JSON Output for Automation

Use JSON for scripts/CI:

Shell
npx diagramkit render . --jsonnpx diagramkit render . --plan --jsonnpx diagramkit doctor --json

--json returns a versioned envelope (schemaVersion: 1) with nested result. failedDetails provides machine-readable diagnostics (file, code, message) for each failed render. --plan --json includes stale reasons before execution.

JSON schema: diagramkit/schemas/diagramkit-cli-render.v1.json (exported from the npm package).

Use --quiet --json together for clean JSON on stdout (suppresses log noise to stderr).

Exit Codes

Code Meaning
0 Success
1 Error (render failure, unknown command, etc.)

Error Codes

failedDetails entries include a code field:

Code Description
UNKNOWN_TYPE File extension not recognized
RENDER_FAILED Diagram rendering failed (syntax error, etc.)
MISSING_DEPENDENCY Required dependency not installed (e.g. sharp for raster)
CONFIG_INVALID Invalid configuration value
BROWSER_LAUNCH_FAILED Playwright Chromium could not start
BUNDLE_FAILED IIFE bundle generation failed

Deep Dives