Architecture Diagram Generator: a Claude skill that turns a text description into a standalone HTML diagram

What this skill actually removes from the diagram workflow

Most architecture diagrams fail at the layout step, not the thinking step. You know the components; positioning twelve boxes and routing arrows between them without crossings is the part that eats an afternoon. This project targets exactly that gap. You describe the system in plain English, and Claude generates a dark-themed diagram as a single HTML file you open in a browser.

The intended user is an engineer or technical writer who already has Claude open and does not want to learn a diagramming tool. The README frames the pitch directly: no design skills needed, iterate by asking Claude to add components or change layouts, and share by sending one file. That last point matters more than it sounds. A single HTML file with embedded CSS and inline SVG survives email, Slack and a docs repository without a rendering pipeline.

The colour scheme is not decorative. The README defines a fixed mapping: cyan for frontend and client apps, emerald for backend and APIs, violet for databases and AI/ML, amber for cloud services, rose for auth and security, slate for external systems. Because the mapping is fixed, a diagram generated today and one generated next month will read the same way, which is the property that makes a diagram useful in a design review.

How Claude builds the diagram: template, skill file and inline SVG

The repository is small and the layout tells you how it works. Two files do the work: architecture-diagram/SKILL.md holds the instructions Claude reads, and architecture-diagram/resources/template.html is the base it fills in. The README's manual setup section shows exactly that tree, with SKILL.md at the root of the skill folder and the template one level down under resources/.

So the data flow is: your text description goes into the conversation, the skill instructions shape how Claude interprets it (which component is frontend, which is a database, where the arrows go), and the template supplies the page shell, the slate-950 background, the grid pattern, the typography and the layering rules. Claude then writes the component boxes and connector paths into that shell and returns a finished HTML document. The README notes that arrows render behind component boxes, which is a layering decision baked into the template rather than something you adjust per diagram.

There is no server, no rendering service and no build step. Everything the browser needs is inside the file. That is why the export toolbar works from a local file opened directly from disk.

Installing the skill and generating a first diagram

The README gives one prerequisite before anything else: Code Execution must be enabled. On Free, Pro and Max that is under Settings, Capabilities. On Team and Enterprise an admin enables it under Organization settings, Skills. Without it, the upload will not be available.

Once that is on, download architecture-diagram.zip from the repository and upload it through the Claude.ai interface. The README describes the path as Customize, then Skills, then the + button, then + Create skill, then Upload a skill. Toggle the skill on after uploading.

If you prefer the command line, the README documents extracting the zip into a skills directory instead:

# Global skills
unzip architecture-diagram.zip -d ~/.claude/skills/

# Or project-local
unzip architecture-diagram.zip -d ./.claude/skills/

Either path leaves you with the same two files in place. The README also offers a third option for Claude.ai Projects: upload the zip to Project Knowledge instead of installing it as a skill.

With the skill active, the first diagram is a single message. The README's own example is:

Use your architecture diagram skill to create an architecture diagram from this description:

- React frontend talking to a Node.js API
- PostgreSQL database
- Redis for caching
- Hosted on AWS with CloudFront CDN

What you should get back is one HTML file. Open it in a browser and the header carries the export toolbar: Copy puts a high-resolution PNG on your clipboard, PNG downloads one, PDF downloads a version that keeps the dark theme. Iteration happens in the same chat. Ask Claude to move a component or add a queue, and the file is regenerated.

Where the skill stops being the right tool

The output is a rendered artefact, not a source file. There is no Diagram-as-Code document you can diff in a pull request, no stable component identifiers, and no way to regenerate the same diagram deterministically. If your team reviews infrastructure changes through version control, this produces a picture that sits beside the repository rather than inside it.

The dependency on Code Execution is the harder constraint. The README states the skill is available on Free, Pro, Max, Team and Enterprise plans, but only with that setting enabled, and on Team and Enterprise it is an administrator decision. Organisations that restrict custom skills cannot use this at all, regardless of plan.

There is also a ceiling on complexity. The mechanism is a language model writing SVG into a fixed template. The README's examples cover a web application, an AWS serverless stack and a microservices system with Kafka and Kubernetes. Nothing in the documentation describes how the output behaves at fifty or a hundred nodes, and the README does not document rollback to a previous diagram version, so keeping earlier HTML files is on you. For a dense network topology or a diagram that must obey a corporate template, a tool with explicit layout constraints will be less work.

How it differs from diagram-as-code tools and hosted canvases

The obvious alternative for engineers is a diagram-as-code tool such as Mermaid or Graphviz, usually rendered through a Markdown viewer or a docs pipeline. The difference in approach is fundamental. Those tools take a declarative graph description and compute the layout themselves, which means the source is text you can review, the output is reproducible, and the diagram lives in the same repository as the code it describes. This project inverts that: a model interprets a prose description and writes the drawing directly. You gain tolerance for vague input and lose reproducibility.

The other alternative is a hosted canvas like diagrams.net or Lucidchart, where you place boxes by hand. That gives you pixel control and a stable editable document, at the cost of a manual layout pass every time the architecture changes. The skill's advantage is speed of iteration inside a conversation; the canvas tool's advantage is that the file is the source of truth.

A practical middle ground the README itself suggests: use an AI coding tool to analyse your codebase and produce the component list first, then feed that list to the skill. That keeps the discovery step grounded in the actual code even though the drawing step is generative.

Licence, maintenance and what an upgrade costs you

The project is MIT licensed, which is permissive and places few obligations on how you use or redistribute the generated files. The repository includes a LICENSE file at the top level. Nothing here constitutes legal advice; if you are embedding the output in a commercial product, read the licence text yourself.

On maintenance, the last push to the repository was on 2026-05-13. The two releases are 1.0 from 2025-12-22 and 1.1 from 2026-05-09, and 1.1 is the one that added the built-in export toolbar. The README does not describe a migration path between versions, which is unsurprising for a skill made of a markdown file and an HTML template. Upgrading means replacing the zip or the extracted folder. The practical cost is that any diagram you generated under 1.0 will not gain the export toolbar unless you regenerate it or edit the HTML yourself, because the toolbar lives in the template that was used at generation time. If you have a folder of older diagrams, decide up front whether they are worth regenerating.

Editorial conclusion

Adopt it if you already use Claude.ai on a plan where Code Execution can be turned on, and you want a diagram you can hand over as one HTML file rather than a shared canvas account. Skip it if you need a diagram source you can diff, review and regenerate outside a chat window, or if your organisation blocks custom skills. Before uploading the zip, confirm two things: that Code Execution is enabled under Settings, Capabilities (or by an admin under Organization settings, Skills on Team and Enterprise), and that the exported PNG and PDF from the header toolbar meet the resolution your slides need. The repository's own examples under examples/ are the fastest way to judge the visual style before you commit.

Frequently asked questions

Official sources

1. Cocoon-AI/architecture-diagram-generator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases