@feimacode/open-design-agent-kit 0.1.7 → 0.1.8

package/README.md

@@ -1,25 +1,60 @@
 # @feimacode/open-design-agent-kit
 
-**Build pro-grade design into Claude Code and Codex with one command.**
+**Give Claude Code and Codex the skills to design, not just code.**
+
+Run one command in your project and your agent can build decks, landing pages, dashboards, prototypes, social posts, and videos that look designed rather than generated. It works by writing [Open Design](https://github.com/nexu-io/open-design)'s skills straight into your repo, in each agent's own native skill format, plus the MCP server that goes with them — drawing on 163 skills, 114 design templates, 152 brand design systems, and 167 remixable examples so your agent has real design taste to work from instead of guessing.
+
+- **No desktop app, no daemon, no account.** Nothing runs in the background — the skills are plain files in your repo.
+- **No API keys or model settings.** Your agent's own model does all the generation.
+- **No marketplace add or manual copying.** Modeled on `openspec init`: pick your agents, and it writes the files.
+- **Shareable.** Commit the generated `.claude/skills/`, `.agents/skills/`, and MCP config, and everyone who clones the repo gets the same design skills.
+
+## See what it builds
+
+Four of the ~280 vendored skills and templates, rendered exactly as-is:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+<img src="https://raw.githubusercontent.com/feimacode/open-design-agent-kit/main/docs/screenshots/examples/dating-web.png" alt="Consumer dating-app dashboard, editorial typography" width="100%"/><br/>
+<sub><b>"Design a dating-site dashboard — mutuals, match rate, a 30-day trend."</b></sub>
+</td>
+<td width="50%" valign="top">
+<img src="https://raw.githubusercontent.com/feimacode/open-design-agent-kit/main/docs/screenshots/examples/gamified-app.png" alt="Gamified habit-tracking mobile app, three phone frames" width="100%"/><br/>
+<sub><b>"A habit-tracking app with daily quests and XP."</b></sub>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="https://raw.githubusercontent.com/feimacode/open-design-agent-kit/main/docs/screenshots/examples/deck-swiss-international.png" alt="Board strategy deck, Swiss International style" width="100%"/><br/>
+<sub><b>"A board-ready strategy deck, Swiss International style."</b></sub>
+</td>
+<td width="50%" valign="top">
+<img src="https://raw.githubusercontent.com/feimacode/open-design-agent-kit/main/docs/screenshots/examples/card-xiaohongshu.png" alt="Xiaohongshu-style swipeable knowledge card" width="100%"/><br/>
+<sub><b>"5 tips, as a Xiaohongshu-style swipeable card carousel."</b></sub>
+</td>
+</tr>
+</table>
+
+## Install
+
+Nothing to install ahead of time — run it with `npx` (requires Node.js 18+):
 
 ```bash
 npx @feimacode/open-design-agent-kit init
 ```
 
-That's the whole setup. `init` writes [Open Design](https://github.com/nexu-io/open-design)'s design skills straight into your project, in each agent's own native skill format, and registers the MCP server that goes with them. From then on, ask your agent for a deck, a landing page, a dashboard, or a prototype. It draws on 163 skills, 114 design templates, 152 brand design systems, and 167 remixable examples to build something that looks designed rather than generated.
+That's the whole setup: it prompts you to pick Claude Code, Codex, or both (both are pre-selected), then writes the skills and registers the MCP server.
 
-- **No desktop app, no daemon, no account.** There's nothing running in the background, and the skills are plain files in your repo.
-- **No API keys or model settings.** Your agent's own model does all the generation.
-- **No marketplace add or manual copying.** It's modeled on `openspec init`: pick your agents, and it writes the files.
-- **Shareable.** Commit the generated `.claude/skills/`, `.agents/skills/`, and MCP config, and everyone who clones the repo gets the same design skills.
+## Use it
 
-## Quick start
+### 1. Set up your project
 
 ```bash
 npx @feimacode/open-design-agent-kit init
 ```
 
-Prompts you to pick Claude Code, Codex, or both (both are pre-selected). For scripted/CI use, skip the prompt:
+For scripted or CI use, skip the interactive prompt:
 
 ```bash
 npx @feimacode/open-design-agent-kit init --tools all
@@ -30,25 +65,41 @@ npx @feimacode/open-design-agent-kit init --tools codex
 
 `init [path]` defaults to the current directory; pass a path to target a different project.
 
-## What it writes
+What it writes:
+
+- **Claude Code:** skills in `.claude/skills/`, and an `open-design` entry merged into `.mcp.json`. Other servers are kept.
+- **Codex:** the same skills in `.agents/skills/`, and `.codex/config.toml` if you don't have one yet. If you do, the snippet to add is printed instead.
 
-**Claude Code** (`--tools claude`):
-- `.claude/skills/open-design/SKILL.md` — the overview skill (auto-triggers on design requests), plus one explicit-only skill per curated entry (`.claude/skills/<id>/SKILL.md`), same generated content as the [Claude Code plugin](https://github.com/feimacode/open-design-agent-kit#claude-code).
-- `.mcp.json` — merges an `open-design` entry into `mcpServers`. Any other servers you already have configured are preserved; the file is created fresh if it doesn't exist yet.
+Both point at [`@feimacode/open-design-agent-kit-mcp`](https://www.npmjs.com/package/@feimacode/open-design-agent-kit-mcp). Full details are in the [`init` reference](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/reference/cli.md#init).
 
-**Codex** (`--tools codex`):
-- `.agents/skills/open-design/` and one skill per curated entry (with a sibling `agents/openai.yaml` marking it explicit-only) — Codex's own skill-discovery convention.
-- `.codex/config.toml` — created fresh with the `open-design` MCP server registration **only if the file doesn't already exist**. If it does, nothing is touched — the exact snippet to add by hand is printed instead, since no TOML library round-trips an existing file's comments/formatting losslessly.
+It's safe to re-run: generated skill files are always fully refreshed, with no stale entries left behind from a previous run. A skill directory *you* created by hand under the same location is never touched or deleted — only directories this tool generated itself get replaced. `.mcp.json` only ever has its own `open-design` entry updated; an existing `.codex/config.toml` is never rewritten at all.
 
-Both hosts end up pointed at [`@feimacode/open-design-agent-kit-mcp`](https://www.npmjs.com/package/@feimacode/open-design-agent-kit-mcp) via `npx`, the same server the VS Code extension and Claude Code plugin use.
+### 2. Ask your agent to design something
 
-## Safe to re-run
+Once `init` has run, just talk to your agent — no further CLI commands needed. Try prompts like:
+
+- "Build a landing page for [product]"
+- "Make a pitch deck for [idea]"
+- "Design a dashboard for [data]"
+- "Create a social card announcing [thing]"
+
+The agent picks a matching skill and produces a real design, saved into your project as plain HTML/JSX/CSS you can keep editing.
+
+### 3. Export or render from a script (optional)
+
+Once an artifact exists, export it to an image, PDF, or PowerPoint, or render a HyperFrames composition to video — no agent needed:
+
+```bash
+npx @feimacode/open-design-agent-kit export .open-design/launch/launch.html --max-bytes 5000000
+npx @feimacode/open-design-agent-kit export .open-design/pitch/pitch.html --format pptx
+npx @feimacode/open-design-agent-kit render-video .open-design/promo --output .open-design/promo/exports/promo.mp4
+```
 
-Generated skill files are always fully refreshed — no stale entries left behind from a previous run. A skill directory *you* created by hand under the same location is never touched or deleted; only directories this tool generated itself get replaced. `.mcp.json` only ever has its own `open-design` entry updated; an existing `.codex/config.toml` is never rewritten at all.
+Every option is in the [CLI reference](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/reference/cli.md), and a full scripted setup is in [Social media pipeline](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/automation/social-pipeline.md).
 
-## More
+## Learn more
 
-Full project layout and the other ways to use Open Design (VS Code extension, the Claude Code plugin marketplace, the standalone MCP server) live in the [main repo](https://github.com/feimacode/open-design-agent-kit).
+[Documentation](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/README.md): getting started for [Claude Code](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/getting-started/claude-code.md) and [Codex](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/getting-started/codex.md), guides, and [troubleshooting](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/troubleshooting.md).
 
 ## License
 

package/assets/claude-skills/card-twitter/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: "od-prototype-card-twitter"
+description: Twitter Share Card (Open Design) — use only when the user explicitly runs this skill
+disable-model-invocation: true
+argument-hint: a brief describing what to build (optional — defaults to a starting example)
+---
+
+<!-- generated:curated-entry -->
+
+Use the Open Design skill `od:prototype:card-twitter` (Twitter Share Card).
+
+Brief: "$ARGUMENTS", or if empty: "Use the Twitter Share Card template to turn my content into a Twitter quote or data card designed to pair with a post. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:card-twitter" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

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

@@ -13,6 +13,12 @@ All Open Design content (skill/template text, design system tokens, example brie
 
 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.
+
+   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.
 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. 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").
 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.
@@ -27,3 +33,15 @@ If the user wants to start from or riff on an existing example rather than build
 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 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. Videos (HyperFrames) aren't exported with this tool: the brief's own instructions say how to render them to MP4 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.
+
+## Help
+
+When the user asks how something works, or a tool reports an error, point them to the relevant page:
+
+- Documentation index: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/README.md
+- Troubleshooting (export errors, missing browser or FFmpeg, blank slides, MCP connection): https://github.com/feimacode/open-design-agent-kit/blob/main/docs/troubleshooting.md
+- Social media posts: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/social-posts.md
+- Export images: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-images.md · Export decks and PDFs: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-decks.md
+- Tools reference: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/reference/tools.md

package/assets/claude-skills/open-design-social-post/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: "open-design-social-post"
+description: Design a social media post (X, Instagram, LinkedIn, Xiaohongshu, Stories/Reels, YouTube thumbnail or video) and export upload-ready files — use whenever the user wants something to post on social media (an X/Twitter image, Instagram or LinkedIn post or carousel, Xiaohongshu cards, a Story/Reels cover, a YouTube thumbnail or video), even if they don't mention Open Design
+argument-hint: what to post, and optionally where (e.g. "X post announcing our v2 launch")
+---
+
+<!-- generated:curated-entry -->
+
+Design a social media post with Open Design and export files that are ready to upload.
+
+Brief: "$ARGUMENTS" — or, if that is empty, the user's request in this conversation (ask them what to post and where if it isn't clear)
+
+## 1. Pick the platform and format
+
+If the brief names a platform or format, use it. Otherwise ask the user to pick one of the rows below before doing anything else. Don't guess.
+
+| Format | Canvas | skillId | Export |
+|---|---|---|---|
+| X single image | 1600×900 | `od:prototype:card-twitter` | `selector: "[data-od-card]"`, `maxBytes: 5000000` |
+| X post mock (for a video overlay or quote) | card element | `od:prototype:social-x-post-card` | `selector: "[data-od-card]"`, `maxBytes: 5000000` |
+| Square carousel (Instagram / LinkedIn) | 1080×1080 per card | `od:prototype:social-carousel` | `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Instagram portrait | 1080×1350 | `od:prototype:poster-hero` | `width: 1080, height: 1350`, `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Story / Reels / TikTok cover | 1080×1920 | `od:prototype:poster-hero` | `width: 1080, height: 1920`, `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Xiaohongshu cards | 1080×1440 per card | `od:prototype:card-xiaohongshu` | `selector: "[data-od-card]"` |
+| YouTube thumbnail | 1280×720 | `od:prototype:social-youtube-thumbnail` | `width: 1280, height: 720`, `selector: "[data-od-card]"`, `maxBytes: 2000000` |
+| YouTube video | 1920×1080 MP4 | `od:video:hyperframes` | MP4 via the HyperFrames CLI (see step 4) |
+
+For several platforms at once, run steps 2–4 once per format and keep each one as its own artifact.
+
+## 2. Generate
+
+Call `prepare_open_design_brief` with the row's `skillId` and the brief. Call `list_open_design_design_systems` first only if the user names a brand or visual direction. In the brief you pass, say the exact canvas size from the table.
+
+Author the files yourself with your own file-editing tools, following the returned instructions, and add these rules for social posts:
+
+- Each card or canvas is a fixed-size element at exactly the table's size with `overflow: hidden`, and carries a `data-od-card` attribute. For multi-card formats, stack the cards vertically in one HTML file, one `data-od-card` element per card.
+- Use real copy from the brief, with no lorem ipsum. Keep text inside a 48px safe margin, and make the hook readable at thumbnail size.
+- No external image URLs unless the user supplied them.
+- No emoji as key visuals. They render from the exporting machine's fonts and can come out as empty boxes. Draw icons and subjects as inline SVG.
+
+## 3. Register
+
+Call `register_open_design_artifact` with the entry path, kind `html`, a title, and `sourceSkillId` set to the row's `skillId`, so the export can find the right size.
+
+## 4. Export
+
+- **Image formats**: call `export_open_design_artifact` with the entry path and the row's export arguments. If it returns warnings (failed fonts or images, over budget), fix the artifact and export again.
+- **YouTube video**: follow the brief's "Host override" section. Render with `npx hyperframes render … --output <artifact-dir>/exports/<name>.mp4`, and check `ffmpeg -version` first.
+
+## 5. Report
+
+List each exported file's path, pixel size, and file size, and remind the user of the post's copy (caption and hashtags) if you wrote any. Don't post anything anywhere yourself.

package/assets/claude-skills/poster-hero/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: "od-prototype-poster-hero"
+description: Marketing Poster (Open Design) — use only when the user explicitly runs this skill
+disable-model-invocation: true
+argument-hint: a brief describing what to build (optional — defaults to a starting example)
+---
+
+<!-- generated:curated-entry -->
+
+Use the Open Design skill `od:prototype:poster-hero` (Marketing Poster).
+
+Brief: "$ARGUMENTS", or if empty: "Use the Marketing Poster template to turn my content into a vertical poster or Moments-style share image with strong visual impact. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:poster-hero" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/claude-skills/social-carousel/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: "od-prototype-social-carousel"
+description: social-carousel (Open Design) — use only when the user explicitly runs this skill
+disable-model-invocation: true
+argument-hint: a brief describing what to build (optional — defaults to a starting example)
+---
+
+<!-- generated:curated-entry -->
+
+Use the Open Design skill `od:prototype:social-carousel` (social-carousel).
+
+Brief: "$ARGUMENTS", or if empty: "Design a 3-card cinematic social carousel — ‘onwards.’, ‘to the next one.’, ‘looking ahead.’. 1080×1080 squares, drop-into-Instagram ready."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-carousel" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/claude-skills/social-youtube-thumbnail/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: "od-prototype-social-youtube-thumbnail"
+description: YouTube Thumbnail (Open Design) — use only when the user explicitly runs this skill
+disable-model-invocation: true
+argument-hint: a brief describing what to build (optional — defaults to a starting example)
+---
+
+<!-- generated:curated-entry -->
+
+Use the Open Design skill `od:prototype:social-youtube-thumbnail` (YouTube Thumbnail).
+
+Brief: "$ARGUMENTS", or if empty: "Use the YouTube Thumbnail template to design a thumbnail for my video. Make the promise of the video readable in under a second: one short hook line, one strong focal subject, high contrast. Use real content from my brief and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-youtube-thumbnail" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/card-twitter/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: card-twitter
+description: Twitter Share Card (Open Design) — use only when explicitly invoked, not for general design requests
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Use the Open Design skill `od:prototype:card-twitter` (Twitter Share Card).
+
+Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Twitter Share Card template to turn my content into a Twitter quote or data card designed to pair with a post. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:card-twitter" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/card-twitter/agents/openai.yaml

@@ -0,0 +1,3 @@
+# generated:open-design-agent-kit
+policy:
+  allow_implicit_invocation: false

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

@@ -15,6 +15,12 @@ All Open Design content (skill/template text, design system tokens, example brie
 
 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.
+
+   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.
 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. 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").
 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.
@@ -29,3 +35,15 @@ If the user wants to start from or riff on an existing example rather than build
 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 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. Videos (HyperFrames) aren't exported with this tool: the brief's own instructions say how to render them to MP4 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.
+
+## Help
+
+When the user asks how something works, or a tool reports an error, point them to the relevant page:
+
+- Documentation index: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/README.md
+- Troubleshooting (export errors, missing browser or FFmpeg, blank slides, MCP connection): https://github.com/feimacode/open-design-agent-kit/blob/main/docs/troubleshooting.md
+- Social media posts: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/social-posts.md
+- Export images: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-images.md · Export decks and PDFs: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-decks.md
+- Tools reference: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/reference/tools.md

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

@@ -0,0 +1,51 @@
+---
+name: open-design-social-post
+description: Design a social media post (X, Instagram, LinkedIn, Xiaohongshu, Stories/Reels, YouTube thumbnail or video) and export upload-ready files — use whenever the user wants something to post on social media (an X/Twitter image, Instagram or LinkedIn post or carousel, Xiaohongshu cards, a Story/Reels cover, a YouTube thumbnail or video), even if they don't mention Open Design
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Design a social media post with Open Design and export files that are ready to upload.
+
+Brief: the rest of the user's message (if there is none, ask the user: "What should the post say, and for which platform?")
+
+## 1. Pick the platform and format
+
+If the brief names a platform or format, use it. Otherwise ask the user to pick one of the rows below before doing anything else. Don't guess.
+
+| Format | Canvas | skillId | Export |
+|---|---|---|---|
+| X single image | 1600×900 | `od:prototype:card-twitter` | `selector: "[data-od-card]"`, `maxBytes: 5000000` |
+| X post mock (for a video overlay or quote) | card element | `od:prototype:social-x-post-card` | `selector: "[data-od-card]"`, `maxBytes: 5000000` |
+| Square carousel (Instagram / LinkedIn) | 1080×1080 per card | `od:prototype:social-carousel` | `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Instagram portrait | 1080×1350 | `od:prototype:poster-hero` | `width: 1080, height: 1350`, `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Story / Reels / TikTok cover | 1080×1920 | `od:prototype:poster-hero` | `width: 1080, height: 1920`, `selector: "[data-od-card]"`, `maxBytes: 8000000` |
+| Xiaohongshu cards | 1080×1440 per card | `od:prototype:card-xiaohongshu` | `selector: "[data-od-card]"` |
+| YouTube thumbnail | 1280×720 | `od:prototype:social-youtube-thumbnail` | `width: 1280, height: 720`, `selector: "[data-od-card]"`, `maxBytes: 2000000` |
+| YouTube video | 1920×1080 MP4 | `od:video:hyperframes` | MP4 via the HyperFrames CLI (see step 4) |
+
+For several platforms at once, run steps 2–4 once per format and keep each one as its own artifact.
+
+## 2. Generate
+
+Call `prepare_open_design_brief` with the row's `skillId` and the brief. Call `list_open_design_design_systems` first only if the user names a brand or visual direction. In the brief you pass, say the exact canvas size from the table.
+
+Author the files yourself with your own file-editing tools, following the returned instructions, and add these rules for social posts:
+
+- Each card or canvas is a fixed-size element at exactly the table's size with `overflow: hidden`, and carries a `data-od-card` attribute. For multi-card formats, stack the cards vertically in one HTML file, one `data-od-card` element per card.
+- Use real copy from the brief, with no lorem ipsum. Keep text inside a 48px safe margin, and make the hook readable at thumbnail size.
+- No external image URLs unless the user supplied them.
+- No emoji as key visuals. They render from the exporting machine's fonts and can come out as empty boxes. Draw icons and subjects as inline SVG.
+
+## 3. Register
+
+Call `register_open_design_artifact` with the entry path, kind `html`, a title, and `sourceSkillId` set to the row's `skillId`, so the export can find the right size.
+
+## 4. Export
+
+- **Image formats**: call `export_open_design_artifact` with the entry path and the row's export arguments. If it returns warnings (failed fonts or images, over budget), fix the artifact and export again.
+- **YouTube video**: follow the brief's "Host override" section. Render with `npx hyperframes render … --output <artifact-dir>/exports/<name>.mp4`, and check `ffmpeg -version` first.
+
+## 5. Report
+
+List each exported file's path, pixel size, and file size, and remind the user of the post's copy (caption and hashtags) if you wrote any. Don't post anything anywhere yourself.

package/assets/codex-skills/poster-hero/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: poster-hero
+description: Marketing Poster (Open Design) — use only when explicitly invoked, not for general design requests
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Use the Open Design skill `od:prototype:poster-hero` (Marketing Poster).
+
+Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the Marketing Poster template to turn my content into a vertical poster or Moments-style share image with strong visual impact. Preserve the template's visual signature, use real content and data, and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:poster-hero" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/poster-hero/agents/openai.yaml

@@ -0,0 +1,3 @@
+# generated:open-design-agent-kit
+policy:
+  allow_implicit_invocation: false

package/assets/codex-skills/social-carousel/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: social-carousel
+description: social-carousel (Open Design) — use only when explicitly invoked, not for general design requests
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Use the Open Design skill `od:prototype:social-carousel` (social-carousel).
+
+Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Design a 3-card cinematic social carousel — ‘onwards.’, ‘to the next one.’, ‘looking ahead.’. 1080×1080 squares, drop-into-Instagram ready."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-carousel" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-carousel/agents/openai.yaml

@@ -0,0 +1,3 @@
+# generated:open-design-agent-kit
+policy:
+  allow_implicit_invocation: false

package/assets/codex-skills/social-youtube-thumbnail/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: social-youtube-thumbnail
+description: YouTube Thumbnail (Open Design) — use only when explicitly invoked, not for general design requests
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Use the Open Design skill `od:prototype:social-youtube-thumbnail` (YouTube Thumbnail).
+
+Treat the rest of the user's message as the brief. If nothing more specific was given, use: "Use the YouTube Thumbnail template to design a thumbnail for my video. Make the promise of the video readable in under a second: one short hook line, one strong focal subject, high contrast. Use real content from my brief and avoid lorem ipsum or placeholder images."
+
+Call `prepare_open_design_brief` (the open-design MCP server's tool) with skillId "od:prototype:social-youtube-thumbnail" and this brief — call `list_open_design_design_systems` first only if the user names a brand or visual direction. Author the files yourself with your own file-editing tools per the returned instructions, then call `register_open_design_artifact`.

package/assets/codex-skills/social-youtube-thumbnail/agents/openai.yaml

@@ -0,0 +1,3 @@
+# generated:open-design-agent-kit
+policy:
+  allow_implicit_invocation: false