{"id":"343fb83e-2987-4151-92c6-20dc5351aea7","slug":"architecture-drawer","kind":"skill","name":"architecture-drawer","summary":"Skill for Claude Code & Codex: describe your system architecture in text → get an editable PowerPoint diagram (native shapes, not a flat image).","owner":"Andy1314Chen","repoUrl":"https://github.com/Andy1314Chen/architecture-drawer","license":"MIT","licenseTier":"permissive","trust":"community","stars":44,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T05:55:18.993Z","logoUrl":"https://avatars.githubusercontent.com/u/18392483?u=b3aeb64a4d5c5d3114f2cf9f9aa5a8c7075d1e08&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media","files-documents","developer-tools"],"tags":["ai-agent","ai-agents","ai-tools","architecture-diagram","claude-code","codex","developer-tools","diagram-generator"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T06:45:14.654Z","sample":false,"url":"https://conduits.dev/tools/architecture-drawer","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# architecture-drawer\n\nEnglish · [简体中文](README.zh_CN.md)\n\nA skill for [Claude Code](https://code.claude.com), Codex, Open Code, Pi Agent, and other AI coding agents: turn a text description of your system architecture into an **editable PowerPoint architecture diagram**.\n\n![License](https://img.shields.io/badge/license-MIT-blue)\n\n---\n\n\n## What it is\n\nTurn **text descriptions** of an architecture into **editable PPT diagrams**: the agent generates an SVG from your description, auto-validates the layout, then exports to native PowerPoint shapes.\n\n### vs. direct image generation\n\n| | This project | Nano Banana / GPT-Image etc. |\n|---|---|---|\n| Output | **Editable PPT** (every shape draggable, recolorable, retextable) | Flattened image |\n| Control | High (code-generated, precisely adjustable) | Low (prompt-driven, hard to reproduce) |\n| Iteration | Fine-tune directly in PPT | Regenerate from scratch |\n| Cost | Low | High (per-image billing) |\n\n## Showcase\n\n\nAll diagrams below were generated entirely from text descriptions by the skill, then scored by the 13-dimension evaluator (each scored ≥76/100). They double as the regression suite under `evals/` — including the first non-architecture case (a process flowchart).\n\n### vLLM — High-Throughput LLM Inference Serving (PagedAttention)\n\n![](docs/showcase/vllm_arch.png)\n\nSix-layer request pipeline (client → API server → engine → paged KV cache → execution → optimizations). Solid edges = data flow; dashed = cache/block management. *Scheme S1 Monochrome Blue.*\n\n### MLIR AI Compiler — Multi-Stream Execution Pipeline\n\n![](docs/showcase/mlir_pipeline.png)\n\nA 4-layer × multi-column matrix (graph optimization → transformation → lowering → codegen) with vertical-fusion grouping and a concurrent multi-stream overlap timeline. *8-accent categorical palette.*\n\n### Agent Infrastructure — Layered Architecture\n\n![](docs/showcase/agent_infra_architecture.png)\n\nFive horizontal layers (application → orchestration → core capabilities → execution → infrastructure) with a cross-cutting security/observability band. Bilingual CN/EN labels. *Neutral grays + 5 colored core modules.*\n\n### CI/CD Deployment Pipeline — Process Flowchart\n\n![](docs/showcase/cicd_pipeline_flow.png)\n\nThe first non-architecture case: a top-to-bottom **process flowchart** with four quality-gate decisions (Build → Lint/SAST → Tests → Smoke) whose \"No\" branches converge via gray junction merge points onto a single Failed terminator. Green terminators · yellow decision diamonds · orange I/O hexagon · purple double-border subprocesses. *Flowchart role palette (color = role).*\n\n## Best Practices\n\n1. **Start with a clear text description.** Before coding, describe the architecture in prose—how many layers, what components each layer has, how they connect, and any special annotations. A crisp text spec (like the specs in `evals/*/input.md`) is the single biggest predictor of a quality diagram. For open-source projects, you can use the system architecture description from [DeepWiki](https://deepwiki.com).\n2. **Let the skill generate.** Submit the text description to the skill and let it generate the initial `gen.py` and SVG. The evaluator automatically catches overlaps, dangles, and crossings.\n3. **The skill auto-reviews the score.** If the score is ≥80, the diagram is structurally sound. If <80, the agent can automatically fix layout issues via `auto_refine` or by iterating on the evaluator report.\n4. **Export to PPTX for final polish.** Run `svg_to_pptx()` to get an editable PowerPoint file. Tweak colors, fonts, arrows, and layout there to match your brand or publication style—these belong in the presentation layer, not the generator code.\n\nSuggested workflow: first discuss with DeepWiki or your agent to produce a clear text description of the system architecture, then use this skill to quickly generate a PPTX diagram, and finally fine-tune colors, labels, and other details directly in PPT.\n\n## Install (Claude Code)\n\nThis repo is a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Add it and install the plugin:\n\n```\n/plugin marketplace add Andy1314Chen/architecture-drawer\n/plugin install architecture-drawer@architecture-drawer\n```\n\nOr from the CLI:\n\n```bash\nclaude plugin marketplace add Andy1314Chen/architecture-drawer\nclaude plugin install architecture-drawer@architecture-drawer\n```\n\nScope with `--scope project` (shared via version control) or `--scope local` (gitignored). Default is `user`.\n\n### Codex CLI\n\n> Codex CLI fully supports the [Agent Skills](https://agentskills.io) directory structure.\n\nCopy the skill directory into Codex's skills folder (usually `~/.codex/skills/`):\n\n```bash\ncp -r plugins/architecture-drawer/skills/architecture-drawer ~/.codex/skills/architecture-drawer\n```\n\nOr install project-scoped (recommended):\n\n```bash\nmkdir -p .codex/skills\ncp -r plugins/architecture-drawer/skills/architecture-drawer .codex/skills/\n```\n\nOnce installed, ask Codex naturally — the workflow in `SKILL.md` is consumed automatically:\n\n```\n> Draw the architecture of vLLM and export to PPTX\n```\n\n### Other agent platforms (Gemini CLI, Cursor, Copilot)\n\nEach skill is a standalone [Agent Skills spec](https://agentskills.io) directory. Copy it into your platform's skills location (typically `.agents/skills/`):\n\n| Platform | Default skills path |\n|---|---|\n| Gemini CLI | `~/.gemini/skills/` |\n| Cursor (@rules) | `.cursorrules` or `cursor/skills/` |\n| Copilot CLI | Per-platform instructions |\n\n```bash\ncp -r plugins/architecture-drawer/skills/architecture-drawer .agents/skills/architecture-drawer\n```\n\n## Dependencies\n\nThe agent generates a `gen.py` that imports four pure-Python modules (`svg_utils.py`, `evaluator.py`, `semantic_qa.py`, `svg2pptx.py`) co-located in the skill. You don't write this code — the agent does. Install these once so generated diagrams can render and export:\n\n| Dependency | Required by | Install |\n|---|---|---|\n| `python-pptx >= 1.0` | PPTX export (`svg2pptx.py`) | `pip install python-pptx` |\n| `rsvg-convert` | PNG rasterization (`rasterize_svg`) | `apt install librsvg2-bin` / `brew install librsvg` |\n| `pytest >= 8` | Running the test suite | `pip install pytest` |\n\n## Testing\n\nThe suite is layered so each layer is cheap, deterministic, and covers a distinct failure mode:\n\n| Layer | Command | What it gates | Runs in CI |\n|-------|---------|---------------|-----------|\n| **Deterministic regression** | `pytest` | each `evals/<name>/gen.py` scores ≥ its threshold and matches its golden SVG | ✅ always |\n| **Spec compliance** | `pytest` | `SKILL.md` frontmatter, name↔directory, relative refs, core scripts present | ✅ always |\n| **Doc ↔ API drift guard** | `pytest` | every `drawer.<m>(` documented in `SKILL.md`/`references/*.md` exists on `SVGDrawer`; curated public API importable | ✅ always |\n| **Agent replay** | `pytest --agent-replay` | install the skill into a leak-free sandbox, let the **Pi coding agent** author `gen.py`, assert score ≥80 + full SVG/PPTX/PNG/brief.json artifact quartet, SVG passing semantic QA against its `brief.json` contract | nightly / local |\n\nThe agent-replay layer is the closest to real usage: the skill is *installed* (never inlined), a real agent discovers it via its native skill mechanism, and the harness — not the agent — re-runs the produced `gen.py` deterministically. It needs the [`pi`](https://pi.dev) CLI and a provider key; backend wiring lives in `tests/agent_backends.py`. Pin **both** the provider and the model (`--agent-provider zai --agent-model glm-5.3`, or `PI_AGENT_PROVIDER`/`PI_AGENT_MODEL`) — the headless run otherwise inherits pi's interactive default provider, which may lack credentials and fail with an opaque upstream 403; a bare `--model` id can also be ambiguous across providers. Other options: `--agent-iter N` caps the stateless refine rounds (default 3), `--agent-eval <name>` restricts the run to one frozen eval, and `--agent-case <dir>` replays an **ad-hoc case outside the frozen set** — any directory containing an `input.md` spec; it never enters the deterministic regression set (no gen.py requirement, no golden snapshot), the agent authors `gen.py` in the sandbox, and `--agent-keep` retains everything under `output/agent_replay/<dir-name>/`.\n\n## Repository layout\n\n```\narchitecture-drawer/\n├── .claude-plugin/marketplace.json              # Claude Code marketplace registry\n├── plugins/architecture-drawer/\n│   ├── .claude-plugin/plugin.json               # plugin manifest\n│   └── skills/architecture-drawer/\n│       ├── SKILL.md                             # agent-consumable workflow (spec-compliant)\n│       ├── scripts/                             # svg_utils.py · evaluator.py · semantic_qa.py · svg2pptx.py\n│       ├── references/design_specs.md           # 4 preset color schemes (S1–S4)\n│       ├── evals/                               # 8 regression cases (7 architecture + 1 flowchart, gen.py each)\n│       └── assets/\n├── tests/                                       # pytest: layered regression (see \"Testing\")\n│   ├── conftest.py                              # fixtures, thresholds, score helpers, CLI options\n│   ├── agent_backends.py                        # Pi coding-agent backend + leak-free sandbox builder\n│   ├── test_regression.py                       # deterministic quality+snapshot for every frozen gen.py\n│   ├── test_skill_spec.py                       # Agent Skills spec compliance\n│   ├── test_doc_api.py                          # doc ↔ API drift guard (always on)\n│   ├── test_semantic_qa.py                      # semantic QA: marker/size/label/route/text checks\n│   ├── test_agent_replay.py                     # opt-in real-agent replay (Pi)\n│   └── golden/*.svg                             # snapshot baselines\n└── examples/                                    # minimal demo of the generate-evaluate-export loop\n```\n\n## Community\n\nThanks to the [LINUX DO](https://linux.do) community. The project gained wider reach, discussion, and real-world feedback after being shared there, and those conversations have helped me keep finding issues and improving architecture-drawer.\n\n## References & acknowledgments\n\nThe geometry/connection detection draws on several open-source projects (their reference docs and validators were studied): [ink-graph](https://github.com/qaz1230sp/ink-graph), [fireworks-tech-graph](https://github.com/yizhiyanhua-ai/fireworks-tech-graph), [svg-animations](https://github.com/supermemoryai/skills), [svg-design](https://github.com/tryopendata/skills), and [svg2pptx](https://github.com/benouinirachid/svg2pptx) (the architectural blueprint for the PPTX export module). See the full credits in [`SKILL.md`](plugins/architecture-drawer/skills/architecture-drawer/SKILL.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n"}