Set up a coding agent for vizzy

The fastest way to get diagrams is to let a coding agent do the drawing — pointed at a reusable vizzy skill that teaches any agent how to author and maintain vizzy diagrams in your repo. There are two ways to add it.

Install the skill

Add the maintained vizzy skill to your project with one command:

npx skills add https://github.com/lloydhumphreys/skills --skill vizzy

This drops the vizzy skill into your agent’s skills folder (e.g. .claude/skills/vizzy/) and works with any tool that supports Agent Skills — Claude Code, Codex, Cursor, and others. Re-run the same command to update it later.

What the agent does

Rather than drawing the diagrams once, the idea is a reusable vizzy skill — e.g. .claude/skills/vizzy/SKILL.md — that captures the format so the work can be done on demand later and stays consistent over time. The skill should teach:

• Where diagrams live — a vizzy/ folder, one concern per file.
• Frontmatter — title, layout, and created / lastEdited dates.
• mermaid vs vizzy fences — when to draw with Mermaid and when to reach for vizzy.
• Annotations — desc to title a node or a whole section, note for an aside, hint for click-to-open detail; and where each directive fits.
• Diagram types, styling, and theming — everything in the Authoring section.
• Checking its work — running vizzy lint after authoring to catch broken hint paths and other issues the renderer silently ignores.

Run the agent inside Vizzy

You don’t have to leave the app to drive an agent. The document window’s side pane has two tabs — Source (the raw .vizzy.md) and Terminal — and the terminal runs a real shell in the open document’s folder, so an agent can edit the file while you watch the canvas live-reload beside it.

Pick which agent the terminal launches from the button beside the pane:

• claude — runs the claude CLI.
• codex — runs the codex CLI.
• Terminal — a plain login shell, for running vizzy render / vizzy lint or anything else by hand.

The split button opens the terminal with your last-used agent; the menu next to it switches agents (which starts a fresh shell). Your choice is remembered for next time. Whichever agent you use, the workflow is the same — it should create the vizzy skill and follow the principles below.

Do a good job

Whether it’s you or an agent authoring, the same rules apply:

• Explore the real code first — diagram what’s actually there, not a guess.
• Short, stable ids; readable labels. On edges, show what is exchanged (payloads).
• Prefer a sequence diagram for a request/response flow, an architecture fence for the static service map, a flowchart for branching logic, a gantt for a schedule, a mindmap for a brainstorm / branching ideas, a conceptmap for a domain model / “how X fits together”.
• Add a short prose paragraph above each diagram explaining its intent.
• When the architecture changes in code, update the matching vizzy/*.vizzy.md and bump its lastEdited date.
• Run vizzy lint on the file when done — it flags broken hint/link paths and other problems the renderer would otherwise swallow silently.