@feimacode/open-design-agent-kit 0.3.0-beta.3 → 0.4.0-beta.1

package/assets/codex-skills/open-design/SKILL.md

@@ -13,33 +13,69 @@ A small, curated subset of skills/templates also has its own explicit `/open-des
 
 All Open Design content (skill/template text, design system tokens, example briefs) is delivered to you as plain text through the MCP tool calls below — never as a file path. You never need to, and should not, browse or search for Open Design's own files anywhere on disk; `list_open_design_skills` and `prepare_open_design_brief` already return everything you need as plain text.
 
+<!-- voice:start -->
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+<!-- voice:end -->
+
 Follow this flow:
 
 0. **Check the tools are wired up.** This skill does nothing on its own — every step below calls a tool the `open-design` MCP server provides. If `list_open_design_skills` (or any other tool named below) isn't available to you right now, the server hasn't been registered in this project yet. Set it up, then retry from step 1:
    - **Claude Code:** run `npx @feimacode/open-design-agent-kit init --tools claude` in the project root, or `claude mcp add open-design -- npx -y @feimacode/open-design-agent-kit-mcp`.
    - **Codex CLI:** run `npx @feimacode/open-design-agent-kit init --tools codex` in the project root.
    - **Any other MCP-capable agent** (Cursor, etc.): register `npx -y @feimacode/open-design-agent-kit-mcp` as a stdio MCP server using this agent's own MCP config mechanism.
-   - **Claude Desktop Chat or claude.ai** (no Open Design tools in the chat): don't make anything yet. Tell the user what's missing: connect a folder to the chat (Claude Desktop, with the Open Design plugin installed), or install the Open Design desktop extension (`open-design-<version>.mcpb` from the project's GitHub releases) to use it in Claude Desktop without a folder. Only if they want to go ahead anyway, make one self-contained HTML page and publish it with your own Artifact tool, and say it skips Open Design's design systems, checks and exports.
+   - **Claude Desktop Chat or claude.ai** (no Open Design tools in the chat): don't make anything yet. Welcome the user in plain words, in this shape:
+     > Open Design can't save or check designs in this chat yet. Two ways to fix that:
+     > 1. **Connect a folder:** make a folder called "Open Design" (in Documents, for example), then click **+** in this chat, choose **Add folder** and pick it.
+     > 2. **Install the Open Design extension for Claude Desktop:** download it from https://github.com/feimacode/open-design-agent-kit/releases/latest, double-click the file, then start a new chat.
+     >
+     > What's the design for?
+
+     Don't name file types, packages, commands or tools in it. Offer the goals from step 1 below as examples of what they can say ("promote an event", "show an idea", "get hired"). Only if they want to go ahead without either, make one self-contained HTML page and publish it with your own Artifact tool, and say it can't use saved styles, checks or saving as PDF and images.
 
    Run the command yourself if you have shell access; otherwise tell the user the exact command to run and wait for their confirmation before continuing. Skip this step entirely once the tools are available.
 
-   **In Claude Desktop** (a chat or Cowork session with a folder the user connected), the server runs on the user's machine and starts in their home folder, and your file tools see the folder under a different path. Before any other Open Design tool, call `set_open_design_workspace` with the folder's path on the user's machine (the one `get_device_info` lists under `connectedFolders`). Every path other tools return is relative to that folder: join it onto your own path for the folder when you read or write files. If a tool says it would be working in the home folder, this is what it's asking for.
+   **In Claude Desktop** (a chat or Cowork session with a folder the user connected), the server runs on the user's machine and starts in their home folder, and your file tools see the folder under a different path. Before any other Open Design tool, call `set_open_design_workspace` with the folder's path on the user's machine (the one `get_device_info` lists under `connectedFolders`). Every path other tools return is relative to that folder: join it onto your own path for the folder when you read or write files, and when you attach or show a file with your own tools, give the full path: a relative one resolves against your shell's current folder, which moves when you `cd`. If a tool says it would be working in the home folder, this is what it's asking for. The first time you set the folder in a chat, tell the user in one sentence where their designs will be saved (the folder's name and the `Open Design` folder inside it) and that they can open it any time; don't repeat it for later designs.
 
-   **In Claude Desktop Chat with no folder** (`use_open_design_managed_workspace` is in your tools), your own file tools, if you have any, can't reach the server's files. Call `use_open_design_managed_workspace` first with a short name for the design, and tell the user the folder's absolute path from its result (under `~/Open Design/` by default), so they can open it. Then save every design file with `write_open_design_file` (the whole file each time, under the output directory) instead of your own file tools, and register, check and export as usual. Show the design with `show_open_design_artifact` after each round; don't keep a per-round Claude artifact preview here. The managed folder is the source of truth: to edit, send the full new file through `write_open_design_file`. If the chat has a connected folder, use `set_open_design_workspace` instead.
+   **In Claude Desktop Chat with no folder** (`use_open_design_managed_workspace` is in your tools), your own file tools, if you have any, can't reach the server's files. Call `use_open_design_managed_workspace` first with a short name for the design, and tell the user once, in one sentence, the folder's absolute path from its result (under `~/Documents/Open Design/` by default), so they can open it. Then save every design file with `write_open_design_file` (the whole file each time, under the output directory) instead of your own file tools, and register, check and export as usual. Show the design with `show_open_design_artifact` once; later rounds update that inline copy by itself. Don't keep a per-round Claude artifact preview here. The managed folder is the source of truth: to edit, send the full new file through `write_open_design_file`. If the chat has a connected folder, use `set_open_design_workspace` instead.
 1. Call `list_open_design_skills` (optionally with a `query` and/or an exact `mode`) to find a skill or design template that matches what the user wants. Pick the best match by name/description/triggers, and prefer a result's `examplePrompt` (adapted to the user's specifics) over inventing your own brief when one is present and closely fits.
-2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. For **phone screens** (the Mobile app surface, or a brief like "a budgeting app that feels like Monzo"), look in the `Mobile Apps` category first, with the app's name as `query`: those systems are adapted from the real iOS apps (tab bars, sheets, iOS point sizes). Use `<app>-ios` (e.g. `spotify-ios`) for phone screens even when a web system of the same brand exists (`spotify`); the web one stays the right choice for web pages. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
+2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. For **phone screens** (the Mobile app surface, or a brief like "a budgeting app that feels like Monzo"), look in the `Mobile Apps` category first, with the app's name as `query`: those systems are adapted from the real iOS apps (tab bars, sheets, iOS point sizes). Use `<app>-ios` (e.g. `spotify-ios`) for phone screens even when a web system of the same brand exists (`spotify`); the web one stays the right choice for web pages. If the user hasn't mentioned any direction and one is active, just omit `designSystemId` from `prepare_open_design_brief` and it will use the active one. **If none is active and the user hasn't named a direction, recommend one** before preparing a new design (not for an edit, a remix or an export): call `recommend_open_design_design_systems` with what you know from the request, the conversation and the workspace (`industries`, `moods`, `theme`, `surface`, `likeBrands`, `brief`), leaving out what you don't know. If its result has `questions`, ask them once, as short multiple-choice options: through `show_open_design_questions` where it is in your tools, else in one message (or your host's question tool if it has one), and accept "you pick"; then call it again with the answers. Ask them in the same message as any surface questions, three in total at most. Show the shortlist: where `show_open_design_design_systems` is in your tools, pass it the recommended `ids`; elsewhere, a short numbered list with each name and its `reason`. Don't wait for a pick unless you asked questions: go ahead with the first recommendation, pass its id to `prepare_open_design_brief`, and say which style you used and that they can pick another. If `recommend_open_design_design_systems` isn't in your tools, use `list_open_design_design_systems` instead, or go without one. Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
 3. Call `prepare_open_design_brief` with the chosen `skillId`, optional `designSystemId` (per step 2), and the user's `brief` (their request, in their own words). This returns `instructions` to follow, a `suggestedEntryPath`, and the `designSystemId`/`designSystemName` actually used (whether explicit or defaulted from active) — mention which one it was if it wasn't obvious from the conversation. It does NOT write any files.
 4. Follow the returned `instructions` and author the artifact's entry file (plus any supporting files) yourself, using your own file-editing tools. Do not look for a separate tool to write the design content.
 5. Call `register_open_design_artifact` with the entry path, a `kind`, a `title`, and any `supportingFiles`, so the artifact is recognized and gets its manifest sidecar written.
-6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. **3D designs are the exception:** when the check returns a 3D review sheet, a clean check isn't the end. Get the critique the check result asks for (the `3d-object` skill's scorecard, from a subagent where your host has one), then fix, re-check and re-critique for up to three critique rounds, which replace the two-fix-round limit. Don't describe the screenshots to the user unless they ask: each run's screenshots are saved for them, and the browser preview's Checks panel shows them before and after (the result also lists the saved paths). If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
+6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Taste warnings (`slop-glow`, `card-row`, `uniform-surface`, `type-scale`, `intent`) are worth a look: fix them unless the brief or the design system asks for that look, and never add `data-od-allow` only to silence one. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. **Then get a second look** before you call it done: once the checks are clean or the fix rounds are spent, run the `open-design-critique` skill, which has a fresh critic judge the latest check run against the brief and the design system on purpose and hierarchy, typography, colour and contrast, layout and rhythm, copy, states, and fit, so build with those in mind. One critique round: on `polish`, apply its fixes once, register and re-check, then report done without another critique; on `rework`, tell the user what's wrong and ask before rebuilding; on `ship`, it's done. The brief or design system wins over a finding against a look it asks for, and the user can ask for another opinion at any time or say they don't want one. **3D designs are the exception:** when the check returns a 3D review sheet, a clean check isn't the end. Get the critique the check result asks for (the `3d-object` skill's scorecard, from a subagent where your host has one), then fix, re-check and re-critique for up to three critique rounds, which replace the two-fix-round limit and the second look above. Don't describe the screenshots to the user unless they ask: each run's screenshots are saved for them, and the browser preview's Checks panel shows them before and after (the result also lists the saved paths). If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
 7. Optionally call `get_open_design_artifact` to confirm what was written before telling the user it's done.
 8. After the first artifact you register in a session, call `open_open_design_preview` with its entry path, unless the user said they don't want it, so they can see it. It opens a live browser preview that reloads whenever the file changes, so don't call it again after edits; call it again only to switch to another artifact. Mention that they can click **Comment** in the preview to leave comments on elements.
 
-   **In Claude Desktop Chat** (a chat conversation, not the Code tab or a terminal), call `show_open_design_artifact` with the entry path instead: it shows the design inline in the conversation, where the user can comment and click **Ask Claude to apply**. Call it after every `register_open_design_artifact`, including after applying comments, since the inline page doesn't reload by itself. If its result says the host doesn't show MCP Apps, fall back to `open_open_design_preview` as above. Its export buttons post a request in the chat: run `export_open_design_artifact` with the format named and tell the user the path. For an exploration, pass `explorationId` to show the directions side by side; when the user picks one with **Take this one**, ask which next step they want before calling `choose_open_design_direction`. A style-tile exploration also offers **Use as design system**, which asks directly for `choose_open_design_direction` with `next: "save-design-system"`.
+   **In Claude Desktop's Code tab** (its preview tool, named like `preview_start`, is in your tools), use the Browser pane instead of a separate window: the first time you show a design in the session, call `set_up_open_design_browser_pane` (once per project; tell the user once, in one sentence, that you added a preview entry to `.claude/launch.json`), then start the `open-design-preview` configuration it names with that preview tool. The pane opens on the newest registered design and reloads when its files change. For a later design, reload the pane if your preview tools can, or tell the user it's in the pane's list. If the pane can't start, fall back to `open_open_design_preview`.
+
+   **In Claude Desktop Chat** (a chat conversation, not the Code tab or a terminal), call `show_open_design_artifact` with the entry path instead: it shows the design inline in the conversation, where the user can comment and click **Ask Claude to apply**. Call it once per design, after its first `register_open_design_artifact`: that copy follows later edits and applied comments by itself, so don't show the same design again unless the user asks. The register result says which applies. If its result says the host doesn't show MCP Apps, fall back to `open_open_design_preview` as above. Its export buttons post a request in the chat: run `export_open_design_artifact` with the format named and tell the user the path. For an exploration, pass `explorationId` to show the directions side by side; when the user picks one with **Take this one**, ask which next step they want before calling `choose_open_design_direction`. A style-tile exploration also offers **Use as design system**, which asks directly for `choose_open_design_direction` with `next: "save-design-system"`.
 
    **Picking by eye in Claude Desktop Chat.** Two more tools are listed only where the host shows MCP Apps inline, so use them only when they are in your tool list: `show_open_design_examples` shows the remixable examples as a gallery of live previews (filter by `query`, `mode` or `surface`), and `show_open_design_design_systems` shows design systems as tiles (pass `ids` for a shortlist). Use them when the user wants to choose a starting example or a brand look and hasn't named one. Picks arrive as chat messages naming the tool to call: "Remix this" means `remix_open_design_example` with that skillId (ask what to make first if the user hasn't said); "Use this design system" means `set_active_design_system` with that id. Elsewhere, keep to `list_open_design_skills` and `list_open_design_design_systems`.
 
-When a request names a **kind of thing to make** (a prototype or landing page, mobile app, slides, document, wireframe, animation, résumé, research synthesis, data report, poster or flier, social post, diagram, 3D object), call `list_open_design_skills` with `surface` set to that kind first (`surface: "list"` shows the ids). Pick from its entries, ask only the surface's questions the request doesn't answer, and follow the surface's prompt when it names one. A request for one specific template or style still goes straight to it. Never pick an entry marked `stub: true`: it only advertises an upstream skill and has no instructions here.
+   **Linking the public gallery.** Some results carry a link to the Open Design gallery, a website with every example and design system: `gallery.url` from `show_open_design_examples` and `show_open_design_design_systems`, and `designSystem.galleryUrl` from `register_open_design_artifact`. They appear only while the gallery is live; never write a gallery link yourself. When the user is **browsing** (wants to look before deciding: "show me some examples", "what styles are there?", "ideas for a café menu"), show the in-chat gallery where it is in your tools, then add one line linking `gallery.url` ("See them all in the [Open Design gallery](…)."), unless you already linked the gallery in this conversation. When a design is **ready** and its register result has `designSystem.galleryUrl`, name the design system with that link in the sentence that says it's ready ("It uses the [Kami](…) design system."), the first time you use that design system in the conversation; not again for later rounds or designs in the same style. Never link the gallery before building on a **concrete** request ("a poster for our seed swap on Saturday"), after an export or publish, or in a recurring job run.
+
+   **Asking with taps in Claude Desktop Chat.** `show_open_design_questions` is listed only where the host shows MCP Apps inline. Where it is in your tool list, ask every short multiple-choice question through it instead of a chat message: the surface and design-system questions before a build, which direction after an exploration, "fix these?" after a review. Up to four questions, each with a short `id`, `text`, a `kind` (`single`, `multi` or `text`) and up to eight `options`; an option can carry `imageRef` (`designSystem:<id>`, `example:<skillId>`, `artifact:<entryPath>` or `checkRun:<entryPath>`), never a URL. Don't repeat the questions in chat. The answer arrives as a message starting "Answers:" with a line `<!-- od-answers {...} -->`: read that JSON (question id to option id, an array for `multi`, typed text, or `you-pick`, meaning choose for them and say what you chose). Accept typed answers too. The artifact view also has three quick replies under the design ("Looks good", "Change something", "Try another direction"); each posts a message saying what to do next. Elsewhere, ask in one chat message.
+
+When a request says **what the design is for but not what to make** ("help me promote our seed swap", "something to get a UX job"), or is too vague to tell, call `list_open_design_skills` with `surface: "list"`: its `goals` are plain-language aims (Promote an event, Show an idea, Get hired…). Take the goal that fits, or show the goals (label and description) and ask one question, "What's it for?". Then call it with `goal` set to that id and continue with the surface marked `default`, asking which one only when the request doesn't settle it and the goal leads to several. Don't show the user the list of surfaces unless they ask what kinds of thing you can make.
+
+When a request names a **kind of thing to make** (a prototype or landing page, mobile app, slides, document, wireframe, animation, résumé, research synthesis, data report, poster or flier, social post, diagram, 3D object), call `list_open_design_skills` with `surface` set to that kind first (`surface: "list"` shows the ids). Pick from its entries and follow the surface's prompt when it names one. **Questions:** a surface lists a few `questions`, each with `options`, a `default` and what the answer `changes`. Ask only the ones the request, the conversation and the workspace don't already answer: at most three in total, merged with any design-system recommender questions (surface ones first), in one message, as multiple choice, accepting "you pick" (then use the question's `default`). A request that already says enough gets no questions. Pass the answers to `prepare_open_design_brief` as `answers` (question id to answer) and what you decided without asking as `assumptions` (up to six short lines), then pass both, with the request in one line as `text`, to `register_open_design_artifact` as `brief`. When the design is ready, list the assumptions in one sentence and invite a change ("I assumed a dark theme and one sign-up button; say if you want otherwise"). A request for one specific template or style still goes straight to it. Never pick an entry marked `stub: true`: it only advertises an upstream skill and has no instructions here.
 
 For **engineering documents** (an RFC, ADR, postmortem, PR explainer or changelog page), use the matching skill (`od:prototype:rfc`, `adr`, `postmortem`, `pr-explainer`, `changelog-page`). Gather the facts yourself first, from git (`git log`, `git diff`, `gh pr view` when available) and the files involved, and register what you read as `sources`. Never invent incident facts, dates or numbers: ask for them. To turn a **folder of Markdown docs** into pages, follow the docs flow (load the `open-design-docs` skill): one page per file, one template for the set, and on a re-run only the pages whose Markdown changed.
 
@@ -53,19 +89,21 @@ If the user explicitly asks for **options to compare** ("show me three direction
 1. Call `prepare_open_design_exploration` with the `skillId` and the user's `brief` (and `count` 2–4 if they gave a number; default 3). The tool picks deliberately different directions itself: visual styles when no design system is active, layout/narrative structures when one is (so the brand is kept), or pass `axis: "custom"` with `customDirections` when the user named what should vary ("three hero concepts"). Pass `directionIds` only when the brief's tone clearly calls for specific ones (e.g. `editorial-monocle` for a magazine, `brutalist-experimental` for an art or agency site). If the result says the active design system was set aside, tell the user.
 2. For each returned direction, follow `sharedInstructions` followed by that direction's own `instructions`, write its file at its `suggestedEntryPath`, and call `register_open_design_artifact` with the `explorationId` and that direction's `directionId`. Directions are quick **sketches** (one screen, or a cover plus two slides), not full builds. If you can delegate work to sub-agents, generate the directions in parallel, passing each one `sharedInstructions` plus its own `instructions`.
 3. Call `compare_open_design_exploration` with `contactSheet: true`. If you can view images, open the contact sheet and check the directions really look different (layout and hero pattern, not just colour); regenerate any that resembles another.
-4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, each on its own line, briefly describe how each direction differs, and ask which one to take forward.
+4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, each on its own line, briefly describe how each direction differs, and ask which one to take forward (through `show_open_design_questions` where it is in your tools, with each direction as an option and `imageRef: "artifact:<its entry path>"`).
 5. When the user picks one, call `choose_open_design_direction` with `next`: `build-out` (build the chosen sketch out at full fidelity), `merge` (the same, taking named aspects from other directions via `mergeFrom`, e.g. "B with A's hero"), or `save-design-system` (turn the direction into a reusable custom design system). Follow the returned `instructions` and register the result as they say.
 
 Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. After registering or updating an artifact, tell the user where it was written, with its workspace-relative entry path (e.g. `.open-design/coffee-poster/coffee-poster.html`) on its own line: in Claude Desktop's Code tab, clicking that path opens it in the Browser pane. Don't open the HTML file in a browser yourself: `open_open_design_preview` (or `show_open_design_artifact` in Claude Desktop Chat) is how it is shown.
 
-**Comments from the preview.** When the user says they left comments (or pastes the preview's "Apply my comments" instruction, or the inline preview posts it), call `get_open_design_artifact` for that entry. Its `openComments` lists each comment's note and the element it points at (`selector`, `text`, `htmlHint`, `rect`); screenshots of up to 4 commented elements are attached as images, and every comment's `screenshot` path is listed. Change only those elements, with your own file-editing tools, then call `register_open_design_artifact` again with the comments' ids as `resolvedCommentIds` so their pins leave the preview, and run the check as in step 6. In Claude Desktop Chat, then call `show_open_design_artifact` again so the user sees the result.
+**Comments from the preview.** When the user says they left comments (or pastes the preview's "Apply my comments" instruction, or the inline preview posts it), call `get_open_design_artifact` for that entry. Its `openComments` lists each comment's note and the element it points at (`selector`, `text`, `htmlHint`, `rect`); screenshots of up to 4 commented elements are attached as images, and every comment's `screenshot` path is listed. Change only those elements, with your own file-editing tools, then call `register_open_design_artifact` again with the comments' ids as `resolvedCommentIds` so their pins leave the preview, and run the check as in step 6. In Claude Desktop Chat, the inline copy updates by itself; tell the user it's updated rather than showing it again.
 
-If the user wants to start from or riff on an existing example rather than build something new, prefer `remix_open_design_example` (skillId must have a non-empty `exampleArtifactPath`) over `prepare_open_design_brief` — it copies a working starting artifact into the project and tells you to modify it rather than regenerate from scratch. See [references/remixable-examples.md](references/remixable-examples.md) for the full list of what's available to remix, grouped by mode — check it before calling `list_open_design_skills` with `remixableOnly: true` if a quick skim already answers the question.
+If the user wants to start from or riff on an existing example rather than build something new, prefer `remix_open_design_example` (skillId must be an entry with `remixable: true`) over `prepare_open_design_brief` — it copies a working starting artifact into the project and tells you to modify it rather than regenerate from scratch. See [references/remixable-examples.md](references/remixable-examples.md) for the full list of what's available to remix, grouped by mode — check it before calling `list_open_design_skills` with `remixableOnly: true` if a quick skim already answers the question.
 
 If the user wants a brand/style that isn't one of the ~150 bundled design systems ("use our own brand colors", "match our website", "set up a custom design system for..."), call `create_open_design_design_system` with a `name`, a `brief` describing the brand, and an optional `sourceUrl` if they gave you a website to match. It returns `instructions` for writing a new `DESIGN.md` yourself (same file shape as every bundled design system) plus, when a `sourceUrl` was given, a best-effort extracted starting palette/font list to incorporate — treat that as a rough starting point, not ground truth. It does NOT write any files. After writing the file, call `set_active_design_system` with the returned `id` — there's no separate "register" step for design systems; a written `DESIGN.md` is immediately selectable, the same way generated artifacts are immediately visible once written.
 
 Once the user is happy with a generated or refined artifact and wants it turned into real, working code in this app ("turn this into a real component", "add this to the app", "wire this into my codebase"), call `port_open_design_artifact_to_app` with the artifact's `entryPath`. It returns `instructions` for reproducing the artifact's design as idiomatic code in this project's actual application — read the returned instructions carefully: they'll tell you to find and follow a real existing component in this codebase as your pattern reference (its styling approach, conventions, file organization) rather than copying the artifact's HTML/CSS verbatim, and to leave routing/navigation wiring as a separate step for the user. It does NOT write any files itself.
 
+When the user wants reusable components rather than one page in the app ("make Material 3 components for my React app from this", "a component library from this design", "an MUI / shadcn set for these screens"), call `prepare_open_design_component_library` instead, with the artifact's `entryPaths` (or the `collectionId` for every screen) and `library` `mui`, `shadcn` or `auto`. Follow its stages in order: write the `components.md` inventory and **stop for the user's yes** before any code, use the generated theme as is, wrap the library's own components, add the gallery, run the app's type check, then call the tool again with `record`. It writes no app code itself. "Material 3" means `mui`.
+
 When the artifact is meant to be posted or uploaded as an image (an X/Twitter post, Instagram or LinkedIn image, Xiaohongshu cards, a YouTube thumbnail, a poster), call `export_open_design_artifact` with its `entryPath` after registering it. It renders the artifact in a headless browser and writes PNG/JPEG file(s) under the artifact's own `exports/` folder, sized from the source skill automatically unless you pass `width`/`height`. For multi-card designs, give each card a `data-od-card` attribute and pass `selector: "[data-od-card]"` to get one numbered image per card. Pass `maxBytes` with the platform's upload limit (X 5000000, YouTube thumbnail 2000000, Instagram 8000000). Tell the user the exported file paths. For any social-post request ("make an X post…", "an Instagram carousel…", "a YouTube thumbnail…"), load the `open-design-social-post` skill first. It maps each platform and format to the right canvas size, skillId and export arguments (and asks the user which platform when that's unclear), then walks through generate → register → export. Animated designs (motion frames, title cards, animated charts, sprite or WebGL animations) export as video or GIF: call `export_open_design_artifact` with `format: "mp4"`, `"webm"` or `"gif"`. Time runs on a virtual clock, so the frames are exact and the same on every run; the length comes from the page (`data-duration` frames or the longest animation) unless you pass `duration`. Before exporting, call `check_open_design_artifact` with `at` (e.g. `[0, 1.5, 3]`) to see the start, middle and end. Export needs an installed ffmpeg: if it reports `no-ffmpeg` or `ffmpeg-missing-encoder`, tell the user what to install rather than trying another way. Compositions built with the HyperFrames framework are the exception: the brief's own instructions render them with the HyperFrames CLI. After registering a slide deck, offer to export it as PowerPoint or PDF, and when the user wants that, call `export_open_design_artifact` with `format: "pptx"` or `"pdf"` (one full-bleed image per slide; not editable text). `format: "pdf"` on an ordinary page prints it as a vector PDF.
 
 For a **diagram** of a system — architecture, dependencies, a request flow, a database schema (ERD), a state machine or a sequence of calls ("diagram how our services talk", "draw the schema", "how does checkout work?") — use the `diagram` skill (`od:prototype:diagram`, or remix its example `od:prototype:diagram:example`). Read the relevant code first and draw only what you read. Write nodes with `data-rank`/`data-lane` and hidden links, never coordinates, then call `add_open_design_diagram_runtime` (it inserts the layout runtime; never write that script yourself), register with kind `diagram` and the files you read as `sources`, and check it. When a later check or `get_open_design_artifact` reports that its sources changed, offer to redraw it.

package/assets/codex-skills/open-design-campaign/SKILL.md

@@ -9,6 +9,25 @@ Build a campaign with Open Design: one message, one visual system, every channel
 
 Brief: the rest of the user's message (if there is none, ask the user: "What is the campaign for, which channels, and which languages?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Agree the copy deck
 
 Before designing anything, agree the words with the user. Draft them from the brief and show them as a short table:

package/assets/codex-skills/open-design-critique/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: open-design-critique
+description: Get a second opinion on an Open Design artifact from a design critic, judged from its latest check screenshots, the brief and the design system against a fixed rubric, with one verdict (ship, polish or rework) and at most five fixes — use before telling the user a design is done (the open-design skill's check step), and whenever the user asks for a second opinion, another opinion, a critique or a review of an Open Design artifact, or asks "is this good?"
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Get a design critic's second opinion on one Open Design artifact.
+
+Request: the rest of the user's message (if there is none, ask the user: "Which design should get a second opinion?")
+
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
+## 1. Find the artifact
+
+Use the artifact the request names; if it names none, use the one you made or changed most recently in this conversation. Registered artifacts are the files under the Open Design output folder (default `.open-design/`) that have a `.artifact.json` file next to them. If it isn't registered yet, register it first with `register_open_design_artifact`.
+
+## 2. Gather what the critic sees
+
+Call `get_open_design_artifact` with its `entryPath` and `critique: true`. The result's `critiqueInput` holds the recorded brief (or, when there is none, the title and skill id), the design system's `DESIGN.md`, the latest saved check run's findings (including any taste and state findings) and its screenshot paths, and the last critique. The run's screenshots are attached.
+
+If it says there is no saved check run, call `check_open_design_artifact` for the artifact first, fix any **error** it reports, then ask for the critique input again.
+
+## 3. Get the critique
+
+The critic judges only what is in `critiqueInput` and the screenshots, never what the builder meant. Pick the first of these your host has:
+
+- **The `design-critic` agent** (Claude Code with the Open Design plugin; it may be listed as `open-design:design-critic`). Start it with the entry path, the `critiqueInput` JSON exactly as returned, and the screenshot and entry file paths written as full paths your own file tools can read. Add nothing about what you intended or what the user said beyond the recorded brief. It reads, it never edits.
+- **A general subagent tool** (the Agent tool in Claude Code, `runSubagent` in VS Code). Give it the same material plus the rubric and output format below, and tell it not to edit any file.
+- **Neither: run it yourself, inline.** Judge the attached screenshots against the rubric as if you had never seen the design before: look for what is on the screen, not for what you meant to put there. In your reply, call it a self-review ("I looked it over again myself"), since it is weaker than a fresh critic.
+
+<!-- rubric:start -->
+**Rubric.** Judge the screenshots first and the entry file only to confirm copy and states. Every finding names one of these areas:
+
+| `area` | Looks for |
+|---|---|
+| `purpose-hierarchy` | Can you tell in five seconds what this is and what to do? One clear first read. |
+| `typography` | The display scale actually used, comfortable line length, not too many sizes or weights. |
+| `colour-contrast` | The accent used for meaning, not decoration; contrast findings from the check. |
+| `layout-rhythm` | Spacing on the design system's steps, alignment, crowded or dead areas. |
+| `copy` | Filler, invented numbers, vague buttons ("Submit", "Learn more"). |
+| `states` | Empty, loading and error states present where the design shows data. |
+| `fit` | Matches the design system's `DESIGN.md` and the brief, not a generic look. |
+
+**The brief wins.** When the brief or the design system asks for the look a finding objects to (all caps, one colour, a dense layout), drop the finding. Don't flag what the check already reported as an error unless it is still visible in the screenshots.
+
+**Verdict:** one of
+- `ship`: nothing worth another round.
+- `polish`: one round of the listed fixes makes it right.
+- `rework`: the direction is wrong (wrong audience, wrong kind of design, unreadable), and fixes won't save it.
+
+**Findings:** at most five, most important first, each with `area`, `where` (the section, element, slide or viewport), `problem` (what is wrong, in one sentence) and `fix` (the change to make, specific enough to do without asking). Fewer is better than padding: a `ship` verdict usually has none.
+
+**Output:** only this JSON, nothing before or after it:
+
+```json
+{ "verdict": "polish", "findings": [{ "area": "copy", "where": "hero button", "problem": "\"Learn more\" doesn't say what happens.", "fix": "Say \"Start your free trial\"." }] }
+```
+<!-- rubric:end -->
+
+## 4. Act on the verdict
+
+- **`ship`:** the design is done. Record the critique (step 5) and tell the user.
+- **`polish`:** apply every finding once with your own file-editing tools, register the artifact again (with the critique, step 5), run `check_open_design_artifact`, and fix any new **error**. Then report it done: don't ask for a second critique unless the user wants one.
+- **`rework`:** don't rebuild yet. Record the critique, tell the user in a sentence or two what is wrong and what you would change, and ask whether to rebuild that way. Rebuilding is their call.
+
+When the user asked for this opinion themselves, show them the verdict and findings and ask which to apply, instead of applying them straight away.
+
+## 5. Record it
+
+Pass the critique as `critique` (`verdict` and `findings`, as returned) on your next `register_open_design_artifact` call for the artifact, with the same other arguments as its last registration (kind, title, skill id, design system, format, supporting files). Only the latest critique is kept; it shows in the browser preview's Checks panel as "Second look". `checkRunId` and `at` are filled in for you. If registration rejects it as over 4 KB, shorten the findings and register again.
+
+## 6. Tell the user
+
+Keep it short and in everyday words: "I had a second look: …", then the top one or two things you improved (or, for `rework`, what's wrong), and nothing about rubric areas, verdict codes, file paths or tools. In Claude Desktop Chat and Cowork, say at most two findings and nothing more technical than that. Elsewhere, list every finding only if the user asks.
+
+If the user says they don't want a second look on their designs, respect it for the rest of the conversation and skip this skill in the check step.

package/assets/codex-skills/open-design-deck-from-source/SKILL.md

@@ -9,6 +9,25 @@ Build a deck (or a one-pager) from existing documents with Open Design, storylin
 
 Request: the rest of the user's message (if there is none, ask the user: "Which document should the deck be built from, and for whom?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Find the sources
 
 Identify the workspace files the request is based on. If it names none, ask which documents to use before doing anything else. Repository files count: `CHANGELOG.md` for a release deck, `docs/adr/*.md` for an architecture review, a metrics CSV or spreadsheet for a board update. Use up to 10 files; for a folder, pick the relevant files.

package/assets/codex-skills/open-design-design-system-from-url/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: open-design-design-system-from-url
+description: Make a design system from a website — measure its real colours, fonts, spacing and button states in a browser, write DESIGN.md and tokens.css that agree, and check the result side by side with the site before saving — use whenever the user wants a design system, brand kit, theme or tokens taken from a website or URL ("make a design system from stripe.com", "match our site's look", "extract the brand from this page"), even if they don't mention Open Design
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Make an Open Design design system from a website: measure the rendered site, write `DESIGN.md` and `tokens.css` from one set of measurements, and check the result against the site before saving it.
+
+Request: the rest of the user's message (if there is none, ask the user: "Which website should the design system come from?")
+
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
+## 1. Ask only what's missing
+
+Three things decide the run. Take each from the request when it says so, and ask only about the ones it leaves open, in one message:
+
+1. **The address** (and, optionally, up to 3 more pages on the same site, such as a pricing or product page).
+2. **Light, dark or both.** Default to light if the user doesn't care.
+3. **Their own brand, or a reference?** For a reference site the design system is named "<Name>-inspired" and no logos or images are copied.
+
+If the request already answers all three ("make a dark design system from https://example.com, it's our brand"), ask nothing and go straight on.
+
+## 2. Measure the site
+
+Call `extract_open_design_design_system` with `url`, `extraUrls` if there are any, and `theme`.
+
+- **`ok`**: you get a `draft` (contract tokens, a `[data-theme="dark"]` set only if the site has a dark theme), `sources` saying which element each value came from, the `unmeasured` tokens, and the screenshot. Look at the screenshot and the role crops in the evidence bundle before writing anything.
+- **`partial`** (no browser installed): only candidate colours and fonts from the page source. Tell the user, show the candidates, and ask them to confirm the brand colour and font, or to install Chrome for a full measurement.
+- **`blocked`**: show the user the screenshot and the reason. Ask for the site's CSS, a screenshot of the page they mean, or another public page. Don't retry the same page.
+- An invalid-args error (a private address, an extra page on another site): tell the user what was refused and why.
+
+If the user asked for dark and the result notes that no dark theme was found, say so. Don't invent dark values.
+
+## 3. Write both files from the draft
+
+Call `create_open_design_design_system` with a `name` (for a reference site, "<Name>-inspired") and a `brief` describing the site in a sentence. Don't pass `sourceUrl`: you have better measurements already. It returns the `suggestedEntryPath`, the `id` and the token contract.
+
+Write `DESIGN.md` at `suggestedEntryPath` and `tokens.css` beside it, **both from the same draft**:
+
+- **`tokens.css`**: start from `draftCss`. Keep every measured value exactly as measured. For an `unmeasured` token, leave it out so the contract fallback applies, or derive it from measured ones (a `color-mix()` of `--accent` for a missing hover); never make one up, and don't fill two steps with the same value.
+- **Sanity-check each role against the screenshot first.** If a measured value plainly can't be that role (text that would be unreadable on `--bg`, a hairline as a spacing step), drop it and say so; don't write prose to explain it away.
+- **`DESIGN.md`**: the values it names (primary colour, surface, text, the font families, the type scale) must be the same values as `tokens.css`. Write the prose (atmosphere, layout, components, voice, do and don't) from the screenshots. For a reference site, say near the top that it is inspired by the site and name it.
+- **Marks**: for the user's own brand, copy the files in the result's `marks` into an `assets/` folder beside `DESIGN.md` and mention them there. For a reference site, copy none.
+
+## 4. Review it side by side
+
+Write a review page next to the design system as `review.html`, and register it with `register_open_design_artifact`. One page, two columns:
+
+- **Left, "The site":** the desktop screenshot from the evidence bundle (an `<img>` with a relative path to it), cropped with `object-fit: cover` to the top 900px.
+- **Right, "The design system":** a sample page that uses only the new `tokens.css` (`<link rel="stylesheet">` to it, or its `:root` block inlined): a hero with a heading and a primary and secondary button, a card with text, and a form row with a label, an input and a button.
+
+Call `check_open_design_artifact` on it. Compare the two columns yourself (colours, font, button shape, density), fix anything that's clearly off, then show the user the review and ask whether it matches.
+
+Apply what the user says ("the buttons are rounder on the site" → raise the radius tokens) in both files, rebuild the review and check again. Stop after **two rounds** of fixes: save then, and list anything still open.
+
+## 5. Save
+
+Call `set_active_design_system` with the returned `id` if the user wants to design with it now (offer it). Tell the user the design system's id and where its files are, and that the measurements are kept in the evidence bundle.

package/assets/codex-skills/open-design-docs/SKILL.md

@@ -9,6 +9,25 @@ Turn existing Markdown documents into designed HTML pages with Open Design, one
 
 Request: the rest of the user's message (if there is none, ask the user: "Which Markdown files should become pages, and in what style?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Find the files
 
 Resolve the folder or glob in the request with your own file tools (for example `docs/adr/*.md`). List what you found.

package/assets/codex-skills/open-design-explore/SKILL.md

@@ -9,6 +9,25 @@ Explore several deliberately different design directions with Open Design, compa
 
 Brief: the rest of the user's message (if there is none, ask the user: "What should we explore directions for?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Plan the directions
 
 If the brief is empty, ask the user what to design before doing anything else.

package/assets/codex-skills/open-design-integrations/SKILL.md

@@ -9,6 +9,25 @@ Show the user Open Design's integrations and whether each one is connected here.
 
 Request: the rest of the user's message (if there is none, ask the user: "Anything you'd like to connect? (or leave empty to just see the list)")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Get the list
 
 Call `list_open_design_integrations` with no arguments. It returns every integration grouped by purpose, each with what it does, the tool names that show it's connected on this agent, whether it can be set up here, and how to manage without it.

package/assets/codex-skills/open-design-new/SKILL.md

@@ -9,22 +9,48 @@ Start a new design with Open Design.
 
 Request: the rest of the user's message (if there is none, ask the user: "What do you want to make, and what is it for?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Pick the surface
 
-Call `list_open_design_skills` with `surface: "list"` to get the kinds of thing Open Design can make (each with an id, label and description).
+Call `list_open_design_skills` with `surface: "list"` to get the kinds of thing Open Design can make (`surfaces`, each with an id, label and description) and the `goals`, plain-language aims such as "Promote an event" or "Get hired", each with the surfaces it leads to.
 
-- If the request starts with or clearly names one of them (by id or label, e.g. "wireframe", "diagram", "a poster"), use that surface.
-- If it names none, or is empty, show the user the surfaces as a short list (label and description) and ask which one. Stop until they answer.
+- If the request starts with or clearly names a surface (by id or label, e.g. "wireframe", "diagram", "a poster"), use that surface.
+- If it says what the design is for but names no surface ("help me get a UX job"), take the goal that fits.
+- If it is empty or too vague to tell, show the user the goals (label and description) and ask one question: "What's it for?". Stop until they answer. Show the surfaces instead only if they ask what kinds of thing you can make.
+- Once you have a goal, call `list_open_design_skills` with `goal` set to its id and use the surface marked `default`, unless the request points at another of that goal's surfaces. Ask which one only when the goal leads to several and you can't tell.
 
 ## 2. Ask what's missing
 
 Call `list_open_design_skills` with `surface` set to the chosen id. The result has the surface's `questions` and its `entries`.
 
-Ask only the questions the request doesn't already answer, all at once, in one short message. If the request answers them all, don't ask anything.
+Each question has `options`, a `default` and what the answer `changes`. Ask only the ones the request, the conversation and the workspace don't already answer, all at once, in one short message, as multiple choice, and accept "you pick" (then use the question's `default`). Ask at most three. If the request already says enough, don't ask anything: "a printed A3 poster for our jazz night on 4 May, dark and moody" gets no questions; "a poster for our event" gets a few.
+
+If no design system is active and the request names no look, also call `recommend_open_design_design_systems` with what you know (the surface, what it's for, how it should feel). If its result has `questions`, add the ones the request doesn't answer to that same message, still three in total at most, surface questions first. Use its first recommendation as the `designSystemId` in step 3, and say which style you used and that they can pick another.
+
+Keep the answers by question id, and note anything you decide without asking (a theme, a layout, how many sections) as a short assumption.
 
 ## 3. Build it
 
 - If the surface has a `prompt` (for example `open-design-poster` or `open-design-social-post`), follow that flow from its first step with the user's request as the brief. In Copilot Chat it's the `/` command of the same name; in Claude Code and Codex it's the skill of the same name.
-- Otherwise pick the entry that best fits the request. Entries come in curated order: the recipe first, then its remixable example when there is one. To start from a rendered example (an entry with an `exampleArtifactPath`), call `remix_open_design_example`; otherwise call `prepare_open_design_brief` with its id and the brief, and follow the general Open Design flow: write the files, register the artifact, then check it with `check_open_design_artifact` before saying it's done.
+- Otherwise pick the entry that best fits the request. Entries come in curated order: the recipe first, then its remixable example when there is one. To start from a rendered example (an entry with `remixable: true`), call `remix_open_design_example`; otherwise call `prepare_open_design_brief` with its id, the brief, any recommended `designSystemId`, the `answers` and your `assumptions` (up to six), and follow the general Open Design flow: write the files, register the artifact with `brief` (the request in one line as `text`, plus the same `answers` and `assumptions`), then check it with `check_open_design_artifact` before saying it's done.
+- When you present the design, list your assumptions in one sentence and invite a change: "I assumed a dark theme and one sign-up button; say if you want otherwise."
 
 Never pick an entry marked `stub: true`.

package/assets/codex-skills/open-design-poster/SKILL.md

@@ -9,6 +9,25 @@ Design a poster with Open Design, check it, and export files that are ready to p
 
 Brief: the rest of the user's message (if there is none, ask the user: "What is the poster for, and is it for print (which size) or screens?")
 
+**How to talk to the user.** Many people using Open Design don't write code, so:
+- Use the user's own words. If they say "artifact", "design tokens" or give a file path, use those terms back; otherwise use the plain words below.
+- Keep the machinery out of replies: no tool names, no ids like `od:prototype:poster-hero`, no internal files (`.artifact.json`, `.comments.json`, `config.json`), and not the words "register", "manifest", "sidecar", "entry" or "surface", unless the user used them first.
+- Explain a print term the first time it comes up, in one short clause, and not again.
+- Say where a file is the way the user would find it ("in your Open Design folder, under seed-swap-flyer"). Give a raw path only where the user can click it (Claude Code, Claude Desktop's Code tab, VS Code) or asks for it.
+- End each reply that finishes a step with one line on what they can do next, with at most two options ("Want it in Instagram sizes too, or is it ready to print?").
+
+| Instead of | Say |
+|---|---|
+| artifact, entry, registered | your design, saved |
+| design system, active design system | your style (the first time: "a saved style: colours, fonts and spacing") |
+| surface, skill, template, recipe | kind of design, starting layout, or nothing |
+| workspace, output directory | your folder, your Open Design folder |
+| bleed | print edge ("a few millimetres extra that the printer trims off") |
+| trim size | final size |
+| preflight findings, errors | "I checked it and fixed…", "one thing to look at:" |
+| export | save as PDF, save as an image |
+| inline preview, MCP App | the preview above |
+
 ## 1. Pick the medium and a default shape
 
 Decide whether this is for **print** or **screens**. If the brief doesn't say, ask the user before doing anything else. Don't guess between print and screen: the units, bleed and type sizes are different.
@@ -39,7 +58,7 @@ Otherwise call `prepare_open_design_brief` with:
 - `format`: the default shape from step 1;
 - `fluid: true`.
 
-Call `list_open_design_design_systems` first only if the user names a brand or visual direction.
+Call `list_open_design_design_systems` first if the user names a brand or visual direction, or `recommend_open_design_design_systems` if they name none and no design system is active.
 
 Author the file yourself, following the returned instructions. Their **Canvas** section is authoritative: one `data-od-card data-od-fluid` element sized by `--od-w`/`--od-h`, everything inside sized in container units, and layout rules for wide and tall shapes. Also: