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.

Setting up a fresh machine?

Tell your agent to fetch usevizzy.com/prompt.md and follow it. That one prompt installs the app, the vizzy CLI, and the skill (globally, for every repo) — the rest of this page covers the pieces individually.

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 creates the vizzy skill and follows it when authoring.