How to use the Maintain Storybook agent skill (maintain-storybook)

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that an AI coding agent loads when a request matches its description. The file gives the agent a set of rules and steps to follow for one kind of task.

Storybook is a tool that shows UI components in isolation with sample data. This skill directs the agent to check that each story still matches the real product code and the project's feature documentation, to classify stories as current, proposed, historical or unreviewed, and to update fixtures and catalog metadata. It also reports upstream documentation drift to a separate verification skill, called maintain-verification-skill, instead of rewriting expected behaviour.

• Reconcile story drift against production components and the feature recipes.
• Classify stories explicitly as current, proposed, historical or unreviewed.
• Update fixtures, mocked API responses and catalog metadata for stories in scope.
• Keep the Storybook index and feature overview pages consistent with the upstream feature map.
• Report production bugs and upstream documentation drift rather than changing expected behaviour to match them.

Install the maintain-storybook skill

Download the ZIP for this skill from this page and unzip it. The skill folder contains agents/openai.yaml and SKILL.md. Place the unzipped folder in one of two locations, depending on how you want it available.

To make it available to all your projects, put it in your personal skills folder. To make it available only to one project, put it in that project's .claude/skills/ folder.

Alternatively, in the Claude apps you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/ (unzip so the maintain-storybook folder sits inside it).
• Project install: .claude/skills/ inside the Paperclip repository.
• Claude apps: Settings → Capabilities → Skills, then upload the skill.

Check the requirements before you start

The skill depends on files and tools inside the Paperclip repository. It will not work on an unrelated codebase, because it refers to paths such as maps/storybook-map, DESIGN.md and scripts/storybook-catalog.mjs, which are not included in this download.

The skill runs scripts, but it does not use the network. Scripts are run with Node.js, including node --test.

• Node.js, since the scripts run with node.
• The Paperclip repository, including scripts/storybook-catalog.mjs and the related check scripts.
• Storybook and Playwright tooling already set up in the repository.
• Git, used for diffs and history when choosing which subjects to review.

How to trigger the skill with natural requests

You do not need a special command. Describe the maintenance job in plain language, using the kinds of task the skill covers: reconciling story drift, classifying prototypes, updating fixtures, or maintaining feature coverage. Name the feature or capability when you can, because the skill follows capability IDs to catalog entries.

Keep requests targeted. The skill is designed not to turn a narrow request into an audit of the whole product.

• "Reconcile the Storybook stories for the approvals feature with the feature map."
• "Classify the prototype stories in the storybook catalog and mark anything without parity evidence as unreviewed."
• "Update the fixtures for the agent-run stories after the mocked API response shape changed."
• "Check which capabilities in the feature map have no current Storybook example."

What the agent does during a maintenance pass

For a targeted change, the agent follows the capability IDs to the matching catalog entries and shared dependencies. For a full inventory, it accounts for every configured story file, including historical examples. It starts by running the catalog script and records the source revision.

It then compares each affected story's rendered subject, props, fixture responses and assertions with the production implementation. It inspects mocked methods, payload shapes and error handling, and it does not replace errors with generic successful mocks to make a check pass.

Finally it regenerates the ignored indexes and runs the catalog checks. Its report names the files and capabilities that were corrected, retained, or still need review.

Safety notes: scripts and what they can and cannot prove

The skill runs local scripts and does not use the network. Review the scripts before running them in a repository you care about, as with any script an agent runs.

Passing catalog checks do not prove product correctness. The skill states that the checks validate local annotations, discovered inventory and references, not semantic parity or runtime health. Fixture interactions also do not establish production API, permission or provider behaviour. Review affected rendering with the review-storybook skill, and do not accept new screenshot baselines as part of a catalog cleanup.

• Scripts run with Node.js; the skill does not use the network.
• A passing check is not evidence that the product works.
• Screenshot baselines should not be accepted as part of a catalog cleanup.