Why use it: this is the main usage path of Archify. You describe the system in natural language, the agent picks the diagram type itself, writes the JSON IR according to the schema itself, runs validate/deliver itself, then returns the HTML path.
What you get: a self-contained HTML file, already validated, along with a receipt (SHA-256 + byte count of both the spec and the artifact) reported back by the agent.
Everything in this file is typed into the agent chat frame, not a terminal. Shell commands are in 03-cli-authoring-loop.md. Don't paste across the two files.
Prerequisites
The skill is installed per 01-install-and-verify.md and the agent has permission to run shell (the agent needs to call node bin/archify.mjs below).
Step 1 — Start from a description, no repo needed
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.
When you need a diagram grounded in real code, open the repo and ask:
Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.
Step 2 — State the diagram type when you already know what you want
The router table is taken verbatim from SKILL.md the "Type router" section:
| Type | Use for | Mention in the prompt |
|---|---|---|
architecture |
Components, services, cloud/security boundaries, infrastructure | Scope, core components, main path |
workflow |
Processes, approval gates, tool calls, runbooks, CI/CD | Participants, order, branches, exceptions |
sequence |
API call chains, request lifecycle, async traces, return values | Caller, callee, return, timing |
dataflow |
Pipelines, ETL/ELT, lineage, data governance, consumers | Sources, transformations, warehouse, boundaries |
lifecycle |
State transitions, retries, waits, terminal states | States, events, retry/cancel paths |
If you're not sure what to pick, just ask, and the agent will run guide for you:
Which Archify diagram type fits: "Show CI/CD checks, approval, deploy, and rollback"?
Step 3 — Refine in small rounds
Archify keeps the typed JSON source, so narrow requests are cheap and stable:
add Redis
move auth to the left
highlight the rollback path
put the retry budget in a card instead of a new edge
Principles in SKILL.md that the agent must follow, which you should know so you don't ask for the opposite:
- One clear main path, side branches split off from the nearest node on the main path. At most ~12 main nodes.
- Supporting details go into
cards, not extra edges. - The agent may only add geometric controls (
via,channelX,channelY,labelAt) after a specific diagnosis demands it, and each revision round changes exactly one thing. - Relationship labels are semantic data. Removing labels is not the way to fix geometric collisions — the agent must move labels, change routes, widen spacing first, and only then shorten the text while preserving meaning.
Step 4 — Paste Mermaid into
Archify does not parse Mermaid mechanically; the agent reads the Mermaid to extract the topology and then composes a new Archify JSON:
Convert this Mermaid to an Archify diagram:
flowchart LR
A[Client] --> B[Gateway]
B --> C[(Postgres)]
Mapping, per SKILL.md section "Mermaid input":
flowchart/graph→workflow(orarchitectureif it is a component map)sequenceDiagram→sequencestateDiagram→lifecycle
Step 5 — Optional requests (only state them when you truly need them)
By default Archify chooses the static version, preset classic, no subtitles, legend auto. Only specify these when you want something different:
make it showcase quality
use the signal-flow visual preset
enable trace animation for the demo
set the viewer UI language to zh-CN
add up to five guided story chapters
meta.locale only accepts en or zh-CN, and only changes the viewer UI (page title, Legend, error messages, a11y, the langattribute) — it does not translate the content you write. For all other languages, the agent must drop meta.locale and state clearly that the viewer UI falls back to English.
Step 6 — Read the agent's return section, and know when it is overclaiming
Per SKILL.md section "Output", the agent must return: the checked HTML path, the diagram type, the validation summary, the spec/artifact receipt, the browser evidence status, and the visual review status honestly.
These three claims are separate; do not let them be merged:
| Claim | Proven by | Does NOT prove |
|---|---|---|
| Artifact passes deterministic checks | deliver (9 artifact checks, 0 errors 0 warnings in the showcase profile) |
Whether it looks good |
| Real behavior in the browser | visual-check (see 05) |
Aesthetics |
| Visual review | A real person or a reviewer can read the image | — |
Signs the agent is overclaiming — stop it immediately:
- A receipt with only 4 artifact checks is called a "showcase". A showcase must have all 9 checks, 0 errors, 0 warnings.
- An exit command other than 0 but still described as success —
SKILL.mdforbids this in writing. - "Checked by eye" when no one has opened the HTML.
Step 7 — Explore the artifact
The generated HTML already has keyboard shortcuts built in; nothing extra to install:
| Action | Key |
|---|---|
| Open Diagram Guide | ? |
| Find and focus a node | / |
| Trace a directed route | R |
| Compare one or two roles | L |
| Overview radar | M |
| Run story / change chapter | P / [ ] |
| Presentation mode | F |
| Change style / theme / open Export | S / T / E |
| Zoom / reset | + / - / 0 |
Stable deep link: #focus=<id>, #focus=<id>&reach=upstream|downstream, #relation=<id>, #route=<source>~<target>, #lens=<kind>~<kind>, #view=<view-id>.