Set up a coding agent for vizzy

The fastest way to get diagrams is to let a coding agent draw them. A reusable vizzy skill teaches the agent how to write and maintain vizzy diagrams in your repo. There are two ways to add it.

Setting up a new 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 each piece on its own.

Install the skill

Add the vizzy skill to your project with one command:

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

This puts the vizzy skill in your agent’s skills folder, for example .claude/skills/vizzy/. It works with any tool that supports Agent Skills, including Claude Code, Codex, and Cursor. Run the same command again to update it.

What the agent does

The skill is a file such as .claude/skills/vizzy/SKILL.md that describes the format, so the agent can draw diagrams on demand and keep them consistent over time. The skill covers:

• Where diagrams live: a vizzy/ folder, one topic per file.
• Frontmatter: title, layout, and created / lastEdited dates.
• mermaid vs vizzy fences: when to use Mermaid and when to use vizzy.
• Annotations: desc to describe a node or 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 writing to catch broken hint paths and other problems the renderer ignores.

Run the agent inside Vizzy

You can run an agent without leaving the app. The document window’s side pane has two tabs: Source (the raw .vizzy.md) and Terminal. The terminal runs a real shell in the open document’s folder, so an agent can edit the file while the canvas reloads next to it.

Choose which agent the terminal launches from the button next to 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 the agent you used last. The menu next to it switches agents and starts a fresh shell. Your choice is remembered. Whichever agent you use, the workflow is the same: it creates the vizzy skill and follows it when writing diagrams.