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
npx skills add sammcj/agentic-coding --skill diagrams-as-code -a claude-codeWhat 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, andRDS, then save it as PNG. - Map requests from
ELBto twoEC2nodes and onward toRDS. - Group services under
VPCandPrivate Subnetand 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-code2Manually: put the files in place
~/.claude/skills/diagrams-as-code/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagrams-as-code/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill diagrams-as-code -a codex2Manually: put the files in place
.agents/skills/diagrams-as-code/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill diagrams-as-code -a cursor2Manually: put the files in place
.cursor/skills/diagrams-as-code/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sammcj/agentic-coding Skills_disabled/diagrams-as-code/SKILL.md2Manually: put the files in place
.github/skills/diagrams-as-code/SKILL.md1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill diagrams-as-code -a gemini-cli2Platform CLI
gemini skills install https://github.com/sammcj/agentic-coding --path Skills_disabled/diagrams-as-codeManually: put the files in place
.devin/skills/diagrams-as-code/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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