Archify Is a Diagram Skill That Deleted Its Own Auto-Layout Engine. That's the Interesting Part.

The trending npx skills add tt-a1i/archify turns plain English into a self-contained HTML architecture diagram. Its most telling decision was refusing to automate the one thing you would expect it to.

Somewhere in archify's roadmap there is a note about a feature the author built, tested, and then deleted. Archify is a skill that turns a plain-English description of your system into a polished architecture diagram, and the obvious way to build that is to parse a diagram language like Mermaid and auto-lay-out the boxes. The author wrote that path, ran an experiment, and cut it. The stated reason is the whole point of the tool: the layout judgment was doing better work than the parser, and that judgment came from the model, not the code.

Most write-ups about a trending diagram tool would tell you it makes pretty pictures. This one is more useful as a small lesson in where to trust a model and where to fence it in.

Why deleting a feature is the story

The industry's reflex when an agent produces unreliable output is to take the decision away from the model. Give it a rigid spec to fill, run a deterministic compiler, let the machine derive the layout so the model cannot get it wrong. That works for some problems. Archify is a working counterexample, and it earns the contrast because the author tried the deterministic path first and walked back from it.

Here is the position. For a whole class of "make the model produce a good artifact" problems, the win is not removing the model's judgment. It is fencing the parts that fail loudly and leaving the parts that fail usefully. Archify fences structure and validation. It leaves taste and layout to the model on purpose. When the auto-layout experiment showed that parsing Mermaid and applying archify's CSS did not look meaningfully better than plain Mermaid, the author kept the model's layout and threw the parser away.

What it actually is

Archify is a Claude Skill, also installable into other agents, that reads a description of a system or process and writes a single self-contained HTML file. No server, no framework, about 19 KB of embedded JavaScript, zero dependencies in the output. You open it in any browser. It draws five kinds of diagram: architecture, workflow, sequence, data flow, and lifecycle, each aimed at a specific technical job rather than being a generic flowchart tool.

The output is built for sharing, and this is where the engineering shows. Press T to toggle dark and light, press E for the export menu. You can copy a PNG straight to your clipboard, or download PNG, JPEG, WebP, or SVG. Every raster export renders natively at up to 4x the diagram's intrinsic resolution instead of upsampling a blurry bitmap, so it stays sharp on a retina screen or a slide. The SVG export is the clever one: it ships as a single dual-theme file carrying both color sets plus a @media (prefers-color-scheme) rule, so you drop one .svg into a GitHub README and it follows each reader's dark or light preference. No more shipping two PNGs wrapped in a <picture> tag.

Under that, archify is a fork and rewrite of Cocoon-AI/architecture-diagram-generator v1.0, which was dark-only with a plain HTML output. The 2.x line added the theme system, the export pipeline, keyboard navigation, and, in the most recent releases, typed renderers with schema validation backed by a golden-file test suite and CI. The current version is 2.6.

Where the determinism lives

This is the part worth stealing for your own skills. Archify does have deterministic machinery, but it sits in validation, not in layout. The typed renderers for workflow, sequence, data flow, and lifecycle diagrams validate the model's output against a schema, check the layout for problems like overlapping lanes, and verify the HTML and SVG. When something is wrong, the validator hands the model an error with a numeric threshold and a suggested fix, which is a far better way to steer an LLM than a vague "invalid input."

So the model decides where the boxes go and how the diagram reads. The code checks whether the result is structurally sound and tells the model precisely how to fix it when it is not. Judgment stays with the model because that is what the model is good at. Correctness gets enforced by the machine because that is what machines are good at. The Mermaid auto-parser died because it tried to move judgment into the code, and judgment was the thing the code was worst at.

Put this into practice

You can get a first diagram in under ten minutes.

1. Install the skill. The fastest path is npx skills add tt-a1i/archify -g. If you use Claude.ai, download archify.zip from the repo, then go to Settings, Capabilities, Skills, click Add, upload the zip, and toggle it on. In Claude Code, unzip it into ~/.claude/skills/ and run npm install inside the skill folder so the schema validator has its one dependency.
2. Get a description. Either write a short bullet list of your stack, or point the agent at your code: "Analyze this codebase and describe the architecture, including major components, how they connect, and any cloud services. Format it as a list for an architecture diagram."
3. Ask for the diagram. "Use your archify skill to make an architecture diagram from this description." The agent writes an HTML file. Open it.
4. Iterate in chat. "Add Redis." "Move auth to the left." "Use emerald for the API." Each request re-renders the file.
5. Export the SVG for docs. For a README, use the dual-theme SVG so one file serves both dark and light readers.

The lowest-friction win is step two into step three: describe a system you already understand, get a diagram, and check whether it matches your mental model. That check is not busywork, and the limitations section explains why.

Honest limitations

Start with the number, because the trending write-ups get it wrong. Archify's own GitHub page shows 661 stars and 41 forks as of this writing, while the trending boards that surfaced it quote figures near 5,700. That gap is the difference between momentum and adoption, and the smaller number is the honest one. This is a two-contributor project moving fast enough that features and roadmap items get added and dropped between point releases. Read the forks and the commit history before you read the star count on anything trending right now.

The look is not archify's own. The color palette, the grid background, and the JetBrains Mono typography come from Cocoon-AI's original. Archify's real contribution is the theme system, the export pipeline, and the validation layer, which is plenty, but credit the aesthetic where it is due.

"Any agent" is asymmetric. Full capability, meaning the typed renderers and schema validation, needs Claude Code or a sandbox that can run npm install for the validator. Upload it to Claude.ai Project Knowledge instead and you get architecture mode only, no code execution. Without the validator dependency, schema validation is skipped, though the layout checks still run.

The deepest limit is the same as the design win. The model's judgment is also the model's failure mode. It can mislabel a service or drop a component entirely, and because the output is clean and confident, a wrong diagram looks exactly as trustworthy as a right one. This is a communication artifact, not a source of truth, and there is no round-trip back to your code to catch the drift. Stable local edits through a JSON intermediate format are on the v3 roadmap, not shipped, so today "move auth to the left" re-renders the whole thing and can nudge unrelated pieces. Verify the diagram against reality before you paste it into a design doc.

Two smaller snags. Fonts in raster exports fall back to a system monospace because the image-rendering sandbox cannot fetch Google Fonts, so install JetBrains Mono locally for pixel-perfect output. And WebP export and clipboard copy depend on your browser's support, with older Safari missing pieces. It is also a skill you install, which carries the same read-it-first caution as any skill.

The question archify leaves open

Every skill that puts a model in the loop has to answer one question: what do you let the model decide, and what do you force it to prove? Archify's answer is unusually clear. Let it decide the layout, force it to prove the structure. The reason that answer is interesting is that the author reached it by building the opposite first and measuring that it was worse.

So the next time you are tempted to hand a model a rigid spec to keep it from going wrong, it is worth asking whether the rigid spec is throwing away the exact judgment you wanted. Draw one of your own systems with archify, then check what it got wrong. What it drops will tell you more about where to trust a model than any benchmark will.

Sources: tt-a1i/archify on GitHub, archify README, Cocoon-AI/architecture-diagram-generator, Archify project page, Trendshift repo page.