d2 - SKILL.md Agent Skill

name: d2 description: "D2 diagramming language reference for architecture diagrams, sequence diagrams, grid layouts, SQL tables, and class diagrams. Produces .d2 files rendered via CLI or playground."

D2 Diagramming Language

D2 is a text-to-diagram language. Write .d2 files and render them to SVG/PNG via the d2 CLI or https://play.d2lang.com.

When to Use

Creating architecture or system diagrams for plans and documentation
Drawing sequence diagrams for API or workflow interactions
Building data model diagrams with SQL table shapes
Laying out grid-based comparison or dashboard diagrams
Visualizing deployment topologies, state machines, or flowcharts

Quick Reference

Concept	Syntax
Shape	`name` or `name: Label`
Connection	`a -> b` or `a -> b: label`
Reverse / bidirectional	`a <- b` / `a <-> b`
Line (no arrow)	`a -- b`
Container	`parent: { child1; child2 }`
Dot nesting	`parent.child.grandchild`
Set shape type	`name.shape: oval`
Style	`name.style.fill: "#ff0000"`
Icon	`name.icon: https://url/icon.svg`
Tooltip	`name.tooltip: hover text`
Link	`name.link: https://example.com`
Class	`classes: { c: { style: {...} } }` then `name.class: c`
Variable	`vars: { k: v }` then `${k}`
Direction	`direction: right`
Comment	`# single line comment`
SQL table	`name.shape: sql_table` then `col: type {constraint: pk}`
Sequence diagram	`name.shape: sequence_diagram`
Grid	`name.grid-rows: 3` or `name.grid-columns: 3`
Layers	`layers: { name: { ... } }`
Scenarios	`scenarios: { name: { ... } }` (inherits parent)
Steps	`steps: { 1: { ... } 2: { ... } }` (each inherits previous)
Import	`a: @file` or `...@file` (spread)
Glob	`.style.fill: red` / `*.style.fill: red`
Null (delete)	`x: null` / `(a -> b)[0]: null`

Core Syntax

Shapes

Any identifier becomes a shape. The default shape is rectangle.

server
database: My Database
api: API Gateway {
  shape: hexagon
}

All shape types: rectangle, square, page, parallelogram, document, cylinder, queue, package, step, callout, stored_data, person, diamond, oval, circle, hexagon, cloud, text, code, class, sql_table, image, sequence_diagram, c4-person.

Connections

a -> b: request
b -> a: response
a <-> b: bidirectional
a -- b: line (no arrowhead)

# Multiple connections between same shapes are indexed
a -> b: first   # (a -> b)[0]
a -> b: second  # (a -> b)[1]

Connection References

Style existing connections by referencing them:

a -> b: request
(a -> b)[0].style.stroke: red
(a -> b)[0].style.stroke-dash: 5

Arrowheads

a -> b: {
  source-arrowhead: 1 {
    shape: diamond
  }
  target-arrowhead: * {
    shape: cf-many
  }
}

Arrowhead shapes: triangle (default), arrow, diamond, circle, cf-one, cf-many, cf-one-required, cf-many-required.

Containers (Nesting)

cloud: AWS {
  vpc: VPC {
    subnet: Private Subnet {
      ec2: Web Server
      db: Database {
        shape: cylinder
      }
    }
  }
}

# Dot notation shorthand
cloud.vpc.subnet.ec2 -> cloud.vpc.subnet.db: query

Labels and Text

# Markdown labels
explanation: |md
  # Architecture Overview
  This system uses **microservices**.
|

# Code blocks
snippet: |go
  func main() {
    fmt.Println("hello")
  }
|

# LaTeX
formula: |latex
  \\frac{n!}{k!(n-k)!}
|

Direction

Controls layout flow. Values: up, down (default), left, right.

direction: right
a -> b -> c

Null (Deletion)

Remove shapes, connections, or attributes:

x: {style.fill: red}
x.style.fill: null    # remove fill
x: null                # remove shape entirely
(a -> b)[0]: null      # remove connection

Comments

# This is a comment
server  # Inline comment

"""
This is a block comment
spanning multiple lines
"""

Positions (near)

Position items at fixed points around the diagram:

title: Architecture Overview {
  shape: text
  near: top-center
  style.font-size: 28
}

legend: {
  near: bottom-right
}

Values: top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right.

Label/icon positioning (additional values):

node: {
  label.near: outside-top-center
  icon: https://icons.terrastruct.com/aws/Compute/Amazon-EC2.svg
  icon.near: outside-left-center
}

Extra values for label/icon: outside-top-left, outside-top-center, outside-top-right, outside-left-center, outside-right-center, outside-bottom-left, outside-bottom-center, outside-bottom-right.

Dimensions

node: {
  width: 200
  height: 100
}

Cannot be set on containers (they resize to fit children).

Configuration via Vars

vars: {
  d2-config: {
    theme-id: 4
    dark-theme-id: 200
    pad: 50
    center: true
    sketch: true
    layout-engine: elk
  }
}

Layout engines: dagre (default, free), elk (free, more features), tala (premium).

Resource Files

For detailed guidance, read these on-demand:

shapes-and-connections.md — Complete shape catalog, connection types, arrowheads
styling-and-layout.md — All style properties, classes, themes, layout engines
special-diagrams.md — Sequence diagrams, grid layouts, SQL tables, class diagrams
composition-and-advanced.md — Vars, globs, imports, layers, scenarios, steps

Input / Output

This skill defines no input parameters or structured output.