--- name: d2-diagrams description: Create or change D2 diagrams in elaborat.ing and embed them in notes. Use only when the user asks for D2, or for a structured diagram that has to be laid out from code, such as database tables and their relationships, a sequence diagram or a graph with dozens of connected nodes. For other diagrams, flows and architecture, make a drawing instead. --- # D2 diagrams The user's instructions win over this skill when they differ. Make a D2 diagram only when the user asks for D2, or when the diagram is structured enough that it has to be laid out from code. When they ask to draw, sketch or diagram something else, make a drawing (the drawings skill). ## Files - A diagram is D2 source in a `.d2` file, such as `diagrams/sign-in.d2`. Write only that file. When someone opens it in the app, the app lays it out and saves two files next to it: the canvas (`sign-in.excalidraw`), which keeps shapes people moved and anything drawn by hand, and a layout record (`sign-in.d2.json`). Don't write or edit those two. - To change a diagram, read its `.d2` file and save the new source with its `base_version`: with `update_and_show` when the user should watch the change happen in the chat, or with `write_file` for a quiet change. Changes made by hand on the canvas survive the next layout. - To move, rename or delete a diagram, do the same to each of its three files that exists (see `list_files`) in one `save_files` call, so they stay together. - Embed it in a note with ``. The file must exist, so create it first or in the same `save_files` call. - To make a new diagram the user should watch being written, use `create_and_show`, before the note that embeds it. - The card of `show_file`, `create_and_show` and `update_and_show` shows the diagram drawn. A new diagram, which has no canvas until it is opened in the app, and one whose source changed are laid out from the source in the chat, where the chat allows that. Where it does not, the card says to open the diagram in elaborat.ing: give the user the link. - Comments on a diagram's shapes are on its canvas: to add one, use the `.excalidraw` path and the shape's `element_id` with `add_comment`. ## Inspect the rendered diagram After a visual change, use `get_file_preview` on the saved `.d2` path to inspect its stored pixels, labels, spacing and connections. Background preparation preserves the app's manual canvas changes and can project missing or stale generated files without saving them. Syntax errors and merge conflicts remain explicit; do not treat an old canvas as a successful preview of new source. For a readable detail crop, pass a normalized `region` and the overview's `snapshot` as `expected_snapshot`. Crops use the stored image resolution. A conflict requires a new overview. If the preview is `pending`, wait for `retry_after` before reading again. Preview reads never start rendering or change files. Use `show_file` to present the diagram to the person. If a preview fails or is unavailable, state what you could not visually verify. ## Writing D2 - Layout is automatic, so don't give positions. Set `direction: right` or `direction: down` at the top. - These shapes are drawn as themselves: rectangle (the default), square, oval, circle, diamond, text and sql_table. A container (`api: { web; worker }`) becomes a frame. Other shapes, such as cylinder or person, are drawn as boxes. - Keep labels short and put the detail in the note around the diagram. ```d2 direction: right start: Start {shape: oval} check: Approved? {shape: diamond} ship: Ship it fix: Fix issues start -> check: submit check -> ship: yes check -> fix: no fix -> check: revise ``` A table diagram: ```d2 users: { shape: sql_table id: int {constraint: primary_key} email: varchar {constraint: unique} } orders: { shape: sql_table id: int {constraint: primary_key} user_id: int {constraint: foreign_key} } users.id <-> orders.user_id: places ```