Skip to main content
skill CX Codex

diagrams-as-code — Claude Code skill for architecture diagrams

diagrams-as-code is a Claude Code skill that creates architecture and infrastructure diagrams with Python’s diagrams library. It turns code-defined schemes into image files.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill diagrams-as-code -a claude-code
Open on GitHub

What diagrams-as-code does

The skill checks for Graphviz and diagrams, writes a Python script in the working directory, runs it, and reports the output path. Graphviz renders the script as an image. You can set diagram direction and output format, connect nodes, and group components inside nested clusters. Setting show=False keeps the run non-interactive.

Node categories cover cloud providers, Kubernetes, and on-premises infrastructure; custom nodes can use a local PNG icon. Graphviz must be available or the script fails, so the skill checks for it before generating a diagram. Graph, node, and edge attributes let you style the result, and a single script can produce multiple output formats.

What it helps with

  • build an architecture diagram from Python code
  • map service and database connections
  • group components into network clusters
  • export a diagram as PNG and SVG

Example prompts for the agent

  • Create an AWS architecture diagram with EC2, Lambda, and RDS, then save it as PNG.
  • Map requests from ELB to two EC2 nodes and onward to RDS.
  • Group services under VPC and Private Subnet and render the diagram as SVG.

How to install diagrams-as-code

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill diagrams-as-code -a claude-code

2Manually: put the files in place

~/.claude/skills/diagrams-as-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagrams-as-code/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about diagrams-as-code

How do I install diagrams-as-code in Claude Code?

Run npx skills add sammcj/agentic-coding --skill diagrams-as-code -a claude-code. The skill file is at ~/.claude/skills/diagrams-as-code/SKILL.md.

What does diagrams-as-code do?

It helps create architecture and infrastructure diagrams using Python’s diagrams library. Graphviz renders the script into an image file.

What do I need to run diagrams-as-code?

Graphviz and the Python package diagrams are required. The skill checks for them before running the script.

Source text

SKILL.md · Apache-2.0
---
name: diagrams-as-code
description: Use only when creating architecture diagrams with Python's `diagrams` library (mingrammer/diagrams).
allowed-tools: Bash(python3 *) Bash(uv *) Bash(pip install *) Bash(command -v *) Bash(brew install *) Read Write Edit Glob Grep
---

# Diagrams as Code

Generate architecture and infrastructure diagrams using the Python `diagrams` library. Diagrams are Python scripts that render to image files via Graphviz.

## Workflow

1. **Check prerequisites** - verify graphviz and diagrams are installed
2. **Write the diagram script** to a `.py` file in the user's working directory
3. **Run it** with `python3 <file>.py`
4. **Report the output path** to the user (image appears in working directory)

### Prerequisites check

```bash
command -v dot >/dev/null || brew install graphviz
uv pip install --system diagrams 2>/dev/null || pip install diagrams
```

Without graphviz, the script fails with a cryptic error. Always verify first.

## Core API

### Diagram context manager

```python
from diagrams import Diagram

with Diagram(
    name="Title",           # used as default filename (slugified)
    filename="output",      # override filename (no extension)
    direction="LR",         # LR | RL | TB | BT
    curvestyle="spline",    # spline | ortho | curved | polyline
    outformat="png",        # png | jpg | svg | pdf | dot (or list)
    show=False,             # ALWAYS False - prevents auto-opening
    strict=False,           # merge duplicate edges
    autolabel=False,        # prefix labels with provider/type
    graph_attr={},          # graphviz graph attributes
    node_attr={},           # graphviz node attributes
    edge_attr={},           # graphviz edge attributes
):
    ...
```

Always set `show=False` so the script runs non-interactively.

### Nodes

Import from `diagrams.<provider>.<category>`:

