The GitHub repository caru-ini/stack-diagram trended in early November 2026 because it turns a boring chore — drawing architecture diagrams with correct logos — into a repeatable agent skill. You write one sentence about your production stack. The agent fetches official icons, routes connectors so lines do not slice through text, and hands back a self-contained HTML file (or PNG / React) you can drop into a wiki, PR or deck.
If you already use agent skills for coding, this is the same packaging idea applied to documentation craft, not model weights.
TL;DR #
| Question | Answer |
|---|---|
| What do I run? | npx skills add caru-ini/stack-diagram per the README |
| Hosts named | Claude Code, Codex, Cursor, other agentskills.io clients |
| Default output | Single HTML file with inlined fonts and logos |
| Themes | Light and dark renders; tiles stay white for brand colors |
| Logo sources | svgl, devicon, vendor packs (AWS, GCP, Azure) |
| Python needed? | Yes, 3.9+ for the build scripts |
| PNG path | Playwright plus Chromium |
| License | MIT for code; logos remain vendor trademarks |
Why developers forwarded it #
Architecture diagrams fail in two predictable ways: wrong logos (recolored SVG hacks) and unreadable routing (arrows through labels). The README promises both are handled — official assets only, lines routed around text, and the agent re-renders to check before delivery.
That matches what teams actually argue about in design reviews, not what slide templates optimize for. It also rides the same wave as skills we covered for Claude animated shorts via Remotion and Blader humanizer patterns: small repos that become agent-native utilities faster than traditional npm CLIs because npx skills add lowers install friction.
The repo's skills.sh badge links to skills.sh/caru-ini/stack-diagram, the discovery surface many Cursor and Claude users search before GitHub Trending.
What the skill actually does #
From the README workflow:
- Parse a natural-language stack description (example: Next.js and Hono on Vercel, Postgres on Neon, auth with Clerk).
- Resolve each named product to a logo pipeline: trysvgl , thendevicon , thengilbarbara/logos , then vendor repositories.AWS, Google Cloud and Azure icons come from each cloud's published packs.
- Layout groups and edges, enforcingno arrows through labels .
- Render HTML withinlined fonts and logos so the file works offline — important for artifacts and email attachments.
- Optionally export PNG or adependency-free React component from the same source.
The output is explicitly not a generic whiteboard export. It is a branded architecture view suitable for RFCs and onboarding docs.
stack-diagram packages architecture-diagram generation as an installable agent skill
Install paths and host differences #
Terminal-first agents use:
npx skills add caru-ini/stack-diagram
Claude apps without CLI skills can upload stack-diagram.zip from GitHub Releases as a skill bundle.
Cursor users should confirm their build supports the same skills ; the README points to agentskills.io for the compatibility list. If your client only runs MCP tools, this repo is not an MCP server — it is a skill package with Python helpers underneath.
Our agent skills complete guide explains how skills differ from MCP and from raw prompts; stack-diagram is a worked example of skills as packaged procedures plus local scripts.
stack-diagram resolves product names to official logo pipelines through svgl, devicon and vendor packs
Examples in the README #
The project ships prompt templates beyond SaaS web apps:
- Dev tooling monorepos — pnpm, Turborepo, Biome, Vitest, Lefthook, GitHub Actions.
- AI apps — Next.js on Vercel, Supabase pgvector, Claude, Inngest syncing Notion.
- Regional cloud layouts — AWS, GCP and Azure three-tier patterns withvendor-native icons .
Each example reinforces one design rule: name real products, not abstract boxes. The skill's matcher lives or dies on whether it recognizes your strings.
Gallery and privacy #
After a diagram, the agent may offer once to publish light and dark PNGs to stacks.caru.moe. The README states:
- It shows exactly what would be public (PNGs, English title, stack list, display name).
- It requires two explicit yes answers .
- Your prompt is never sent .
- GitHub login is optional and only enables later deletion.
For teams under NDA, decline the gallery. The local HTML artifact still works.
Licensing and trademark hygiene #
Code and docs are MIT. Fonts use SIL Open Font License 1.1. Logos are not bundled; they download at build time under each vendor's terms. The README repeats that diagram use is not endorsement and that Microsoft permits Azure icons in architecture diagrams per their published guidance.
That matters for commercial decks. A skill that auto-fetches logos is convenient; your legal review may still want a static export archived with attribution.
Limitations honest builders should expect #
- Network required for logo fetches during generation.
- Python 3.9+ and, for PNG,Playwright/Chromium — CI containers need those dependencies.
- Ambiguous names ("Oracle" database versus cloud) can map wrong; edit the sentence and regenerate.
- Star counts move ; verify the README on the commit you install, not a screenshot from social media.
The GitHub page showed zero stars in one automated fetch while Trending metadata cited thousands gained since November 1 — typical lag between indexer snapshots and the trending email. Use the repo's release tags and issue tracker for maturity, not stars alone.
How this compares to doing it manually #
| Approach | Pros | Cons |
|---|---|---|
| stack-diagram skill | Fast, logo-accurate, agent-driven iteration | Python and Playwright setup |
| Figma / Lucid templates | Designer polish | Manual logo compliance |
| Mermaid in markdown | Version controlled | Weak logo fidelity |
| Cloud vendor diagram tools | Official stencils | Lock-in to one hyperscaler |
For agent-heavy teams, the skill wins on iteration speed when the diagram is a living document during refactors. For customer-facing PDFs, you may still touch up spacing in a design tool.
Security note #
The skill runs local Python and fetches third-party SVGs. Treat it like any agent tool chain: run in a trusted environment, pin the skill version in team docs, and review HTML output before hosting on a public domain (inline resources can be large but should not execute remote scripts if you use the stock templates).
For broader agent hardening patterns, see agent sandboxes compared and loop engineering with coding agents.
What people ask after seeing the repo #
Do I need a paid API? No for the skill itself — you pay whatever model your agent host bills. Logo fetches hit public CDNs and vendor icon hosts.
Can I use this in client deliverables? The MIT license covers the tooling. Logo trademark rules still belong to each vendor; keep the README's attribution mindset.
Does it replace C4 models? No. C4 captures context containers and components; stack-diagram optimizes logo fidelity for one snapshot of what you run today. Many teams will use both: C4 for narrative, stack-diagram for the quick "what we deploy" slide.
Will it understand internal codenames? Unlikely. Replace internal service names with the public product you actually run in prod, or add a gloss line the matcher can grep.
How does this relate to explainx.ai skills? Our skills directory catalogs installable agent procedures for workshops and products. stack-diagram is an external skill you add the same way you would add a lint or deploy skill — it does not ship inside explainx.ai, but it is the kind of utility we expect in agent-heavy teams.
Maintenance and team rollout #
Rollout works best as a doc template, not a one-off demo:
- Add the skill to your team skill manifest alongside testing and formatting skills.
- Store generated HTML under
docs/architecture/in git so PRs show diagram diffs when stacks change. - Pin the release zip version for Claude app users; floating
latestwill drift when logo sources move. - In CI, skip PNG generation unless you maintain a Playwright image; HTML-only keeps pipelines light.
When your stack changes — say you migrate auth from one vendor to another — regenerate in the same skill session so group boxes stay aligned. The README's light and dark pair helps Confluence and Notion pages that auto-theme.
Deeper comparison to diagram-as-code #
Diagram-as-code tools (Mermaid, D2, PlantUML) excel at git diffs and reviewability. stack-diagram trades some purity for marketing-grade icons. A sensible split:
- Use Mermaid inside engineering specs for flows and sequence diagrams.
- Use stack-diagram for onboarding README heroes and executive summaries.
- Export PNG only when the audience lives in PowerPoint or PDF.
If you already document agents with DESIGN.md patterns, paste the stack sentence from your DESIGN stack section to keep diagrams synchronized with declared dependencies.
Try it in five minutes #
- Clone or
npx skills add caru-ini/stack-diagram. - Paste a sentence that names at least five concrete products you deploy today.
- Ask the agent for HTML first ; open the file locally and toggle dark mode if your template supports it.
- Only then request PNG if you need slides.
- Decline gallery upload unless marketing owns the stack list.
Related reading #
Document the prompt sentence your team standardizes on — for example listing hosting, database, auth, payments and CI in fixed order — so diffs stay readable when only one vendor changes.
Repository layout and commands follow the caru-ini/stack-diagram README as read on November 9, 2026.