This skill is for drawing container-based layered diagrams (diagrams with the structure of "large containers nesting small containers, multi-level vertical nesting"). D2 is the implementation method (d2lang.com). This SKILL.md is a router — read it for main workflow, iron rules, and triage; refer to documents under

references/

as needed (see §4 References Routing Table).

• C4 model Container Diagram: Shows what containers a software system consists of (Official C4 definition: "A container represents an application or data store... The container diagram shows the high-level technology choices and how the containers communicate with one another.").
• Technical architecture diagrams / product architecture diagrams / business capability layered diagrams / microservice architecture diagrams: Any diagram that fits the form of "multi-level vertical nesting of large containers + sub-container distribution" is applicable to this skill.

• Container = An independently divisible unit in the diagram (application, service, data storage, business module, etc.), not Docker container.
• Container-based layered diagram = Zoom in on a system/product/business to show "what containers it consists of + how containers communicate with each other".

For the 9 characteristic requirements, feature-to-syntax mapping, dynamic padding calculation, and layered specifications (color/spacing/shape/rounded corner/color scheme), see references/c4-container-spec.md.

The following iron rules are the final effect standards — any syntax or template must comply. Self-check against them after generation; if not met =不合格, must adjust.

D2 is a declarative DSL — every requirement can be guaranteed by syntax from the source, no need to "draw first then check for errors". When generating code, ensure that the syntax naturally meets the requirements, and rendering is only for verification.

1. Align structure (Steps 1-3 in §2 Workflow)
2. Calculate the width/height of all sub-containers using the formulas in references/layout-and-grid.md (every container, every partition, every sub-module)
3. Attach rounded corner classes to each node as specified in c4-container-spec.md §4.8
4. Write code → render → self-check verification (should pass at one time)

