2,088 GitHub stars and 1,300 installs on skills.sh in its first week. stack-diagram went public on November 1, 2026 with a simple pitch: describe your stack in one sentence and your agent hands back an architecture diagram with each technology's official logo. It works with Claude Code, Codex, Cursor and any other agent that supports Agent Skills, and it is MIT-licensed.
What it does when you ask for a diagram
The skill kicks in whenever you ask for an architecture, infrastructure or service-topology diagram, even if you never mention an output format. From there, its SKILL.md lays out seven steps:
- Settle the content: one node per technology (a name plus a short role such as
http server), groups for whatever shares a runtime, vendor or repo, and three kinds of edge: the main request flow, internal connections, and dashed deploy or CI relationships. - Fetch the icons with
fetch_icons.py: svgl first, then devicon and gilbarbara/logos. AWS, Google Cloud and Azure come from each vendor's official icon package, and a missing service fails outright instead of falling back to a third-party copy. Logos are never recolored. - Plan the coordinates using a geometry reference whose main rule is that no arrow may run through a node's label.
- Build a self-contained HTML file with
build.py, logos and fonts inlined. - Render a PNG and inspect it with Playwright before delivering: arrows over labels, white icons on white tiles, nodes spilling out of their group.
- Deliver HTML (the default), light and dark PNGs, a dependency-free React component or an artifact.
- Offer to post it to a public gallery, once per conversation.
The part I like most is the vendor-specific detail. On AWS it draws public and private subnets inside the VPC when it can infer them; on Google Cloud it puts the region inside the VPC rather than the other way round, because a VPC is global; on Azure the VNet sits inside its region and App Service stays outside unless it runs in an App Service Environment. Those are exactly the fixes anyone who knows these clouds would make in a diagram review.
Installing and using it
npx skills add caru-ini/stack-diagramIn the Claude apps you upload stack-diagram.zip from the latest release as a skill. After that you just describe the system; the README's example is:
Diagram our stack: Next.js and a Hono API on Vercel. Postgres on Neon, auth with Clerk, payments with Stripe. GitHub Actions deploys.
The icon, build and sharing scripts use nothing beyond the Python 3.9+ standard library. PNG output needs Playwright with Chromium, and this is the command the skill itself suggests:
pip install playwright && python3 -m playwright install --with-deps chromium--with-deps installs OS packages, so on a corporate laptop or a shared runner you are better off dropping that flag and sorting out Chromium's libraries yourself. Without PNG output the skill still works, but it skips the step where it checks its own work.
Risks and limits
- Network: it needs outbound access to svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, the AWS, Google and Microsoft icon domains, and the site or repo of any brand those catalogs lack. Behind an egress allowlist, every one of them has to be opened.
- The public gallery:
share.pyuploads both PNGs, a title, the list of technologies and a display name tostacks.caru.moe. The skill must show all of it first, flag hostnames, IPs or internal service names, and get two explicit confirmations. Even so, an internal architecture diagram is sensitive, and inside a company the safe answer is no. The delete key is stored in~/.config/stack-diagram/gallery.json, and theSTACK_DIAGRAM_GALLERYenvironment variable changes where posts go. - Trademarks: logos are not shipped in the repo but downloaded at build time, and the README notes that Microsoft only allows its icons in architecture diagrams, training material and documentation.
- Maturity: the repo is a week old and its last push was on November 3, 2026. With a project this young, read the
SKILL.mdand scripts of the version you install: what is described here may change in the next one.
stack-diagram vs. diagrams
The go-to tool for drawing cloud architectures without design software is diagrams (mingrammer/diagrams), the Python "diagram as code" library.
| stack-diagram | diagrams | |
|---|---|---|
| Approach | Describe the system in plain language, the agent lays it out | Write the diagram as Python code |
| Engine | HTML with fixed coordinates, PNG via Chromium | Graphviz |
| Providers | AWS, Google Cloud and Azure with official icons, plus any brand's logo | AWS, Azure, GCP, Kubernetes, Alibaba Cloud, Oracle Cloud, on-premises and SaaS |
| License | MIT | MIT |
| Maturity | One week old, 2,088 stars | 42,796 stars, last push on November 2, 2026 |
diagrams wins when the diagram has to live in the repo: the Python code gets reviewed in a PR and the output is reproducible. stack-diagram wins on polish and speed for a slide, a README or a design doc, and on something Graphviz handles poorly: control over where every arrow goes. For documentation that evolves with the system I would stick with diagrams; to explain a stack to another team in five minutes, I would give stack-diagram a try.