The Agent Skill That Outputs a Production-Ready Diagram

Editor

Archify turns plain-English system descriptions into self-contained, themeable HTML diagrams with native 4× raster export, packaged as a skill for Claude and Codex CLI.

tt-a1i/archify

★57.5k stars Velocity · 7d +1929 ★/day ↘cooling

star history

View on GitHub ↗

The current wave of AI agent frameworks is changing what it means to generate something useful. Text is no longer the default output; agents are expected to produce spreadsheets, slides, interactive dashboards, and now—architecture diagrams that you can paste directly into a GitHub issue or a Notion page. Archify, a rewrite of the popular Cocoon-AI diagram generator, has been repackaged as an agent skill for Claude, Codex CLI, and opencode. Its pitch is simple: describe your system in English, receive a single HTML file containing a polished, themeable diagram, then iterate by chat. There is no DSL to learn, no SaaS login, and no build pipeline. The file simply opens in a browser.

The Hype Moment: When Agents Started Shipping Artifacts

Archify is riding a broader shift in how developers expect to interact with AI. Commercial tools like Eraser.io now offer AI-generated architecture diagrams as a managed service, while the long-standing “diagrams as code” movement—encompassing PlantUML, Mermaid, D2, and Structurizr—continues to dominate formal documentation pipelines. Archify sits at the intersection of these two trends. It uses the AI agent as the authoring interface, but produces a self-contained, portable artifact rather than a subscription-dependent web link.

The project’s visibility owes something to its lineage. It is a fork and rewrite of Cocoon-AI/architecture-diagram-generator, a dark-themed diagram skill that accumulated over seven thousand stars before Archify’s author refactored the template around a themeable CSS-variable system and added a client-side export pipeline. That rewrite, released as Archify 2.0, transformed a single-theme novelty into a multi-format document generator. The attention spike since then reflects a growing appetite for agent-native tools: capabilities that are not merely used by AI, but distributed as skills inside Claude, Codex, and other agent runtimes.

The Product Is the HTML File

What makes Archify genuinely different from both traditional diagramming SaaS and conventional diagrams-as-code tools is its unit of output. It does not generate a share link, a proprietary canvas file, or a text file full of Mermaid syntax. It emits a single, self-contained HTML document—inline SVG, embedded JavaScript, and a Google Fonts link—totaling roughly nineteen kilobytes of overhead. The generated file has zero dependencies, requires no server, and can be emailed, checked into git, or dropped onto a static host.

The skill supports five diagram types: architecture, workflow, sequence, data flow, and lifecycle. Each has a typed renderer and, as of version 2.5, schema validation backed by ajv. The interaction model is conversational. A user pastes a bullet list of components, asks the agent to draw an architecture diagram, and receives the HTML file. Follow-up instructions—“add Redis,” “move auth to the left,” “use emerald for the API”—mutate the diagram without the user touching coordinates or CSS. This is a subtle but important inversion of the usual diagrams-as-code workflow, where the human maintains source code and the tool renders it. In Archify, the conversation itself is the source, and the HTML is the compiled artifact.

A Surprisingly Serious Export Pipeline

For a project distributed as a chat skill, Archify’s export pipeline is unusually rigorous. The template uses CSS custom properties on :root and semantic classes such as c-frontend or t-muted. Toggling a data-theme attribute on the <html> element re-themes the entire diagram—gradients, grid, arrows, and masks—switching between dark and light modes that persist across sessions via localStorage.

The raster export path is the standout technical detail. Rather than taking a screenshot or upsampling a low-resolution bitmap, Archify clones the SVG, resolves the current theme variables into inline styles, sets the clone’s width and height to four times the viewBox, and asks the browser to rasterize the vectors natively at that resolution. The result is drawn to a canvas at natural size, producing genuinely crisp PNG, JPEG, or WebP output for retina displays and print. If the 4× target would exceed browser canvas limits, the pipeline automatically steps down to 3× or 2× so the export still succeeds. There is no scale dial; maximum safe sharpness is chosen automatically.

The SVG export is equally thoughtful. The file ships with both dark and light CSS variable sets plus an @media (prefers-color-scheme) rule, meaning a single .svg dropped into a GitHub README or a blog post will follow the reader’s system preference. This eliminates the usual workaround of maintaining two PNGs wrapped in a <picture> element. Copy-to-clipboard, keyboard navigation, a print stylesheet, ARIA semantics, and CJK font fallbacks round out a feature set that feels closer to a design tool than a chat prompt template.

Honest Limits in a Crowded Field

The README contains an unusually candid admission: “Archify’s aesthetic core is Claude’s layout judgment, not the CSS.” This is a critical distinction. Unlike Graphviz, D2, or Structurizr, which use deterministic layout engines, Archify delegates spatial reasoning to the large language model. If Claude misplaces a component or draws an ambiguous arrow, the diagram is wrong in a way that no amount of CSS tuning will fix. The project is not, and does not claim to be, a general-purpose auto-layout engine.

The authors also document what they tried and abandoned. An automatic Mermaid parser route was cut after experiments showed that auto-layout plus Archify styling did not look meaningfully better than native Mermaid. Mermaid code can still be fed into the skill, but it is handled through the SKILL.md prompts, not a parser. Similarly, planned features such as user-selectable export scales, color-blind palettes, and share links were dropped, with the rationale recorded in the roadmap. Schema validation for typed renderers requires a one-time npm install for ajv; without it, the renderers skip validation but still run. And when used via Claude.ai Project Knowledge—rather than as an installed skill—Archify is limited to architecture mode only, with no code execution.

Toward a Diffable Intermediate Format

The most architecturally interesting item on the roadmap is version 3.0’s planned “JSON IR stabilization.” The goal is a minimal diagram.json intermediate format that would let Claude make local coordinate edits without drifting unrelated components, while producing git diff-friendly output and supporting theme or palette swaps without re-rendering the entire diagram from scratch.

If realized, this would move Archify from a prompt-to-picture novelty toward a genuine diagrams-as-code system—one where the code happens to be generated by conversation. It would address the biggest long-term risk of any LLM-dependent tool: non-determinism. A stable JSON IR would allow teams to version their diagrams, review changes in pull requests, and rebaseline layouts without losing the conversational authoring experience that makes the skill appealing in the first place.

Archify is best understood as a signal that the unit of AI work is shifting from the paragraph to the artifact. Whether or not it evolves into a lasting format, it raises the bar for what agent-generated output should look like: self-contained, portable, and polished enough to ship.