How to use the Review Storybook agent skill

What the review-storybook skill makes the agent do

The skill is for reviewing a feature or change in the Paperclip user interface. The agent first finds the requested capability in the Storybook catalog's generated index, then checks the relevant feature recipe, the production source and the story before driving it.

The agent picks states that can actually distinguish a good change from a bad one: the normal action and result, relevant failures or retries, permission or gate presentation, and mobile or theme variants where they apply. It runs the stories, inspects the rendered output including errors and browser console output, and waits for story play assertions to finish.

The report keeps evidence separate. Render, interaction, visual comparison and production acceptance are reported on their own, and each selected case is marked passed, failed, blocked or not run. Catalog status from earlier reviews is treated as context, not as proof of the current revision.

• Records the revision, story ID, environment, and whether the subject was production or prototype
• Names omitted scope, so sampling is never described as full coverage
• Reports proven drift with exact source references and a proposed correction

Install the review-storybook skill

The skill ships as a folder containing SKILL.md and agents/openai.yaml. To install it, download the ZIP from the skill's page on this directory and unzip it into one of two places: ~/.claude/skills/ for your personal use, or a project's .claude/skills/ folder if you want it available only in that project.

You can also upload the ZIP in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload it there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Prepare your Paperclip checkout

The skill only works inside a checkout of the Paperclip repository, because it depends on that repository's Storybook catalog, maps, documentation paths and browser test suites. You need Node.js and pnpm installed. The skill uses the existing Storybook commands documented in the repository, namely pnpm build-storybook, or a Storybook dev server on an available local port that the review owns.

The visual comparison work expects a Playwright-style browser testing setup for the existing visual and focused browser suites.

• Node.js and pnpm
• A checkout of the Paperclip repository with its Storybook catalog, maps and browser test suites
• Playwright-style browser testing setup for the visual suite tests/storybook-visual/storybook-visual.spec.ts

Ask for a review with a natural request

You do not need a special command. Describe the change you want checked in plain language while you are working in the Paperclip repository, and mention that you want a Storybook review. The agent reads the skill description and decides to use it when the request matches.

Name the feature or change as specifically as you can. Say whether you care about errors, permissions, mobile layout or themes, because the agent chooses discriminating states based on what you describe. If you already know the story you care about, give its ID.

• Review the Paperclip agent settings change with Storybook, focusing on error and retry states
• Use the Storybook review skill to check the permission gate on the approvals screen, mobile and dark theme included
• Run a Storybook review of the new sidebar index and check that existing story links still work

Read the report the skill produces

Each case in the report lists the revision, story ID, environment, whether the subject was production or prototype, the simulated boundaries (such as mocked fetch handlers), the action and assertion, and the observed result. Evidence types are separated so a passing screenshot is not mistaken for a passing interaction test.

Visual regression proof depends on the published baseline manifest. The skill says an unpublished manifest blocks comparisons, and a macOS capture is useful inspection but not the Linux baseline. Backend persistence, real authorization and live provider behaviour are not signed off by this skill and must go to the production verification skill.

• Render: did the story display the subject correctly, without errors in the console
• Interaction: did the story's play assertions complete and show the expected result
• Visual comparison: only meaningful against the published Linux baseline
• Production acceptance: handled separately by the production verification skill