*New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.*
27 types. One Claude Code skill. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram.
27 types. One agent skill for Claude Code, Codex, and Pi. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram.
No Figma. No generic rounded boxes. No 30-minute color-picking sessions.
@@ -87,19 +87,13 @@ All 27 diagrams ship in three variants: minimal light, minimal dark, and full-ed
## Install
**Pi:**
```bash
# Clone the repo somewhere, then symlink the inner skill into Claude Code's skills dir
pi install https://github.com/cathrynlavery/diagram-design
```
The real skill lives at`skills/diagram-design/`inside the repo (so the same tree works as a Claude Code plugin, a Codexplugin, and a standalone skill). The symlink points Claude Code at that inner directory.
Restart Claude Code. The skill registers as `diagram-design` and activates whenever you ask Claude to make a diagram.
### Alternative: install as a plugin
Quicker to install — but the skill lives in the plugin cache, so edits to `references/style-guide.md` don't survive plugin updates. Pick this if you just want to try it out; use the clone route above if you plan to customize the style guide by hand.
Run `/reload` in an open Pi session. The skill activates automatically for diagram requests; use`/skill:diagram-design`to invoke it explicitly. Pi also loads the `/export-diagram` prompt template.
**Claude Code:**
@@ -116,6 +110,22 @@ Quicker to install — but the skill lives in the plugin cache, so edits to `ref
Managed installs are convenient, but changes to `references/style-guide.md` may be replaced by package updates. Clone the repo and install the local path if you plan to customize the style guide:
The shared skill lives at `skills/diagram-design/`. Pi discovers it through the repo's standard `skills/` package directory; Claude Code, Codex, and other Agent Skills-compatible tools use the same files.
---
## Onboarding — make it look like *your* brand
@@ -128,7 +138,7 @@ Out of the box, diagrams render in a clean **jet-black + atomic-tangerine** pale
```
You: "onboard diagram-design to https://yoursite.com"
Claude: → fetches the homepage
Agent: → fetches the homepage
→ extracts the dominant palette + font stack
→ maps detected values to semantic roles:
paper, ink, muted, accent, link
@@ -173,29 +183,40 @@ See [`skills/diagram-design/references/onboarding.md`](skills/diagram-design/ref
## Quickstart
```bash
# Open the gallery to see all 27 diagrams
open ~/.claude/skills/diagram-design/assets/index.html
# From a cloned checkout, open the gallery to see all 27 diagrams
open skills/diagram-design/assets/index.html# macOS
xdg-open skills/diagram-design/assets/index.html # Linux
# In Claude Code, just ask:
# In Claude Code, Codex, or Pi, ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
# see assets/example-sequence-oauth.html — not a full authorize-code handshake)
# see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)
```
Claude will pick the right type, build the HTML, and save it. You can also start from a template directly:
Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:
@@ -219,42 +240,46 @@ Both formats are diagram-only — editorial cards and headers from `-full` varia
## Architecture
Progressive disclosure. `SKILL.md` is a lean index — it tells Claude how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant.
Progressive disclosure. `SKILL.md` is a lean index — it tells the agent how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant.
│ ├── references/ — loaded only when a type or primitive is chosen
│ │ ├── style-guide.md — single source of truth for colors + fonts
│ │ ├── onboarding.md — the URL-to-tokens flow
│ │ ├── type-architecture.md
│ │ ├── type-flowchart.md
│ │ ├── type-sequence.md
│ │ ├── type-state.md
│ │ ├── type-er.md
│ │ ├── type-timeline.md
│ │ ├── type-swimlane.md
│ │ ├── type-quadrant.md
│ │ ├── type-nested.md
│ │ ├── type-tree.md
│ │├── type-org-chart.md
│ │ ├── type-layers.md
│ │├── type-venn.md
│ │ ├── type-pyramid.md
│ │ ├── primitive-annotation.md
│ │├── primitive-sketchy.md
│ │└── primitive-terminal.md
│ └── assets/
│ ├── index.html — live gallery, tabbed
│ ├── template*.html — scaffolds for new diagrams
│ ├── example-<type>.html — 3 variants × 27 types
│ ├── example-loop-terminal.html
│ ├── example-quadrant-consultant.html
│ └── example-sequence-oauth*.html
└── docs/screenshots/ — images used in this README
```
This keeps Claude's working context tight (only load what you need) and makes the skill easy to extend — drop a new `type-<name>.md` and wire it into the selection guide. The skill ships with 34 reference files covering every diagram type, primitive, and utility.
This keeps the agent's working context tight (only load what you need) and makes the skill easy to extend — drop a new `type-<name>.md` and wire it into the selection guide. The skill ships with 34 reference files covering every diagram type, primitive, and utility.
### Contributing / skin lint
@@ -265,7 +290,7 @@ The repository-wide check `python3 scripts/lint-skin.py --all --baseline` must s
The top-level `SKILL.md` is always in context. Everything else is pulled in only when relevant — this is what keeps the skill fast even with 34 reference files.
| You ask for… | Claude loads |
| You ask for… | Agent loads |
|---|---|
| "Make me a flowchart" | `SKILL.md` + `references/type-flowchart.md` |
| "Build an architecture diagram" | `SKILL.md` + `references/type-architecture.md` |
@@ -275,7 +300,7 @@ The top-level `SKILL.md` is always in context. Everything else is pulled in only
| "Give me a terminal / CLI-window version" | `SKILL.md` + `references/primitive-terminal.md` |
| Routine diagram-making (any of the 27 diagrams) | Only `SKILL.md` + that one type's reference |
No matter how many types exist, Claude only reads the one you need. Add a new type tomorrow and nothing else changes.
No matter how many types exist, the agent only reads the one you need. Add a new type tomorrow and nothing else changes.
Export diagram HTML at `$1` to `.svg` or `.png`, following `skills/diagram-design/references/export.md` from installed diagram-design package. Read that reference first; treat it as source of truth.
Full argument string: `$ARGUMENTS`
## Defaults
- Produce both `.svg` and `.png` next to source (for example, `diagram.html` → `diagram.svg` + `diagram.png`).
- Render PNG at `device_scale_factor=2`.
## Flags
-`--svg-only` — emit SVG only. Skip Playwright.
-`--png-only` — emit PNG only.
-`--scale=1`, `--scale=2`, or `--scale=3` — override PNG device scale factor.
-`--output=<path>` — override output base path; append format extension.
## Required behavior
1. No source path → ask user which `.html` file to export. Do not guess.
2. Source is `assets/index.html` → refuse; ask for specific diagram file.
3. Source lacks `<svg>` → refuse; write nothing.
4. PNG requested without Playwright → show install instruction from reference verbatim; stop. Do not auto-install.
Three source methods are supported. Jump to the relevant section:
- [§ URL](#url) — fetch a live website
- [§ Skill](#skill) — read an installed Claude Code skill that carries design tokens
- [§ Skill](#skill) — read an installed Agent Skill that carries design tokens
- [§ Folder](#folder) — read a local design-system directory (CSS, JSON, Markdown)
---
@@ -128,7 +128,7 @@ Write the new tokens to `style-guide.md`. Suggest running the `/regenerate-examp
After onboarding, the user should:
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 26 types.
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 27 types.
2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
---
@@ -144,7 +144,7 @@ After onboarding, the user should:
## § Skill
Extract tokens from an installed Claude Code skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill).
Extract tokens from an installed Agent Skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill).
### Invocation
@@ -154,13 +154,20 @@ Or the gate offers this as option (b) and the user names the skill.
### Step 1 — locate the skill
Search for the skill in order:
Use the installed-skill location exposed by the current agent when available. Otherwise search locations for the active harness:
**Pi:**
1.`~/.pi/agent/skills/<skill-name>/` and `~/.agents/skills/<skill-name>/` (user installs)
2.`.pi/skills/<skill-name>/` and `.agents/skills/<skill-name>/` from the current directory through the repo root (project installs)
3. Package paths listed in `~/.pi/agent/settings.json` or `.pi/settings.json`; managed packages live under `~/.pi/agent/git/`, `~/.pi/agent/npm/`, `.pi/git/`, or `.pi/npm/`
If not found, ask the user to confirm the skill name or provide the path.
Finally, check any path the user provides explicitly. If the skill is still not found, ask the user to confirm the name or provide its path.
### Step 2 — read token sources
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Daan Balm