From bffdf40eb2d8c5a5f0bfcf83d5e5983581c7faf7 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Wed, 10 Jun 2026 11:05:35 +0200 Subject: [PATCH 01/10] feat: move to CLI skills --- packages/claude-plugin/.mcp.json | 12 -- .../frontend-component-writing/SKILL.md | 6 +- .../claude-plugin/skills/stories/SKILL.md | 43 +++---- .../codex-plugin/plugins/storybook/.mcp.json | 10 -- .../frontend-component-writing/SKILL.md | 26 +---- .../plugins/storybook/skills/stories/SKILL.md | 107 +++++++----------- 6 files changed, 77 insertions(+), 127 deletions(-) delete mode 100644 packages/claude-plugin/.mcp.json delete mode 100644 packages/codex-plugin/plugins/storybook/.mcp.json diff --git a/packages/claude-plugin/.mcp.json b/packages/claude-plugin/.mcp.json deleted file mode 100644 index d5cc3624..00000000 --- a/packages/claude-plugin/.mcp.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "mcpServers": { - "storybook": { - "command": "npx", - "args": [ - "-y", - "--prefer-online", - "https://pkg.pr.new/storybookjs/mcp/@storybook/mcp-proxy@main" - ] - } - } -} diff --git a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md index c39f61f1..2d459bda 100644 --- a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md +++ b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md @@ -28,16 +28,18 @@ description: >- stories so they reflect the change. - You MUST NOT write or edit any `*.stories.*` file directly from here. All story work goes through the **`stories`** skill, which owns the strict, gated - Storybook workflow (loading the MCP rules, guaranteeing a running preview, and - producing a verifiable preview link). + Storybook workflow. - You MUST NOT report a component change as complete until the corresponding story work has been handed off to the `stories` skill and finished. - FOLLOW THE WORKFLOW SEQUENTIALLY +- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Workflow 1. Determine whether the project has Storybook. If it does NOT, go to "When Storybook is not installed" and stop here unless the user opts in. + - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. + - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. 2. Invoke the **`stories`** skill to create, update, or remove the stories for the component you just touched. Tell it which component changed and what changed (new component, new props, new variants, renamed states, deleted diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index 3553d64f..7da4eaa8 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -10,14 +10,12 @@ description: >- assets. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, or has "no behavior change" — that judgment is not yours to make; the skill always runs. Also use before starting or previewing Storybook to - verify UI. Pulls story-writing guidance from the Storybook MCP, keeps the - preview running so stories can be verified, and repairs the Claude launch - config when Storybook is not running. + verify UI. --- # Storybook Stories -The Storybook MCP is the source of truth for _how_ to write stories. This skill +The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill is the **mandatory, ordered process** for working on them. This is a STRICT, GATED workflow. You MUST execute the steps below in order and @@ -28,16 +26,26 @@ working around it. Treat any shortcut as a failure of this workflow. ## Absolute rules -- FOLLOW THE WORKFLOW SEQUENTIALLY -- ALL TOOL CALLS MUST GO THROUGH STORYBOOK MCP PROXY - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. -- YOU MUST USE THE PORT INPUT WHENEVER AVAILABLE FOR ANY TOOL CALL THAT SUPPORTS IT, to ensure your calls are routed through the Storybook MCP Proxy and not directly to the server. -- IGNORE PROJECT LOCAL STORYBOOK MCP. ONLY USE THE STORYBOOK MCP PROXY SERVER FOR ALL STORYBOOK-RELATED TOOL CALLS, to ensure you are following the MCP's instructions and your calls are routed through the proxy for accurate port handling and preview integration. +- IGNORE LOCAL REGISTERED STORYBOOK MCP + +## Step 0 — Prerequisites + +- Storybook must be installed in the project. If it is not, invoke the + **storybook-init** skill to set it up, or ask the user if they want to set it + up before proceeding. If the user declines, STOP and report that Storybook is + required for story work. +- Storybook must be a canary version (0.0.0-canary) or at least version 10.5. If an older version is + installed, invoke the **storybook-upgrade** skill to upgrade it before + proceeding. +- Storybook `.storybook/main.js` (or `main.ts`) must have `features.ai` enabled. ## Step 1 — Open the preview browser up front +MANDATORY REQUIREMENT BEFORE GOING TO STEP 2 + 1. Inspect `.claude/launch.json` for a launch entry that starts this project's Storybook dev server. If: - the `.claude/launch.json` file does not exist @@ -46,18 +54,18 @@ working around it. Treat any shortcut as a failure of this workflow. repair it first: invoke the **storybook-setup-claude-launch** skill, which creates or repairs the `.claude/launch.json` Storybook entry. 2. Start Storybook by launching that `.claude/launch.json` entry through the Claude launcher (never via Bash/background, per the Absolute rules). 3. Open the Storybook preview in the preview browser. If the launch entry uses `autoPort`, wait for the terminal to show which port Storybook is running on and use that port to open the preview URL (e.g. `http://localhost:6006`) in the preview browser. -4. Save the port being used by Storybook shown in the terminal in your working memory. USE THIS PORT FOR ALL TOOL CALLS in the following steps to ensure they are routed through the MCP Proxy. +4. Save the port being used by Storybook shown in the terminal in your working memory. USE THIS PORT FOR ANY SUBCOMMAND THAT NEEDS TO KNOW THE PORT (e.g. `preview-stories`). **Gate:** Do NOT proceed to Step 2 until the preview browser is open and has rendered the Storybook URL without error. If launch setup reports an error, surface it to the user and STOP. ## Step 2 — Load the rules (before touching any story file) -USE THE STORYBOOK MCP PROXY SERVER. - -Call **get-storybook-story-instructions** and read it fully. Look components up -with **list-all-documentation** / **get-documentation** rather than assuming -props or APIs. +- Run `npx storybook ai --help` to get all available subcommands and options. + - Save the available subcommands and options in your working memory for reference. +- Run the ai subcommand to get the story-writing instructions. + - If the subcommand allows a port option, use the port you saved in Step 1. +- Follow the instructions in the output, which will include the exact imports, structure, and conventions to use for the story you are writing or editing. The instructions are the ONLY acceptable source for how to write the story; do NOT rely on memory or existing patterns. **Gate:** Do NOT create or edit any `*.stories.*` file until this tool has returned and you are following its output. If you have not called it this task, @@ -67,14 +75,11 @@ you are not allowed to write a story yet — go back and call it now. Create or edit the story strictly following the Step 2 instructions. -**Gate:** Every story you touched must conform to the -`get-storybook-story-instructions` output. If anything is unclear, re-read it +**Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. ## Step 4 — Preview and verify -USE THE STORYBOOK MCP PROXY SERVER. - Produce a preview for every story you touched with **preview-stories** (prefer `{ storyId }` inputs). Before showing any returned URL to the user, navigate to it in the preview browser and confirm the story renders without errors. @@ -85,8 +90,6 @@ story as done until each preview link has been navigated and verified. ## Step 5 — Publish the review page -USE THE STORYBOOK MCP PROXY SERVER. - Once the stories render cleanly, call **display-review** so the user can review exactly what changed in one place. This tool does NOT just return a link — it publishes a curated **review page** inside the already-running Storybook and diff --git a/packages/codex-plugin/plugins/storybook/.mcp.json b/packages/codex-plugin/plugins/storybook/.mcp.json deleted file mode 100644 index fe5185cc..00000000 --- a/packages/codex-plugin/plugins/storybook/.mcp.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "storybook": { - "command": "npx", - "args": [ - "-y", - "--prefer-online", - "https://pkg.pr.new/storybookjs/mcp/@storybook/mcp-proxy@main" - ] - } -} diff --git a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md index 9c9ae38a..676d81fb 100644 --- a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md @@ -17,19 +17,6 @@ description: >- # Frontend Component Writing -Frontend components and their Storybook stories must stay in sync. This skill -runs **before** you touch a component file — for ANY reason — so the workflow -governs how the change is made. Whenever you create, edit, or delete a component, -its stories MUST be created, updated, or removed to match. Do NOT decide for -yourself that a change is "cosmetic", "internal", a "refactor", a "rename", a -"deletion", or has "no behavior change" and skip the story step: that exemption -does not exist. If a component is created, edited, or deleted, the story step -runs. - -This is a MANDATORY companion step **when Storybook is already set up** in the -project. If Storybook is not installed, do not force it — see "When Storybook is -not installed" below. - ## Absolute rules - This skill runs FIRST. The moment you know you are going to create, edit, or @@ -45,21 +32,20 @@ not installed" below. producing a verifiable preview link). - You MUST NOT report a component change as complete until the corresponding story work has been handed off to the `stories` skill and finished. +- FOLLOW THE WORKFLOW SEQUENTIALLY +- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Workflow 1. Determine whether the project has Storybook. If it does NOT, go to "When Storybook is not installed" and stop here unless the user opts in. -2. Make the component change the user asked for — creating, editing, or deleting - the component — following the surrounding code's conventions. -3. Identify the component's story file (`*.stories.tsx/.ts/.jsx/.js/.vue/.svelte`). - If one does not exist yet for a new component, it still needs stories. If the - component is being deleted, its stories must be removed too. -4. Invoke the **`stories`** skill to create, update, or remove the stories for + - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. + - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. +2. Invoke the **`stories`** skill to create, update, or remove the stories for the component you just touched. Tell it which component changed and what changed (new component, new props, new variants, renamed states, deleted component, etc.) so it can cover or clean up the affected surface. -5. Let the `stories` skill run its full gated workflow — including producing the +3. Let the `stories` skill run its full gated workflow — including producing the preview link — and surface that link in your final response. **Gate:** Do NOT consider the component task done until the `stories` skill has diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index 3957d2b1..0ee309e8 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -5,20 +5,9 @@ description: Write, create, update, or review Storybook stories for a component # Storybook Stories -The Storybook MCP is the source of truth for _how_ to write stories. This skill +The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill is the **mandatory, ordered process** for working on them. -## Follow the MCP's own workflow first - -If the Storybook MCP is reachable through the MCP-proxy, it serves its own -**server instructions** describing the authoritative tool workflow (routing, -documentation lookup, previewing, working on stories, verification). When those -instructions are available, read them and follow them **carefully and exactly** — -they take precedence over any general assumption you might make about the tools. -The gated steps below operate _within_ that MCP-provided workflow; they do not -replace it. If the MCP exposes no instructions (proxy unavailable or Storybook -not registered), fall back to the steps below. - This is a STRICT, GATED workflow. You MUST execute the steps below in order and satisfy each step's **Gate** before moving to the next. Do NOT skip, reorder, or batch steps. Do NOT write or edit any `*.stories.*` file until Steps 1 and 2 are @@ -30,76 +19,68 @@ working around it. Treat any shortcut as a failure of this workflow. - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. -- You MUST NOT report a story as done until its preview link has been produced - (Step 4) AND the review page has been published and opened (Step 5). An - unverified story, or a change with no review page, is not a deliverable. +- IGNORE LOCAL REGISTERED STORYBOOK MCP -## Step 1 — Load the rules (before touching any story file) +## Step 0 — Prerequisites -Call **get-storybook-story-instructions** and read it fully. Look components up -with **list-all-documentation** / **get-documentation** rather than assuming -props or APIs. +- Storybook must be installed in the project. If it is not, invoke the + **storybook-init** skill to set it up, or ask the user if they want to set it + up before proceeding. If the user declines, STOP and report that Storybook is + required for story work. +- Storybook must be a canary version (0.0.0-canary) or at least version 10.5. If an older version is + installed, invoke the **storybook-upgrade** skill to upgrade it before + proceeding. -**Gate:** Do NOT create or edit any `*.stories.*` file until this tool has -returned and you are following its output. If you have not called it this task, -you are not allowed to write a story yet — go back and call it now. - -## Step 2 — Guarantee a running preview +## Step 1 — Guarantee a running preview browser The Storybook preview MUST be running so the story can be verified. -If any MCP tool returns a "Storybook is not running" error, you MUST NOT ignore -it and MUST NOT proceed to write the story. STOP and recover: +Run `npx storybook ai instances ls` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. +If there is no running instance, start it with the steps below: + 1. Start the project's existing Storybook dev script as a background task from + the Storybook invocation directory + 2. Wait for the terminal to show which port Storybook is running on and use that port to open the preview URL (e.g. `http://localhost:6006`) in the preview browser. + 3. Save the port being used by Storybook shown in the terminal in your working memory. USE THIS PORT FOR ANY SUBCOMMAND THAT NEEDS TO KNOW THE PORT (e.g. `preview-stories`). + +**Gate:** Do NOT proceed to Step 2 until the preview browser is open and has rendered the Storybook URL without +error. If launch setup reports an error, surface it to the user and STOP. -1. Start the project's existing Storybook dev script as a background task from - the Storybook invocation directory, and open it in Codex's in-app browser. -2. Use that invocation directory as the `cwd` for MCP tool calls. -3. Retry the MCP tool call. If Storybook is not configured yet, use the `init` - skill; if it is outdated, use the `upgrade` skill. +## Step 2 — Load the rules (before touching any story file) -**Gate:** Do NOT proceed to Step 3 until an MCP tool call succeeds against a -running Storybook. +- Run `npx storybook ai --help` to get all available subcommands and options. + - Save the available subcommands and options in your working memory for reference. +- Run the ai subcommand to get the story-writing instructions. +- Follow the instructions in the output, which will include the exact imports, structure, and conventions to use for the story you are writing or editing. The instructions are the ONLY acceptable source for how to write the story; do NOT rely on memory or existing patterns. + +**Gate:** Do NOT create or edit any `*.stories.*` file until you are following its output. If you have not called it this task, +you are not allowed to write a story yet — go back and call it now. ## Step 3 — Write the story -Create or edit the story strictly following the Step 1 instructions. +Create or edit the story strictly following the Step 2 instructions. -**Gate:** Every story you touched must conform to the -`get-storybook-story-instructions` output. If anything is unclear, re-read it +**Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. -## Step 4 — Verify +## Step 4 — Preview and verify -After changes, call **preview-stories** and open the returned links in Codex's -in-app browser to confirm the stories render without errors. These links are for -your own verification. +Produce a preview for every story you touched with **preview-stories** (prefer +`{ storyId }` inputs). Before showing any returned URL to the user, navigate to +it in the preview browser and confirm the story renders without errors. -**Gate:** Do NOT proceed to Step 5 until preview links exist and render for the -stories you created or changed. +**Gate:** Every URL you put in your final response MUST have been opened in the +preview browser first — no exceptions, per the Absolute rules. Do NOT report the +story as done until each preview link has been navigated and verified. ## Step 5 — Publish the review page Once the stories render cleanly, call **display-review** so the user can review exactly what changed in one place. This tool does NOT just return a link — it publishes a curated **review page** inside the already-running Storybook and -returns its `reviewUrl`. The review page IS the deliverable. - -- Group the stories you touched into `collections` covering the **visual - cascade** of the change: the changed component itself, the components that - import it, and the pages/containers that render them. Don't ship a - single-collection review unless the component is genuinely standalone. -- Every `storyId` you pass MUST come from a tool result this session - (`get-changed-stories`, `get-stories-by-component`, or `list-all-documentation`). - `display-review` validates every ID against the live index and rejects the - whole review if any are unknown — never invent IDs. -- Provide `title`, `description`, and `changedFiles` (the files you edited, most - central first). - -Because the `reviewUrl` is a page, open it in Codex's in-app browser — do not -merely print it. Then surface it to the user as the very last thing in your -response, under its own heading (e.g. `## 👀 Review your changes`) as a markdown -link, with nothing after it. - -**Gate:** Do NOT claim the task is complete until `display-review` has succeeded, -you have opened the returned `reviewUrl`, and that link is the final element of -your user-facing response. +returns its `reviewUrl`. The review page IS the deliverable; the raw +`preview-stories` URLs from Step 4 are for your own verification. + +**Gate:** Do NOT report the task as done until `display-review` has succeeded, +you have opened the returned `reviewUrl` in the preview browser, and that link is +the final element of your user-facing response. + From ed04c68f1e80d8eca2f718f8baac5b9450152788 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Wed, 10 Jun 2026 14:54:19 +0200 Subject: [PATCH 02/10] chore: update skill --- .../skills/frontend-component-writing/SKILL.md | 8 ++++++-- .../skills/frontend-component-writing/SKILL.md | 11 +++++++---- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md index 2d459bda..beb7796d 100644 --- a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md +++ b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md @@ -36,8 +36,8 @@ description: >- ## Workflow -1. Determine whether the project has Storybook. If it does NOT, go to "When - Storybook is not installed" and stop here unless the user opts in. +1. Determine whether the project has Storybook. + - If not installed go to "When Storybook is not installed" and stop here unless the user opts in. - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. 2. Invoke the **`stories`** skill to create, update, or remove the stories for @@ -80,6 +80,10 @@ Before asking the user anything, check whether they have already declined: (`storybook-init` / `storybook-setup`), then resume the Workflow above from step 3. If an opt-out file existed from a previous "no", delete it. +5. Once done, the user should have Storybook installed and configured, the component change + made, and the `stories` skill invoked to create/update/delete the relevant + stories with a verified preview link. + **Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook dependencies, or invoke the setup skills unless the user has explicitly opted in this time. A saved opt-out MUST be respected on every later invocation without diff --git a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md index 676d81fb..beb7796d 100644 --- a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md @@ -28,8 +28,7 @@ description: >- stories so they reflect the change. - You MUST NOT write or edit any `*.stories.*` file directly from here. All story work goes through the **`stories`** skill, which owns the strict, gated - Storybook workflow (loading the MCP rules, guaranteeing a running preview, and - producing a verifiable preview link). + Storybook workflow. - You MUST NOT report a component change as complete until the corresponding story work has been handed off to the `stories` skill and finished. - FOLLOW THE WORKFLOW SEQUENTIALLY @@ -37,8 +36,8 @@ description: >- ## Workflow -1. Determine whether the project has Storybook. If it does NOT, go to "When - Storybook is not installed" and stop here unless the user opts in. +1. Determine whether the project has Storybook. + - If not installed go to "When Storybook is not installed" and stop here unless the user opts in. - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. 2. Invoke the **`stories`** skill to create, update, or remove the stories for @@ -81,6 +80,10 @@ Before asking the user anything, check whether they have already declined: (`storybook-init` / `storybook-setup`), then resume the Workflow above from step 3. If an opt-out file existed from a previous "no", delete it. +5. Once done, the user should have Storybook installed and configured, the component change + made, and the `stories` skill invoked to create/update/delete the relevant + stories with a verified preview link. + **Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook dependencies, or invoke the setup skills unless the user has explicitly opted in this time. A saved opt-out MUST be respected on every later invocation without From d40c7aa7174ad819d5f3cb562a359c26a677d8a2 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Wed, 10 Jun 2026 16:59:52 +0200 Subject: [PATCH 03/10] fix: update skills --- .../skills/frontend-component-writing/SKILL.md | 11 +---------- packages/claude-plugin/skills/stories/SKILL.md | 7 ++----- .../skills/frontend-component-writing/SKILL.md | 9 --------- .../plugins/storybook/skills/stories/SKILL.md | 8 ++++---- 4 files changed, 7 insertions(+), 28 deletions(-) diff --git a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md index beb7796d..bcd54fed 100644 --- a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md +++ b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md @@ -19,27 +19,18 @@ description: >- ## Absolute rules -- This skill runs FIRST. The moment you know you are going to create, edit, or - delete a frontend component (add/remove/rename props, change variants, states, - defaults, markup, or styling — or remove the component entirely), invoke this - skill **before** making the change, so the workflow below governs the change. -- After you create, modify, or delete a frontend component **in a project that - has Storybook**, you MUST create, update, or remove that component's Storybook - stories so they reflect the change. - You MUST NOT write or edit any `*.stories.*` file directly from here. All story work goes through the **`stories`** skill, which owns the strict, gated Storybook workflow. - You MUST NOT report a component change as complete until the corresponding story work has been handed off to the `stories` skill and finished. -- FOLLOW THE WORKFLOW SEQUENTIALLY -- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Workflow 1. Determine whether the project has Storybook. - If not installed go to "When Storybook is not installed" and stop here unless the user opts in. - - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. + - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. 2. Invoke the **`stories`** skill to create, update, or remove the stories for the component you just touched. Tell it which component changed and what changed (new component, new props, new variants, renamed states, deleted diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index 7da4eaa8..b3748d85 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -26,10 +26,10 @@ working around it. Treat any shortcut as a failure of this workflow. ## Absolute rules +- Commands must be run with the variable `STORYBOOK_FEATURE_AI_CLI=1` - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. -- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Step 0 — Prerequisites @@ -40,12 +40,9 @@ working around it. Treat any shortcut as a failure of this workflow. - Storybook must be a canary version (0.0.0-canary) or at least version 10.5. If an older version is installed, invoke the **storybook-upgrade** skill to upgrade it before proceeding. -- Storybook `.storybook/main.js` (or `main.ts`) must have `features.ai` enabled. ## Step 1 — Open the preview browser up front -MANDATORY REQUIREMENT BEFORE GOING TO STEP 2 - 1. Inspect `.claude/launch.json` for a launch entry that starts this project's Storybook dev server. If: - the `.claude/launch.json` file does not exist @@ -61,7 +58,7 @@ error. If launch setup reports an error, surface it to the user and STOP. ## Step 2 — Load the rules (before touching any story file) -- Run `npx storybook ai --help` to get all available subcommands and options. +- Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --help` to get all available subcommands and options. - Save the available subcommands and options in your working memory for reference. - Run the ai subcommand to get the story-writing instructions. - If the subcommand allows a port option, use the port you saved in Step 1. diff --git a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md index beb7796d..36a11db5 100644 --- a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md @@ -19,20 +19,11 @@ description: >- ## Absolute rules -- This skill runs FIRST. The moment you know you are going to create, edit, or - delete a frontend component (add/remove/rename props, change variants, states, - defaults, markup, or styling — or remove the component entirely), invoke this - skill **before** making the change, so the workflow below governs the change. -- After you create, modify, or delete a frontend component **in a project that - has Storybook**, you MUST create, update, or remove that component's Storybook - stories so they reflect the change. - You MUST NOT write or edit any `*.stories.*` file directly from here. All story work goes through the **`stories`** skill, which owns the strict, gated Storybook workflow. - You MUST NOT report a component change as complete until the corresponding story work has been handed off to the `stories` skill and finished. -- FOLLOW THE WORKFLOW SEQUENTIALLY -- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Workflow diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index 0ee309e8..af0c5dc3 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -16,10 +16,10 @@ working around it. Treat any shortcut as a failure of this workflow. ## Absolute rules +- Commands must be run with the variable `STORYBOOK_FEATURE_AI_CLI=1` - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. -- IGNORE LOCAL REGISTERED STORYBOOK MCP ## Step 0 — Prerequisites @@ -35,7 +35,7 @@ working around it. Treat any shortcut as a failure of this workflow. The Storybook preview MUST be running so the story can be verified. -Run `npx storybook ai instances ls` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. +Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai instances ls` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. If there is no running instance, start it with the steps below: 1. Start the project's existing Storybook dev script as a background task from the Storybook invocation directory @@ -47,7 +47,7 @@ error. If launch setup reports an error, surface it to the user and STOP. ## Step 2 — Load the rules (before touching any story file) -- Run `npx storybook ai --help` to get all available subcommands and options. +- Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --help` to get all available subcommands and options. - Save the available subcommands and options in your working memory for reference. - Run the ai subcommand to get the story-writing instructions. - Follow the instructions in the output, which will include the exact imports, structure, and conventions to use for the story you are writing or editing. The instructions are the ONLY acceptable source for how to write the story; do NOT rely on memory or existing patterns. @@ -64,7 +64,7 @@ rather than guessing. ## Step 4 — Preview and verify -Produce a preview for every story you touched with **preview-stories** (prefer +Produce a preview for every story you touched with **STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai preview-stories** (prefer `{ storyId }` inputs). Before showing any returned URL to the user, navigate to it in the preview browser and confirm the story renders without errors. From 46f90714be5b6b7d419524dc220b34c4e51d7d34 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Wed, 10 Jun 2026 17:01:42 +0200 Subject: [PATCH 04/10] fix: update skills --- packages/claude-plugin/skills/stories/SKILL.md | 4 ++-- .../codex-plugin/plugins/storybook/skills/stories/SKILL.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index b3748d85..acadcde8 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -60,7 +60,7 @@ error. If launch setup reports an error, surface it to the user and STOP. - Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --help` to get all available subcommands and options. - Save the available subcommands and options in your working memory for reference. -- Run the ai subcommand to get the story-writing instructions. +- Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --port ` to get the story-writing instructions. - If the subcommand allows a port option, use the port you saved in Step 1. - Follow the instructions in the output, which will include the exact imports, structure, and conventions to use for the story you are writing or editing. The instructions are the ONLY acceptable source for how to write the story; do NOT rely on memory or existing patterns. @@ -77,7 +77,7 @@ rather than guessing. ## Step 4 — Preview and verify -Produce a preview for every story you touched with **preview-stories** (prefer +Produce a preview for every story you touched with **STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai preview-stories** (prefer `{ storyId }` inputs). Before showing any returned URL to the user, navigate to it in the preview browser and confirm the story renders without errors. diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index af0c5dc3..b5d9e9ce 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -35,7 +35,7 @@ working around it. Treat any shortcut as a failure of this workflow. The Storybook preview MUST be running so the story can be verified. -Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai instances ls` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. +Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --help` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. If there is no running instance, start it with the steps below: 1. Start the project's existing Storybook dev script as a background task from the Storybook invocation directory From 5482c936b3f0f7a5795d67f56efbc6d236ffec4f Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Wed, 10 Jun 2026 17:13:53 +0200 Subject: [PATCH 05/10] fix: force claude to use CLI --- packages/claude-plugin/skills/stories/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index acadcde8..92745e00 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -30,6 +30,7 @@ working around it. Treat any shortcut as a failure of this workflow. - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. +- Ignore local Storybook MCP registrations. Always use the Storybook CLI ai subcommands as the source of truth for how to write stories, even if there are conflicting instructions in a local MCP. ## Step 0 — Prerequisites From a109a48ca2270b3b122cb828b2781821eac1e9d8 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Thu, 11 Jun 2026 11:35:27 +0200 Subject: [PATCH 06/10] feat: merge skills --- .../frontend-component-writing/SKILL.md | 81 ------------------- .../claude-plugin/skills/stories/SKILL.md | 77 ++++++++++++++---- .../frontend-component-writing/SKILL.md | 81 ------------------- .../plugins/storybook/skills/stories/SKILL.md | 59 +++++++++++--- 4 files changed, 111 insertions(+), 187 deletions(-) delete mode 100644 packages/claude-plugin/skills/frontend-component-writing/SKILL.md delete mode 100644 packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md diff --git a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md b/packages/claude-plugin/skills/frontend-component-writing/SKILL.md deleted file mode 100644 index bcd54fed..00000000 --- a/packages/claude-plugin/skills/frontend-component-writing/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: frontend-component-writing -description: >- - Invoke BEFORE you touch a frontend component, on EVERY change, with no - exception. Call this FIRST — before writing, editing, or deleting — so the - workflow governs how the change is made, not after the fact. Triggers on - creating, editing, OR deleting any frontend component (React/Vue/Svelte and - similar *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: - props, variants, states, markup, layout, styling, - CSS/Tailwind/styled-components, themes, tokens, icons, or assets. Invoke this - even if you believe the change is cosmetic-only, internal, a refactor, a - rename, a deletion, or has "no behavior change" — that judgment is NOT yours - to make here; the skill always runs first. Ensures every component - create/edit/delete is reflected in its Storybook stories by handing off to the - `stories` skill. ---- - -# Frontend Component Writing - -## Absolute rules - -- You MUST NOT write or edit any `*.stories.*` file directly from here. All story - work goes through the **`stories`** skill, which owns the strict, gated - Storybook workflow. -- You MUST NOT report a component change as complete until the corresponding - story work has been handed off to the `stories` skill and finished. - -## Workflow - -1. Determine whether the project has Storybook. - - If not installed go to "When Storybook is not installed" and stop here unless the user opts in. - - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. - - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. -2. Invoke the **`stories`** skill to create, update, or remove the stories for - the component you just touched. Tell it which component changed and what - changed (new component, new props, new variants, renamed states, deleted - component, etc.) so it can cover or clean up the affected surface. -3. Let the `stories` skill run its full gated workflow — including producing the - preview link — and surface that link in your final response. - -**Gate:** Do NOT consider the component task done until the `stories` skill has -completed its workflow for every component you created, modified, or deleted. A -component change without matching, verified stories is not a deliverable. - -## When Storybook is not installed - -Installing and configuring Storybook is invasive, so it is the **user's choice**. -Never set it up on your own initiative as a side effect of a component change. - -Before asking the user anything, check whether they have already declined: - -1. **Read the saved decision** at `.claude/storybook-optout.json` (project-local). - If it exists with `{ "storybookOptOut": true }`, the user has ALREADY refused - Storybook for this project. Do NOT ask again — silently skip all story work, - finish the component change, and move on. -2. **If there is no opt-out file**, briefly tell the user the project has no - Storybook and ask whether they want to set it up (and write stories) for it. -3. **If the user declines**, persist that choice so future invocations don't - re-ask: write `.claude/storybook-optout.json` with: - - ```json - { - "storybookOptOut": true, - "reason": "" - } - ``` - - Then finish the component change without any story work. - -4. **If the user opts in**, set Storybook up via the setup skills - (`storybook-init` / `storybook-setup`), then resume the Workflow above from - step 3. If an opt-out file existed from a previous "no", delete it. - -5. Once done, the user should have Storybook installed and configured, the component change - made, and the `stories` skill invoked to create/update/delete the relevant - stories with a verified preview link. - -**Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook -dependencies, or invoke the setup skills unless the user has explicitly opted in -this time. A saved opt-out MUST be respected on every later invocation without -re-prompting. diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index 92745e00..f3ad8dc7 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -1,22 +1,26 @@ --- name: stories description: >- - Write, create, update, or review Storybook stories. Use whenever the user asks - to write, add, or generate stories, to write Storybook stories for a component - or project, to cover a component with stories, or to create or edit any - *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue) — and on EVERY edit - to a frontend component, with no exception: its props, variants, states, - markup, layout, styling, CSS/Tailwind/styled, themes, tokens, icons, or - assets. Invoke this even if you believe the change is cosmetic-only, internal, - a refactor, or has "no behavior change" — that judgment is not yours to make; - the skill always runs. Also use before starting or previewing Storybook to - verify UI. + Invoke BEFORE you touch a frontend component, on EVERY change, with no + exception — call this FIRST, before writing, editing, or deleting, so the + workflow governs how the change is made. Triggers on creating, editing, OR + deleting any frontend component (React/Vue/Svelte and similar + *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: props, + variants, states, markup, layout, styling, CSS/Tailwind/styled-components, + themes, tokens, icons, or assets. Invoke this even if you believe the change + is cosmetic-only, internal, a refactor, a rename, a deletion, or has "no + behavior change" — that judgment is NOT yours to make; the skill always runs + first. Also use whenever the user asks to write, add, generate, update, or + review Storybook stories, to cover a component or project with stories, or to + create or edit any *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue), + and before starting or previewing Storybook to verify UI. --- # Storybook Stories The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill -is the **mandatory, ordered process** for working on them. +is the **mandatory, ordered process** for working on them, and for keeping +stories in sync with every frontend component you create, modify, or delete. This is a STRICT, GATED workflow. You MUST execute the steps below in order and satisfy each step's **Gate** before moving to the next. Do NOT skip, reorder, or @@ -31,17 +35,55 @@ working around it. Treat any shortcut as a failure of this workflow. `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. - Ignore local Storybook MCP registrations. Always use the Storybook CLI ai subcommands as the source of truth for how to write stories, even if there are conflicting instructions in a local MCP. +- When this skill runs because you created, modified, or deleted a component, + you MUST NOT report the component change as complete until this workflow has + finished for every component you touched. A component change without + matching, verified stories is not a deliverable. ## Step 0 — Prerequisites -- Storybook must be installed in the project. If it is not, invoke the - **storybook-init** skill to set it up, or ask the user if they want to set it - up before proceeding. If the user declines, STOP and report that Storybook is - required for story work. +- Storybook must be installed in the project. If it is not, go to + "When Storybook is not installed" below and stop here unless the user opts in. - Storybook must be a canary version (0.0.0-canary) or at least version 10.5. If an older version is installed, invoke the **storybook-upgrade** skill to upgrade it before proceeding. +### When Storybook is not installed + +Installing and configuring Storybook is invasive, so it is the **user's choice**. +Never set it up on your own initiative as a side effect of a component change. + +Before asking the user anything, check whether they have already declined: + +1. **Read the saved decision** at `.claude/storybook-optout.json` (project-local). + If it exists with `{ "storybookOptOut": true }`, the user has ALREADY refused + Storybook for this project. Do NOT ask again — silently skip all story work, + finish the component change (if any), and move on. +2. **If there is no opt-out file**, briefly tell the user the project has no + Storybook and ask whether they want to set it up (and write stories) for it. +3. **If the user declines**, persist that choice so future invocations don't + re-ask: write `.claude/storybook-optout.json` with: + + ```json + { + "storybookOptOut": true, + "reason": "" + } + ``` + + Then finish the component change (if any) without any story work. If the + user explicitly asked for story work, STOP and report that Storybook is + required for it. + +4. **If the user opts in**, set Storybook up via the setup skills + (`storybook-init` / `storybook-setup`), then resume this workflow from + Step 1. If an opt-out file existed from a previous "no", delete it. + +**Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook +dependencies, or invoke the setup skills unless the user has explicitly opted in +this time. A saved opt-out MUST be respected on every later invocation without +re-prompting. + ## Step 1 — Open the preview browser up front 1. Inspect `.claude/launch.json` for a launch entry that starts this project's Storybook dev server. @@ -71,7 +113,10 @@ you are not allowed to write a story yet — go back and call it now. ## Step 3 — Write the story -Create or edit the story strictly following the Step 2 instructions. +Create or edit the story strictly following the Step 2 instructions. When this +skill runs for a component change, cover the affected surface: new components +get stories, new props/variants/states get covered, renamed states get +updated, and deleted components get their stories removed. **Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. diff --git a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md deleted file mode 100644 index 36a11db5..00000000 --- a/packages/codex-plugin/plugins/storybook/skills/frontend-component-writing/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: frontend-component-writing -description: >- - Invoke BEFORE you touch a frontend component, on EVERY change, with no - exception. Call this FIRST — before writing, editing, or deleting — so the - workflow governs how the change is made, not after the fact. Triggers on - creating, editing, OR deleting any frontend component (React/Vue/Svelte and - similar *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: - props, variants, states, markup, layout, styling, - CSS/Tailwind/styled-components, themes, tokens, icons, or assets. Invoke this - even if you believe the change is cosmetic-only, internal, a refactor, a - rename, a deletion, or has "no behavior change" — that judgment is NOT yours - to make here; the skill always runs first. Ensures every component - create/edit/delete is reflected in its Storybook stories by handing off to the - `stories` skill. ---- - -# Frontend Component Writing - -## Absolute rules - -- You MUST NOT write or edit any `*.stories.*` file directly from here. All story - work goes through the **`stories`** skill, which owns the strict, gated - Storybook workflow. -- You MUST NOT report a component change as complete until the corresponding - story work has been handed off to the `stories` skill and finished. - -## Workflow - -1. Determine whether the project has Storybook. - - If not installed go to "When Storybook is not installed" and stop here unless the user opts in. - - If < 10.5 is installed, consider it too old. Run the upgrade skill to get it to 10.5+ before proceeding. - - If canary version (0.0.0-canary) of Storybook is installed, consider it compatible. -2. Invoke the **`stories`** skill to create, update, or remove the stories for - the component you just touched. Tell it which component changed and what - changed (new component, new props, new variants, renamed states, deleted - component, etc.) so it can cover or clean up the affected surface. -3. Let the `stories` skill run its full gated workflow — including producing the - preview link — and surface that link in your final response. - -**Gate:** Do NOT consider the component task done until the `stories` skill has -completed its workflow for every component you created, modified, or deleted. A -component change without matching, verified stories is not a deliverable. - -## When Storybook is not installed - -Installing and configuring Storybook is invasive, so it is the **user's choice**. -Never set it up on your own initiative as a side effect of a component change. - -Before asking the user anything, check whether they have already declined: - -1. **Read the saved decision** at `.claude/storybook-optout.json` (project-local). - If it exists with `{ "storybookOptOut": true }`, the user has ALREADY refused - Storybook for this project. Do NOT ask again — silently skip all story work, - finish the component change, and move on. -2. **If there is no opt-out file**, briefly tell the user the project has no - Storybook and ask whether they want to set it up (and write stories) for it. -3. **If the user declines**, persist that choice so future invocations don't - re-ask: write `.claude/storybook-optout.json` with: - - ```json - { - "storybookOptOut": true, - "reason": "" - } - ``` - - Then finish the component change without any story work. - -4. **If the user opts in**, set Storybook up via the setup skills - (`storybook-init` / `storybook-setup`), then resume the Workflow above from - step 3. If an opt-out file existed from a previous "no", delete it. - -5. Once done, the user should have Storybook installed and configured, the component change - made, and the `stories` skill invoked to create/update/delete the relevant - stories with a verified preview link. - -**Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook -dependencies, or invoke the setup skills unless the user has explicitly opted in -this time. A saved opt-out MUST be respected on every later invocation without -re-prompting. diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index b5d9e9ce..b5853b46 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -1,12 +1,13 @@ --- name: stories -description: Write, create, update, or review Storybook stories for a component or a whole project. Use whenever the user asks to write, add, or generate stories, to write Storybook stories for a component or project, to cover a component with stories, or to create or edit any *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue) — and on EVERY edit to a frontend component, with no exception: its props, variants, states, markup, layout, styling, CSS/Tailwind/styled, themes, tokens, icons, or assets. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, or has "no behavior change" — that judgment is not yours to make; the skill always runs. Also use before starting or previewing Storybook to verify UI. Pulls story-writing guidance from the Storybook MCP and keeps the preview running so stories can be verified. +description: Invoke BEFORE you touch a frontend component, on EVERY change, with no exception — call this FIRST, before writing, editing, or deleting, so the workflow governs how the change is made. Triggers on creating, editing, OR deleting any frontend component (React/Vue/Svelte and similar *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: props, variants, states, markup, layout, styling, CSS/Tailwind/styled-components, themes, tokens, icons, or assets. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, a rename, a deletion, or has "no behavior change" — that judgment is NOT yours to make; the skill always runs first. Also use whenever the user asks to write, add, generate, update, or review Storybook stories, to cover a component or project with stories, or to create or edit any *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue), and before starting or previewing Storybook to verify UI. Pulls story-writing guidance from the Storybook CLI ai subcommands and keeps the preview running so stories can be verified. --- # Storybook Stories The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill -is the **mandatory, ordered process** for working on them. +is the **mandatory, ordered process** for working on them, and for keeping +stories in sync with every frontend component you create, modify, or delete. This is a STRICT, GATED workflow. You MUST execute the steps below in order and satisfy each step's **Gate** before moving to the next. Do NOT skip, reorder, or @@ -20,17 +21,55 @@ working around it. Treat any shortcut as a failure of this workflow. - You MUST NOT write or edit a story from memory or existing patterns. The `get-storybook-story-instructions` output is the only acceptable source for imports, structure, and conventions. +- When this skill runs because you created, modified, or deleted a component, + you MUST NOT report the component change as complete until this workflow has + finished for every component you touched. A component change without + matching, verified stories is not a deliverable. ## Step 0 — Prerequisites -- Storybook must be installed in the project. If it is not, invoke the - **storybook-init** skill to set it up, or ask the user if they want to set it - up before proceeding. If the user declines, STOP and report that Storybook is - required for story work. +- Storybook must be installed in the project. If it is not, go to + "When Storybook is not installed" below and stop here unless the user opts in. - Storybook must be a canary version (0.0.0-canary) or at least version 10.5. If an older version is - installed, invoke the **storybook-upgrade** skill to upgrade it before + installed, invoke the **upgrade** skill to upgrade it before proceeding. +### When Storybook is not installed + +Installing and configuring Storybook is invasive, so it is the **user's choice**. +Never set it up on your own initiative as a side effect of a component change. + +Before asking the user anything, check whether they have already declined: + +1. **Read the saved decision** at `.claude/storybook-optout.json` (project-local). + If it exists with `{ "storybookOptOut": true }`, the user has ALREADY refused + Storybook for this project. Do NOT ask again — silently skip all story work, + finish the component change (if any), and move on. +2. **If there is no opt-out file**, briefly tell the user the project has no + Storybook and ask whether they want to set it up (and write stories) for it. +3. **If the user declines**, persist that choice so future invocations don't + re-ask: write `.claude/storybook-optout.json` with: + + ```json + { + "storybookOptOut": true, + "reason": "" + } + ``` + + Then finish the component change (if any) without any story work. If the + user explicitly asked for story work, STOP and report that Storybook is + required for it. + +4. **If the user opts in**, set Storybook up via the setup skills + (`init` / `setup`), then resume this workflow from + Step 1. If an opt-out file existed from a previous "no", delete it. + +**Gate:** Do NOT install Storybook, scaffold `.storybook/`, add Storybook +dependencies, or invoke the setup skills unless the user has explicitly opted in +this time. A saved opt-out MUST be respected on every later invocation without +re-prompting. + ## Step 1 — Guarantee a running preview browser The Storybook preview MUST be running so the story can be verified. @@ -57,7 +96,10 @@ you are not allowed to write a story yet — go back and call it now. ## Step 3 — Write the story -Create or edit the story strictly following the Step 2 instructions. +Create or edit the story strictly following the Step 2 instructions. When this +skill runs for a component change, cover the affected surface: new components +get stories, new props/variants/states get covered, renamed states get +updated, and deleted components get their stories removed. **Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. @@ -83,4 +125,3 @@ returns its `reviewUrl`. The review page IS the deliverable; the raw **Gate:** Do NOT report the task as done until `display-review` has succeeded, you have opened the returned `reviewUrl` in the preview browser, and that link is the final element of your user-facing response. - From 752837461f3608e6f875ea5ee123f5a51bcdcf11 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Thu, 11 Jun 2026 11:40:06 +0200 Subject: [PATCH 07/10] chore: reduce slightly the descriptions --- packages/claude-plugin/skills/stories/SKILL.md | 4 +--- .../codex-plugin/plugins/storybook/skills/stories/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index f3ad8dc7..1244d09c 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -5,9 +5,7 @@ description: >- exception — call this FIRST, before writing, editing, or deleting, so the workflow governs how the change is made. Triggers on creating, editing, OR deleting any frontend component (React/Vue/Svelte and similar - *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: props, - variants, states, markup, layout, styling, CSS/Tailwind/styled-components, - themes, tokens, icons, or assets. Invoke this even if you believe the change + *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, a rename, a deletion, or has "no behavior change" — that judgment is NOT yours to make; the skill always runs first. Also use whenever the user asks to write, add, generate, update, or diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index b5853b46..c57b4149 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -1,6 +1,6 @@ --- name: stories -description: Invoke BEFORE you touch a frontend component, on EVERY change, with no exception — call this FIRST, before writing, editing, or deleting, so the workflow governs how the change is made. Triggers on creating, editing, OR deleting any frontend component (React/Vue/Svelte and similar *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with: props, variants, states, markup, layout, styling, CSS/Tailwind/styled-components, themes, tokens, icons, or assets. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, a rename, a deletion, or has "no behavior change" — that judgment is NOT yours to make; the skill always runs first. Also use whenever the user asks to write, add, generate, update, or review Storybook stories, to cover a component or project with stories, or to create or edit any *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue), and before starting or previewing Storybook to verify UI. Pulls story-writing guidance from the Storybook CLI ai subcommands and keeps the preview running so stories can be verified. +description: Invoke BEFORE you touch a frontend component, on EVERY change, with no exception — call this FIRST, before writing, editing, or deleting, so the workflow governs how the change is made. Triggers on creating, editing, OR deleting any frontend component (React/Vue/Svelte and similar *.tsx/.jsx/.ts/.js/.vue/.svelte files) or anything it renders with. Invoke this even if you believe the change is cosmetic-only, internal, a refactor, a rename, a deletion, or has "no behavior change" — that judgment is NOT yours to make; the skill always runs first. Also use whenever the user asks to write, add, generate, update, or review Storybook stories, to cover a component or project with stories, or to create or edit any *.stories.* file (.stories.tsx/.ts/.jsx/.js/.svelte/.vue), and before starting or previewing Storybook to verify UI. Pulls story-writing guidance from the Storybook CLI ai subcommands and keeps the preview running so stories can be verified. --- # Storybook Stories From 8943ad1aee10255fdc36bbd77e898fd45b8d0b23 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Thu, 11 Jun 2026 11:41:35 +0200 Subject: [PATCH 08/10] chore: run fmt --- .../plugins/storybook/skills/stories/SKILL.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index c57b4149..0b79e869 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -76,10 +76,11 @@ The Storybook preview MUST be running so the story can be verified. Run `STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai --help` subcommand to check for running Storybook instances. If there is a running instance, note its port and open the preview URL in the preview browser. If there is no running instance, start it with the steps below: - 1. Start the project's existing Storybook dev script as a background task from - the Storybook invocation directory - 2. Wait for the terminal to show which port Storybook is running on and use that port to open the preview URL (e.g. `http://localhost:6006`) in the preview browser. - 3. Save the port being used by Storybook shown in the terminal in your working memory. USE THIS PORT FOR ANY SUBCOMMAND THAT NEEDS TO KNOW THE PORT (e.g. `preview-stories`). + +1. Start the project's existing Storybook dev script as a background task from + the Storybook invocation directory +2. Wait for the terminal to show which port Storybook is running on and use that port to open the preview URL (e.g. `http://localhost:6006`) in the preview browser. +3. Save the port being used by Storybook shown in the terminal in your working memory. USE THIS PORT FOR ANY SUBCOMMAND THAT NEEDS TO KNOW THE PORT (e.g. `preview-stories`). **Gate:** Do NOT proceed to Step 2 until the preview browser is open and has rendered the Storybook URL without error. If launch setup reports an error, surface it to the user and STOP. From a4552e78831ebd5f007ebb902ce146918201cba4 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Thu, 11 Jun 2026 12:09:21 +0200 Subject: [PATCH 09/10] chore: remove additionnal steps o follow only provided workflow by cli --- .../claude-plugin/skills/stories/SKILL.md | 22 ------------------- .../plugins/storybook/skills/stories/SKILL.md | 22 ------------------- 2 files changed, 44 deletions(-) diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index 1244d09c..57dda659 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -118,25 +118,3 @@ updated, and deleted components get their stories removed. **Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. - -## Step 4 — Preview and verify - -Produce a preview for every story you touched with **STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai preview-stories** (prefer -`{ storyId }` inputs). Before showing any returned URL to the user, navigate to -it in the preview browser and confirm the story renders without errors. - -**Gate:** Every URL you put in your final response MUST have been opened in the -preview browser first — no exceptions, per the Absolute rules. Do NOT report the -story as done until each preview link has been navigated and verified. - -## Step 5 — Publish the review page - -Once the stories render cleanly, call **display-review** so the user can review -exactly what changed in one place. This tool does NOT just return a link — it -publishes a curated **review page** inside the already-running Storybook and -returns its `reviewUrl`. The review page IS the deliverable; the raw -`preview-stories` URLs from Step 4 are for your own verification. - -**Gate:** Do NOT report the task as done until `display-review` has succeeded, -you have opened the returned `reviewUrl` in the preview browser, and that link is -the final element of your user-facing response. diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index 0b79e869..c49068ae 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -104,25 +104,3 @@ updated, and deleted components get their stories removed. **Gate:** Every story you touched must conform to the instruction output you received. If anything is unclear, re-read it rather than guessing. - -## Step 4 — Preview and verify - -Produce a preview for every story you touched with **STORYBOOK_FEATURE_AI_CLI=1 npx storybook ai preview-stories** (prefer -`{ storyId }` inputs). Before showing any returned URL to the user, navigate to -it in the preview browser and confirm the story renders without errors. - -**Gate:** Every URL you put in your final response MUST have been opened in the -preview browser first — no exceptions, per the Absolute rules. Do NOT report the -story as done until each preview link has been navigated and verified. - -## Step 5 — Publish the review page - -Once the stories render cleanly, call **display-review** so the user can review -exactly what changed in one place. This tool does NOT just return a link — it -publishes a curated **review page** inside the already-running Storybook and -returns its `reviewUrl`. The review page IS the deliverable; the raw -`preview-stories` URLs from Step 4 are for your own verification. - -**Gate:** Do NOT report the task as done until `display-review` has succeeded, -you have opened the returned `reviewUrl` in the preview browser, and that link is -the final element of your user-facing response. From bd9442ec779ce477ccdf3022750840c8ba9070d6 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Thu, 11 Jun 2026 13:50:32 +0200 Subject: [PATCH 10/10] feedbacks --- packages/claude-plugin/skills/stories/SKILL.md | 4 ---- .../plugins/storybook/skills/stories/SKILL.md | 8 ++------ 2 files changed, 2 insertions(+), 10 deletions(-) diff --git a/packages/claude-plugin/skills/stories/SKILL.md b/packages/claude-plugin/skills/stories/SKILL.md index 57dda659..64d1611c 100644 --- a/packages/claude-plugin/skills/stories/SKILL.md +++ b/packages/claude-plugin/skills/stories/SKILL.md @@ -16,10 +16,6 @@ description: >- # Storybook Stories -The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill -is the **mandatory, ordered process** for working on them, and for keeping -stories in sync with every frontend component you create, modify, or delete. - This is a STRICT, GATED workflow. You MUST execute the steps below in order and satisfy each step's **Gate** before moving to the next. Do NOT skip, reorder, or batch steps. Do NOT write or edit any `*.stories.*` file until Steps 1 and 2 are diff --git a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md index c49068ae..e87d33c4 100644 --- a/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md +++ b/packages/codex-plugin/plugins/storybook/skills/stories/SKILL.md @@ -5,10 +5,6 @@ description: Invoke BEFORE you touch a frontend component, on EVERY change, with # Storybook Stories -The Storybook CLI ai subcommands is the source of truth for _how_ to write stories. This skill -is the **mandatory, ordered process** for working on them, and for keeping -stories in sync with every frontend component you create, modify, or delete. - This is a STRICT, GATED workflow. You MUST execute the steps below in order and satisfy each step's **Gate** before moving to the next. Do NOT skip, reorder, or batch steps. Do NOT write or edit any `*.stories.*` file until Steps 1 and 2 are @@ -41,14 +37,14 @@ Never set it up on your own initiative as a side effect of a component change. Before asking the user anything, check whether they have already declined: -1. **Read the saved decision** at `.claude/storybook-optout.json` (project-local). +1. **Read the saved decision** at `.codex/storybook-optout.json` (project-local). If it exists with `{ "storybookOptOut": true }`, the user has ALREADY refused Storybook for this project. Do NOT ask again — silently skip all story work, finish the component change (if any), and move on. 2. **If there is no opt-out file**, briefly tell the user the project has no Storybook and ask whether they want to set it up (and write stories) for it. 3. **If the user declines**, persist that choice so future invocations don't - re-ask: write `.claude/storybook-optout.json` with: + re-ask: write `.codex/storybook-optout.json` with: ```json {