1. User input points to an existing d2 block — provides location + diagram name ("the capability layered diagram in

   docs/L1/PRODUCT-SPEC.md

   "), pastes the code block, or says "modify/adjust/update that diagram" → Modify Mode (§2.3 Workbench extract → modify → render → sync)
2. User uses new diagram terms (draw/create/add a new diagram) and does not reference existing blocks → New Mode (complete all 5 steps in §2.2; if there is another diagram at the target location → insert a new block, do not touch the old diagram)
3. User says redraw/override/regenerate a certain diagram → Modify Mode (replace the code block)
4. User says "check/look at" → Read-Only Mode (acceptance via troubleshooting.md, no code modification)

• Unable to locate: User does not provide document path/cannot find any d2 block, and cannot clarify intent → ask "Where is the target document/diagram?"
• Multiple blocks do not match: The document has multiple d2 blocks, and the diagram name mentioned by the user does not match the first-line comment of any block → list the diagram names of each block for the user to choose ("The document contains: ① System Architecture Diagram ② Deployment Architecture Diagram... Which one to modify?")
• No location at all: Only says "draw a diagram" without any document clues → ask "Where to draw it?"

Rendering Method: d2 code blocks are automatically rendered by the project Markdown rendering engine (embedded ```d2 is rendered). AI does not manually render SVG to files — all diagram outputs are in Markdown code blocks. Only temporarily render SVG with scripts for verification during self-check (see references/troubleshooting.md).

CRITICAL — BLOCKING (Blocking Requirement #1, Step 2): Before drawing an architecture diagram, must first align with the user on number of layers / modules in each layer / label style (top-centered vs left vertical arrangement). Prohibit writing d2 code before alignment.

CRITICAL — BLOCKING (Blocking Requirement #2, Step 3): Before writing the d2 code block, MUST first show the general structure of the diagram (number of layers + modules in each layer + connections between layers) to the user via an ASCII architecture diagram in the conversation. Prohibit writing d2 code before user confirmation. (See references/templates.md for ASCII diagram elements)

1. Locate the target Markdown document: Confirm the insertion position (new) or target code block (modify). Prohibit writing d2 code before confirming the target document
2. Align architecture diagram parameters (Mandatory, Blocking #1): Confirm with the user: ① Number of layers (usually 3~6 layers); ② Module names in each layer (users will list each product/service/capability name — must use real business labels, prohibit placeholders such as e1/e2/c1/c2, placeholders only appear in skill template examples); ③ Label style (top-centered = mainstream / left vertical arrangement = architect-style); ④ Color preference (default to the five layer systems of blue/purple/green/orange/gray, or user-specified); ⑤ Whether inter-layer arrows are needed (default to implicit dependency via stacking; when arrows are needed, only connect between layer containers, parent to parent, see references/connection-routing.md)
3. ASCII Architecture Confirmation (Mandatory, Blocking #2): Directly output an ASCII architecture diagram (number of layers + modules in each layer + connections between layers + label position) in a

   text

   code block in the conversation, and wait for the user's explicit confirmation. If the user proposes modifications, update the ASCII diagram and confirm again. (See references/templates.md)
4. Write/modify the

   ```d2

   code block in the target document: Write the diagram name comment in the first line (

   # Diagram Name

   ) — this is the identifier of the diagram, and subsequent location/modification relies on semantic matching (§2.1), prohibit omission. Format is not limited: Chinese is preferred (e.g.,

   # System Architecture Diagram

   ), subject to user preference, both Chinese and English are acceptable (e.g.,

   # System Architecture

   ) — the key is to have an identifiable name. Start the second line with

   vars: { d2-config: { layout-engine: elk } }

   (default elk), and you can continue to write meta-information comments such as perspective/purpose. After writing, rendering is automatically completed by the Markdown engine, AI does not perform any output/rendering actions
5. Self-check: Use one command from §2.3 Workbench (automatically verify viewBox/overflow/equal width/rounded corners) — for new diagrams:

   extract docs.md --name Diagram Name

   to extract the newly written block for verification (no sync needed); for modifications to existing diagrams:

   extract → render → sync

   . Use the manual process in troubleshooting.md only when the workbench is unavailable.

```d2

verify-svg.py

Objective: Modify diagrams quickly from the second time (3~5 minutes each time), not rewrite the entire diagram. Core principle: Authoritative source = Markdown code block, always modify the original document content when changing code (keep

\n

literals); temporary .d2 files are read-only for verification, prohibit "modifying temporary files then copying back" to cause duplicate maintenance. If the target block has no diagram name (no first-line comment): First ask the user to add a name (can suggest), add it before modifying — make all diagrams identifiable (§2.1).

undefined

text

See references/templates.md for the ASCII architecture diagram element list + complete examples, and confirmation protocol. Prohibit writing d2 code or calling rendering commands before the user's explicit confirmation (blocking requirement).

\n

diagram-review.md

is a project-specific post-rendering organization review checklist; other

connections/containers/elk/grid-diagrams

are localized D2 official documents.

Each of the following is a red line, must adjust to comply if violated. See corresponding references for detailed rules.

1. Explicit width calculation for each layer: For each layer of nesting (A→B→C→D), explicitly calculate the width of sub-containers (references/layout-and-grid.md); the only exception: single-column vertical bars do not require setting width, let ELK automatically wrap and center them. Calculating only the outermost layer will cause "left-aligned offset".
2. Parent-to-parent arrows: Inter-layer arrows only connect between parent layer containers (

   Overall Architecture.Layer A -> Overall Architecture.Layer B

   ), do not connect sub-containers within layers; must write the complete path, otherwise d2 silently creates duplicate top-level nodes (references/connection-routing.md).
3. Multi-board diagrams prohibited:

   layers/scenarios/steps

   multi-board syntax cannot be output by the Markdown rendering engine, split into multiple independent

   ```d2

   code blocks (references/d2-syntax-cheatsheet.md).
4. TALA engine prohibited: TALA is closed-source and paid (free version has watermarks), use

   elk

   uniformly (d2-syntax-cheatsheet.md).
5. viewBox integer overflow: Combination of multiple classes + deep nesting + vertical bars will trigger ELK int64 overflow (viewBox=-9e18 blank diagram). Must use single class + outer 1×1 grid + no width setting for vertical bars (d2-syntax-cheatsheet.md §6.16).

6. \n

   Line Break Iron Rule: Write

   \n

   literal (two characters: backslash + n) for line breaks in labels, prohibit actual line breaks; long labels (>8 characters) must be split with

   \n

   into lines with ≤8 characters each (d2-syntax-cheatsheet.md §6.17).
7. Global rounded rectangles: Every graphic (outer layer/layer/partition/innermost sub-module/vertical bar) must have rounded corners (c4-container-spec.md §4.8).

Use one command from the workbench script (automatically verify viewBox/overflow/equal width/rounded corners), see references/troubleshooting.md for detailed process.

undefined

Complete templates (3-layer standard/vertical arrangement/vertical bar/intra-layer partition) are available in references/templates.md.

undefined