Archify

WHAT IS IT?

Archify is a skill for coding agents (Claude Code, Codex CLI, Cursor, OpenCode) that turns a system description or a repository into an interactive diagram. The agent does not draw the SVG itself: it writes a typed JSON source, which Archify validates and then compiles deterministically into a self-contained HTML file. Five diagram types are covered: architecture, workflow, sequence, data flow and lifecycle. There is no WYSIWYG editor: you change a diagram by asking the agent ("add Redis", "move auth to the left"). Install it with npx skills add tt-a1i/archify -g.

WHY IS IT INTERESTING?

• Validation before delivery: schema, layout, arrow routing and label-to-route clearance are checked before a diagram replaces the last valid version. On failure, validate --json returns a rule code, the offending element, the measured evidence and the supported fixes, so the agent applies a targeted repair instead of retrying blindly.
• Interactions grounded in the source: node search, upstream and downstream reach, routes between two components, role comparison and guided stories. Everything relies on the relationships declared in the JSON, with no claim about runtime impact. Each view has a stable link, for example #route=web~db.
• Architecture review in PRs: the compare command diffs two validated JSON snapshots and renders a Before / Delta / After view listing added, removed, changed, moved and rerouted elements.
• Source evidence, on request: architecture nodes can link to the matching files and line ranges, verified through Git and pinned to one public commit. Regular diagrams carry no source references.
• One file, several exports: the output is a self-contained HTML file with light and dark themes, four visual presets and a presentation mode. The Export menu produces PNG, SVG, WebM and 1200×630 share cards, including one for a specific route traced in the diagram. A local preview mode watches the JSON file and only reloads the render once it passes validation.

USE CASES

• Map the runtime architecture of an unfamiliar repository by asking the agent for core components, the primary path and trust boundaries.
• Attach a Before / Delta / After view to a pull request that changes the architecture.
• Document an API call with a cache miss as a sequence diagram, or a Kafka pipeline with a DLQ as a data flow diagram.
• Walk through a system in a meeting with presentation mode and a chapter-by-chapter guided story.
• Illustrate a README or release note with a 1200×630 share card generated from the diagram.