diff --git a/README.md b/README.md index 3cc29a5..c647cba 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ *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 -git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design -ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design +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 Codex plugin, 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 npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design ``` +### Editable install + +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: + +```bash +git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design + +# Pi: register the checkout as a local package +pi install ~/code/diagram-design + +# Claude Code: symlink the inner skill +ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design +``` + +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: ```bash -cp assets/template.html my-diagram.html # minimal light -cp assets/template-full.html my-diagram.html # editorial with summary cards +cp skills/diagram-design/assets/template.html my-diagram.html # minimal light +cp skills/diagram-design/assets/template-full.html my-diagram.html # editorial with summary cards ``` --- ## Export to PNG / SVG -Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command: +Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent: + +**Pi:** + +``` +/export-diagram path/to/diagram.html +/export-diagram path/to/diagram.html --svg-only +/export-diagram path/to/diagram.html --png-only --scale=3 +``` + +**Claude Code:** ``` /diagram-design:export path/to/diagram.html @@ -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. ``` diagram-design/ -├── SKILL.md — top-level: philosophy, selection guide, checklist -├── 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 — italic-serif editorial callouts -│ ├── primitive-sketchy.md — hand-drawn SVG filter variant -│ └── primitive-terminal.md — charcoal-black CLI-window variant -├── assets/ -│ ├── index.html — live gallery, tabbed -│ ├── template*.html — scaffolds for new diagrams -│ ├── example-.html — 3 variants × 27 types -│ ├── example-loop-terminal.html — terminal-variant flagship -│ ├── example-quadrant-consultant.html — consultant-special 2×2 scenario matrix -│ └── example-sequence-oauth*.html — sequence special: bearer + ALT refresh -└── docs/screenshots/ — the images in this README +├── prompts/ +│ └── export-diagram.md — Pi `/export-diagram` prompt template +├── skills/ +│ └── diagram-design/ +│ ├── SKILL.md — philosophy, selection guide, checklist +│ ├── 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-.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-.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-.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. --- diff --git a/prompts/export-diagram.md b/prompts/export-diagram.md new file mode 100644 index 0000000..1a19dc1 --- /dev/null +++ b/prompts/export-diagram.md @@ -0,0 +1,30 @@ +--- +description: Export a diagram-design HTML file to SVG and PNG +argument-hint: " [--svg-only|--png-only] [--scale=N] [--output=]" +--- + +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=` — 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 `` → refuse; write nothing. +4. PNG requested without Playwright → show install instruction from reference verbatim; stop. Do not auto-install. +5. `--scale` outside {1, 2, 3} → reject. + +After export, report output paths plus sizes. diff --git a/skills/diagram-design/SKILL.md b/skills/diagram-design/SKILL.md index dd05090..cf10009 100644 --- a/skills/diagram-design/SKILL.md +++ b/skills/diagram-design/SKILL.md @@ -192,7 +192,7 @@ Universal building blocks. Type-specialized primitives (lifeline, activation bar - Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md) - Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md) -- Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](../assets/icons.html). +- Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](assets/icons.html). - Terminal / CLI-window variant → [primitive-terminal.md](references/primitive-terminal.md) ### Background diff --git a/skills/diagram-design/references/onboarding.md b/skills/diagram-design/references/onboarding.md index 26da199..3a8ae61 100644 --- a/skills/diagram-design/references/onboarding.md +++ b/skills/diagram-design/references/onboarding.md @@ -7,7 +7,7 @@ Takes about 60 seconds. 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//` and `~/.agents/skills//` (user installs) +2. `.pi/skills//` and `.agents/skills//` 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/` + +**Claude Code:** 1. `~/.claude/skills//` (user install) 2. `.claude/skills//` (project install) -3. Any path the user provides explicitly -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