stack-diagram: an unofficial agent skill that turns one sentence into an architecture diagram with official logo files
stack-diagram (caru-ini/stack-diagram) is a free, MIT-licensed community skill: describe your stack in a sentence and Claude Code, Codex or Cursor draws an architecture diagram as one offline HTML file, using logos fetched from official sources. The brands do not endorse it.
stack-diagram (GitHub: caru-ini/stack-diagram) is a community agent skill: describe your stack in a sentence, and your agent returns an architecture diagram as one HTML file, with PNG and React versions on request. The repository was created on November 1, 2026 by caru-ini and had 2,512 stars and 134 forks on November 16.
Quick facts
- What it is: one skill (SKILL.md, Python scripts including fetch_icons.py, build.py, render_png.py and share.py, an HTML template, fonts and reference notes) plus a gallery site in site/.
- Works with: Claude Code, Codex, Cursor and other skill-capable agents; the Claude apps take the release zip.
- Requirements: Python 3.9+, network access to the icon sources, and Playwright with Chromium for PNGs. The skill lists no API key; your agent's own account or plan is separate.
- Output: a self-contained HTML file by default, light and dark PNGs, a dependency-free React (TSX) component, or an artifact where the agent has an artifact tool.
- Licence: MIT for code and docs; the bundled Geist and JetBrains Mono fonts are SIL OFL 1.1. Logos are not bundled.
- Activity (November 16, 2026): 30 of 33 commits on main by caru-ini; six releases, v0.1.0 (November 1) to v0.6.0 (November 13). GitHub counts 452 zip downloads and skills.sh lists 1.9K installs, each by its own method.
How to install
The README gives one command for agents that use the skills CLI:
npx skills add caru-ini/stack-diagramFor the Claude apps, download stack-diagram.zip from the latest GitHub release and upload it as a skill; the repository's release workflow zips the skill folder and attaches it to a release whenever a v* tag is pushed. The latest release, v0.6.0, added Kubernetes icons. PNG output needs Playwright: pip install playwright, then python3 -m playwright install --with-deps chromium.
Your first diagram
Ask in plain words, in any language, for example the README's own prompt: "Diagram our stack: Next.js and a Hono API on Vercel. Postgres on Neon, auth with Clerk, payments with Stripe. GitHub Actions deploys." The skill then decides nodes, groups and edges, fetches icons, plans coordinates from a geometry reference, builds the HTML with build.py, renders and inspects a PNG, delivers, and optionally offers to share. Given a flat list of tools, the agent infers groups and flows and asks only when a tool is truly ambiguous.
Solid accent lines mark the main request path, neutral lines internal calls, dashed lines CI and deploys. The HTML has a dark variant, and render_png.py emits light and dark PNGs by default. The skill advises one level of group nesting at most.
What stands out
- A strict logo chain. fetch_icons.py tries svgl (exact title match only), then devicon, then gilbarbara/logos. simple-icons is excluded: the skill calls its glyphs monochrome redraws. When every source misses, the agent must find the official file in the project's repo or site and pass it as name=URL. Logos are never recoloured; a white logo goes on a dark tile. Only unbranded nodes, such as a cron job or a user, get Lucide line icons or generic glyphs.
- Cloud vendors get their own icons and rules. AWS, Google Cloud, Azure and Kubernetes icons come at run time from each vendor's official package; for AWS, Google Cloud and Azure a miss fails rather than falling back to a third-party copy. Google gives only core products their own icon; the rest use a category icon. Azure icons must never be cropped, flipped, rotated or reshaped. A v0.4.0 fix limited the AWS rules to the AWS area; SKILL.md now applies that limit to every vendor's group.
- A look-before-you-ship step. The agent must render the HTML with headless Chromium and read the image before delivering: no arrow through label text, every icon visible in both themes, nothing outside its group. A node counts as its tile plus the text under it; vertical and elbow edges route around that box, while edges along a row join tile sides.
- The HTML is the source of truth. Fonts and logos are inlined as data URIs, so it renders offline and in an artifact sandbox. PNGs are screenshots of it; the TSX component copies its geometry but does not embed the fonts, using fallback font stacks instead.
- Sharing needs two yeses. After delivering, the agent offers once to post to the gallery at stacks.caru.moe. Before sending it shows the PNG paths and labels, an English title, the stack, a display name and any GitHub login (marked not public), flags anything that looks internal, and sends only after a second explicit yes. share.py rejects PNGs over 1 MB or outside 16 to 4000px a side; re-render with a lower --scale. Your prompt is never collected.
How it was built with Claude
Of the 30 caru-ini commits on main, 28 carry a Co-Authored-By: Claude trailer naming no model version; the three outside commits have none. The gallery's site/AGENTS.md tells agents to run pnpm check, check-types, test and build (heavy commands under a memory cap), never to start dev servers and never to edit a migration. An outside contributor still caught a proof-of-work limit mismatch between server and share.py, fixed in v0.5.0.
Try it with your AI. If you would rather not install the skill, this prompt asks your own agent for a similar diagram. Without the skill's template, geometry rules and scripts it only approximates the look. Fill in both bracketed lines first.
Draw an architecture diagram of my stack as one self-contained HTML file.
My stack: [one or two sentences: services, where they run, how they talk]
Output folder: [path; create it if missing, never overwrite existing files]
First check whether Playwright with Chromium is installed. If it is not, show me the
install commands (pip install playwright, then python3 -m playwright install --with-deps
chromium) and wait for my confirmation.
1. List the nodes (name plus a short role), the groups (shared runtime, vendor or repo;
one level of nesting at most) and the edges: solid accent for the main request path,
neutral solid for internal calls, dashed for CI and deploy. Show me the list before
drawing.
2. Use official logo files only: svgl.app, then devicon, then gilbarbara/logos. For AWS,
Google Cloud, Azure and Kubernetes services use only the vendor's official icon
package, never a third-party copy. If no source has a brand's logo, look for the
official file in the project's own repo or site; if you still cannot find one, stop
and ask me rather than substituting. Never recolor or redraw a logo; put a white logo
on a dark tile. Use plain line icons (for example Lucide) only for nodes with no
brand, such as a user, a queue or a cron job.
3. Inline fonts and logos as data URIs so the file works offline. Keep colors in CSS
variables and add a dark theme.
4. Render a PNG of both themes with headless Chromium and look at it. Fix any arrow that
crosses label text, any invisible icon and anything outside its group, then render
again.
5. In a footer, credit each icon source you actually used and note that logos remain
their owners' trademarks.
Do not upload or publish the diagram anywhere, and do not delete files. Finish with the
file paths and anything you guessed.Known limits
- Logos are other companies' trademarks. The README says they are downloaded at build time, not bundled, and imply no endorsement. Microsoft allows the Azure icons only in architecture diagrams, training materials and documentation; for AWS and Google icons the skill says redistribution is unconfirmed and tells you to keep icon packages out of repos.
- Icon licences differ: devicon is MIT, gilbarbara/logos CC0, the Kubernetes icons Apache-2.0 / CC-BY-4.0 and Lucide ISC. The skill credits the sources actually used, from manifest.json, in the diagram footer.
- Building needs network access, since icons may be fetched from svgl, GitHub, jsDelivr and vendor sites; the finished HTML and PNGs work offline.
- Japanese labels need a Japanese font on the machine that renders the PNG, or characters come out in Chinese glyph variants; render_png.py warns about this.
- The gallery is public and moderated: published posts can be indexed by search engines, held posts wait for manual review, and uploads stop for the day (UTC) at 200 in total or 5 from one address. The GitHub login, IP hash and delete-key hash never leave the server. Remove internal hostnames or customer names before sharing.
Get help and remove shared posts
On November 16 there were two open pull requests and no open issues. To remove a shared post, run python3 scripts/share.py delete with its id, or sign in to the gallery with the GitHub login you attached, if it was confirmed, and delete it there.
FAQ
How do I install stack-diagram?
Run npx skills add caru-ini/stack-diagram. In the Claude apps, download stack-diagram.zip from the latest GitHub release and upload it as a skill.
Are the logos bundled, and does using them mean the brands endorse my diagram?
No to both. Logos are downloaded at build time, and the README says their use does not imply endorsement.
Does the React component look the same as the HTML?
The geometry is the same, but the TSX does not embed the Geist and JetBrains Mono fonts; it uses fallback stacks, and loading those fonts restores the reference look.
Is it only for cloud architectures?
No. The README also shows a monorepo tooling diagram, and the HTML can go into a repo, a wiki or a Claude artifact.
What becomes public if I share a diagram?
The light and dark PNGs, an English title, the stack and a display name. Your prompt is never collected, and posting needs a second explicit yes.
Related on claudefox
- Floorplan: a Claude Code and Codex plugin that maps your codebase in plain English
- AWS releases AWS Emulator, a free local copy of its APIs written entirely by AI agents
- teardown: a Claude Code skill that builds take-apart 3D machine simulators as one offline HTML page
- ex-USSR Kinship Research: an evidence-first genealogy skill for Claude Code and Codex
Source: GitHub: caru-ini/stack-diagram, stack-diagram README, stack-diagram SKILL.md, stack-diagram fetch_icons.py, stack-diagram share.py, stack-diagram releases, stack-diagram commit history, stack-diagram gallery AGENTS.md, stack-diagram gallery README, stack-diagram issues and pull requests, stack-diagram gallery, skills.sh: caru-ini/stack-diagram
This story first appeared in the claudefox daily briefing for November 16, 2026.