d2-diagrams

Files (25)

• SKILL.md
• .gitkeep · assets/
• REFERENCE.md · references/
• classes-reuse.md · references/
• cli.md · references/
• composition.md · references/
• connections.md · references/
• containers.md · references/
• globs.md · references/
• grid-diagrams.md · references/
• icons.md · references/
• imports.md · references/
• interactive.md · references/
• layouts.md · references/
• overrides.md · references/
• positioning.md · references/
• sequence-diagrams.md · references/
• shapes.md · references/
• sql-tables.md · references/
• style.md · references/
• text.md · references/
• themes.md · references/
• uml-classes.md · references/
• vars.md · references/
• .gitkeep · scripts/

SKILL.md (first lines)

## Overview

## Purpose

Create d2 diagrams for any purpose:

- system architecture
- data flow
- sequence interactions
- database schemas
- class hierarchies
- grid layouts
- multi-board compositions

## When to Use

The user wants a visual diagram and either explicitly asks for d2 or asks for a diagram
type that d2 handles well. Examples:

- "Create an architecture diagram showing how the services connect"
- "Draw a sequence diagram of the auth flow"
- "Make an ER diagram for these database tables"
- "Lay out a grid showing all 12 microservices"
- "Diagram the deployment pipeline with different scenarios"
- "I need a class diagram for this data model"

## Principles

## Process

### 1. Understand what the user wants

Determine:

- **Diagram type** — which d2 feature to use (see diagram type guide below)
- **Content** — what entities, relationships, and labels to include
- **Output path** — where to write the file (default: working directory or `.task/`)

If the request is clear, skip straight to reading docs and writing.

### 2. Read the relevant docs

The `docs/` subdirectory (relative to this skill file) contains comprehensive d2 reference
documentation. Read only what you need for the diagram at hand:

| Diagram type                       | Read these docs                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| Architecture / flowchart / general | `references/shapes.md`, `references/containers.md`, `references/connections.md` |
| Sequence diagram                   | `references/sequence-diagrams.md`, `references/connections.md`                  |
| Grid / dashboard layout            | `references/grid-diagrams.md`                                                   |
| ER / database schema               | `references/sql-tables.md`, `references/connections.md`                         |
| UML class diagram                  | `references/uml-classes.md`, `references/connections.md`                        |
| Multi-board (scenarios/steps)      | `references/composition.md`                                                     |
| Any diagram needing styling        | `references/style.md`, `references/themes.md`, `references/icons.md`            |
| Positioning / layout control       | `references/layouts.md`, `references/positioning.md`                            |
| Reusable styles                    | `references/classes-reuse.md`, `references/vars.md`, `references/globs.md`      |
| Text / labels / code blocks        | `references/text.md`                                                            |
| Tooltips / links                   | `references/interactive.md`                                                     |
| CLI flags / rendering              | `references/cli.md`                                                             |

Always read the docs before writing d2 — they contain the exact syntax and valid values.
Don't rely on memory for d2 specifics; the docs are the source of truth.

### 3. Write the d2 file

#### Diagram type guide

**Standard graphs** (architecture, flowcharts, call graphs, data flow):

```d2
direction: right

client: Client
server: Backend Server {
  api: API Gateway
  auth: Auth Service
  db: Database {
    shape: cylinder
  }
}
client -> server.api: HTTPS
server.api -> server.auth: validate
server.api -> server.db: query
```

**Sequence diagrams** — set `shape: sequence_diagram` on a container. Order of declarations
controls visual order. All actors share scope within the sequence container:

```d2
auth_flow: {
  shape: sequence_diagram
  client
  api
  auth
  db

  client -> api: POST /login
  api -> auth: validate credentials
  auth -> db: lookup user
  db -> auth: user record
  auth -> api: JWT token
  api -> client: 200 OK + token
}
```

**Grid diagrams** — use `grid-rows` and/or `grid-columns` for matrix layouts:

```d2
services: {
  grid-columns: 3
  grid-gap: 20
  svc_a: Service A
  svc_b: Service B
  svc_c: Service C
  svc_d: Service D
  svc_e: Service E
  svc_f: Service F
}
```

From rock-hu/agent-skills, Apache-2.0.

More from rock-hu/agent-skills