D2 Diagram Author

Generate idiomatic .d2 source files — diagrams encoded as declarative text, rendered by the official d2 CLI to SVG / PNG / PDF / GIF. The output is human-readable, diffable, and embeds anywhere D2 embeds (GitHub, Notion, VS Code, docs sites, Oxide's play.d2lang.com).

Keep this entry file small. Load only the reference packs that match the current diagram.

Always-On Rules

1. Output is .d2 text, nothing else. The skill never invokes a renderer; the user runs d2 input.d2 out.svg or opens play.d2lang.com. Quality must be enforceable by reading the source.
2. Idiomatic D2 over clever D2. Prefer declarative node names (api -> db) over IDs + labels when the name reads naturally. Reach for label: only when the natural name would be awkward or duplicated.
3. Shape type matches concept. A database is shape: cylinder, a queue is shape: queue, an actor is shape: person. Never default everything to rectangle. Full catalog in references/shapes.md.
4. Direction declared up front. Set direction: down | right | up | left on the root (and per container if needed). Layout direction is a communication choice, not an incidental default.
5. Semantic edge style, not ornamental. stroke-dash for async / weak dependency; animated: true for streams; stroke color to encode criticality / failure paths. Catalog in references/connections.md.
6. Group by container, not by proximity. If nodes belong to one domain (a subsystem, a cloud, a bounded context), nest them in a container map. Containers are D2's native grouping — use them instead of manual placement.
7. One concept per diagram. If a diagram answers two questions, split into two layers: or two files. Don't compress.
8. Classes for repetition. ≥ 2 nodes share styling → define a class in classes: {} and apply with .class: name or a glob.
9. No invented shapes. All shape: values must come from references/shapes.md. D2 silently falls back to rectangle on typos, which is the worst failure mode: it looks right but isn't.
10. Commit-ready source. File ends with a newline, uses 2-space indentation, no trailing whitespace, comments explain intent not mechanics. D2 is git-friendly — keep it that way.