```python
from diagrams.aws.compute import EC2, Lambda, ECS
from diagrams.aws.database import RDS, Aurora
from diagrams.aws.network import ELB, Route53, CloudFront
from diagrams.k8s.compute import Pod, Deployment
from diagrams.onprem.database import PostgreSQL, MySQL
from diagrams.onprem.network import Nginx
```

See `references/providers.md` for the full provider and category listing with common node names.

### Data flow operators

```python
ELB("lb") >> EC2("web") >> RDS("db")    # left to right
RDS("db") << EC2("web")                  # right to left
RDS("primary") - RDS("replica")           # undirected
ELB("lb") >> [EC2("w1"), EC2("w2")]      # fan-out to list
```

Operator precedence matters: `-` (subtraction) binds more tightly than `>>` / `<<` (bitshift) in Python, so `A >> B - C` parses as `A >> (B - C)`. Wrap in parentheses when mixing: `(A >> B) - C`.

### Clusters

```python
from diagrams import Cluster

with Cluster("VPC"):
    with Cluster("Private Subnet"):
        svc = [ECS("svc1"), ECS("svc2")]
```

Unlimited nesting depth. Clusters accept `graph_attr` for styling (e.g. background colour).

### Edges

```python
from diagrams import Edge

node_a >> Edge(label="HTTPS", color="darkgreen", style="dashed") >> node_b
```

Attributes: `label` (text on the edge), `color` (X11 name or hex), `style` (solid | dashed | dotted | bold).

### Custom nodes

```python
from diagrams.custom import Custom

svc = Custom("My Service", "./icon.png")  # local PNG, ideally 256x256
```

## Key Techniques

- **Direction**: use `TB` for layered/hierarchical diagrams, `LR` for pipelines and flows
- **Transparent background**: `graph_attr={"bgcolor": "transparent"}`
- **Multiple outputs**: `outformat=["png", "svg"]`
- **Reduce edge noise**: import `Node` from `diagrams` and create blank junctions with `Node("", shape="plaintext", width="0", height="0")`, or merge overlapping edges with `graph_attr={"concentrate": "true", "splines": "spline"}`
- **Assign nodes to variables** when they connect to multiple other nodes
- **PEP 723** for standalone scripts so `uv run` handles the dependency automatically:
  ```python
  # /// script
  # dependencies = ["diagrams"]
  # ///
  ```

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

SKILL.md skills catalog →

From the same set73

The whole set →
critical-reviewer The critical-reviewer subagent reviews recent code, documents, plans, or designs and returns prioritised findings. Use it for a fresh critical review before applying fixes yourself. CX Codex ★ 173repo stars quick-researcher quick-researcher pulls facts that are already published on the web and hands each one back with a link to the page it came from. Useful when the answer exists somewhere but hunting it down by hand is slow. CX Codex ★ 173repo stars ambitious-model-use The ambitious-model-use skill reshapes a task before execution. Rather than merely improving the prompt, it examines what outcome you actually need and suggests working with raw data or drawing on adjacent fields. CX Codex +1 ★ 173repo stars demo-recorder demo-recorder drives headless Chromium to record scripted 3K 60fps web app demos, generate narration via Cloney, and dub the final cut. CX Codex +1 ★ 173repo stars liteparse liteparse extracts text and structure from PDF, DOCX, PPTX, XLSX and images to markdown locally, no cloud or LLM required. CX Codex +1 ★ 173repo stars analyse-design The analyse-design skill examines an app, website, or document’s code and screenshots to map its design system. Use it to audit UI consistency or guide new components. CX Codex +1 ★ 173repo stars invokeai-image-gen invokeai-image-gen — a skill for generating images via local InvokeAI API, supporting FLUX.2 Klein, Z-Image Turbo, and SDXL. Auto-detects models and applies appropriate parameters, saves output as PNG. CX Codex +1 ★ 173repo stars qa-to-issues qa-to-issues runs an interactive QA session to turn reported bugs into durable GitHub issues. The agent asks quick clarifying questions, checks your codebase, and files tickets. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open