Skip to main content
skill CX Codex

storybook-stories · oakoss — Claude Code skill: what it does, how to install

Writes Storybook stories and interaction tests in CSF3 format. Handles component examples, Chromatic visual snapshot setup, and accessibility checks.

MIT 124 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill storybook-stories -a claude-code
Open on GitHub

What storybook-stories does

This skill generates Storybook stories following CSF3 syntax. It applies the args object pattern for individual components and switches to custom render functions for multi-component layouts. Interaction testing runs inside the play function with userEvent actions and Testing Library queries, giving priority to accessible role lookups. It also configures Chromatic parameters for visual regression checks, including snapshot delays and skips.

The skill is limited to isolated UI development and does not handle end-to-end browser automation or API testing. When components render inside portals or run asynchronous animations, querying the standard canvas context directly fails, requiring body-level lookups and waitFor wrappers.

What it helps with

  • generate CSF3 component stories with typed args
  • write interaction tests using play functions and userEvent
  • set up Chromatic snapshot delays and capture rules
  • verify accessible names and labels across UI elements

Example prompts for the agent

  • Generate a CSF3 story for Button with a play function testing click events
  • Add Chromatic parameters to skip visual regression snapshots for Modal
  • Refactor interaction test queries from getByTestId to getByRole

How to install storybook-stories

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill storybook-stories -a claude-code

2Manually: put the files in place

~/.claude/skills/storybook-stories/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/storybook-stories/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about storybook-stories

How to install storybook-stories in Claude Code?

Run npx skills add oakoss/agent-skills --skill storybook-stories -a claude-code. The skill file is placed in ~/.claude/skills/storybook-stories/SKILL.md.

What does the storybook-stories skill do?

It writes CSF3 component stories, creates play function interaction tests with userEvent, and sets up Chromatic visual snapshot rules.

Can storybook-stories be used for end-to-end testing?

No, the skill only handles isolated component development. For end-to-end application journeys or API validation, tools like Playwright, Cypress, or Vitest are required.

Source text

SKILL.md · MIT
---
name: storybook-stories
description: 'Writes and maintains Storybook stories and interaction tests using CSF3 format. Covers component stories, play functions, visual regression testing with Chromatic, and accessibility testing. Use when creating component documentation, writing interaction tests, debugging test failures, configuring visual snapshots, or updating story structure. Use for CSF3, play functions, userEvent, Testing Library queries, Chromatic configuration, autodocs, MDX.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: https://storybook.js.org/docs
user-invocable: false
---

# Storybook Stories

## Overview

Storybook is a frontend workshop for building UI components in isolation. Stories are written in Component Story Format 3 (CSF3), which uses object syntax with `args` for type-safe component documentation and testing.

**When to use:** Component documentation with live examples, interaction testing with play functions, visual regression testing, accessibility validation, design system maintenance, isolated component development.

**When NOT to use:** End-to-end testing (use Playwright/Cypress), API integration testing (use Vitest/Jest), full application testing (use browser automation), performance testing (use Lighthouse/WebPageTest).

## Quick Reference

| Pattern                | API                                                    | Key Points                             |
| ---------------------- | ------------------------------------------------------ | -------------------------------------- |
| Basic story            | `export const Default: Story = { args }`               | Use args for simple single components  |
| Complex story          | `export const Example: Story = { render }`             | Use render for multi-component layouts |
| Meta configuration     | `const meta = { component, args } satisfies Meta`      | Define defaults and argTypes           |
| Interaction test       | `play: async ({ canvas, userEvent, args })`            | canvas and userEvent provided directly |
| User interaction       | `await userEvent.click(element)`                       | Always await userEvent methods         |
| Query elements         | `canvas.getByRole('button')`                           | Prefer getByRole over other queries    |
| Assertions             | `await expect(args.onPress).toHaveBeenCalled()`        | Use storybook/test assertions          |
| beforeEach hook        | `beforeEach: async ({ args }) => {}`                   | Setup mocks before story renders       |
| Play composition       | `await OtherStory.play?.(context)`                     | Reuse setup across stories             |
| Autodocs               | `tags: ['autodocs']`                                   | Enable automatic documentation         |
| Controls customization | `argTypes: { variant: { control: 'select' } }`         | Configure control panel                |
| Decorators             | `decorators: [withTheme]`                              | Add wrappers or context providers      |
| Parameters             | `parameters: { layout: 'centered' }`                   | Configure addon behavior per story     |
| Chromatic snapshot     | `parameters: { chromatic: { delay: 300 } }`            | Control visual regression captures     |
| Disable snapshot       | `parameters: { chromatic: { disableSnapshot: true } }` | Skip story in visual tests             |
| A11y testing           | `await expect(button).toHaveAccessibleName()`          | Validate accessible labels             |

## Common Mistakes

| Mistake                                    | Correct Pattern                                          |
| ------------------------------------------ | -------------------------------------------------------- |
| Using args with multi-component layouts    | Use render for complex compositions                      |
| Not awaiting userEvent methods             | Always await: `await userEvent.click(button)`            |
| Using within(canvasElement) manually       | Destructure `canvas` from play context directly          |
| Using getByTestId first                    | Prefer getByRole, getByLabelText, getByText              |
| Missing default args at meta level         | Add args to meta to prevent placeholder controls         |
| Exposing non-serializable props            | Disable className, ref, style in argTypes                |
| Not composing play functions               | Reuse setup with `await BaseStory.play?.(context)`       |
| Forgetting to mock callbacks               | Use `fn()` for event handlers: `args: { onPress: fn() }` |
| Missing accessible names for icon buttons  | Add aria-label or use aria-labelledby                    |
| Not scoping queries for portal content     | Use `within(canvasElement.ownerDocument.body)`           |
| Using boolean && for conditional rendering | Use ternary in stories for consistent snapshots          |
| Not waiting for animations                 | Wrap assertions in waitFor for async state               |

## Common Fixes

| Problem                    | Solution                                        |
| -------------------------- | ----------------------------------------------- |
| Controls show placeholders | Add `args` at meta level with default values    |
| Serialization error        | Disable `className`, `ref`, `style` in argTypes |
| Portal element not found   | Search `body` instead of `canvas`               |
| Animation timing issues    | Wrap assertions in `waitFor`                    |
| Multiple buttons found     | Add `{ name: '...' }` to getByRole              |
| A11y test failing          | Add `label` prop or `aria-label`                |

## Delegation

- **Story structure review**: Use `code-reviewer` skill for CSF3 pattern validation
- **Accessibility audit**: Use `Explore` agent to discover ARIA patterns across stories
- **Visual regression analysis**: Use `Task` agent to investigate Chromatic failures

## References

- [Story writing patterns and CSF3 syntax](references/story-writing.md)
- [Interaction tests with play functions](references/interaction-tests.md)
- [Component documentation and controls](references/component-documentation.md)
- [Visual testing with Chromatic](references/visual-testing.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

storybook-stories by other authors comes first.

storybook-stories Pedro Nauck Writes and edits Storybook stories the way your repo already does it. Handy once a project has plenty of stories and the naming rules live only in people's heads. CX Codex +1 317installs storybook-story-writing TheBushidoCollective storybook-story-writing writes and edits Storybook stories for your components: CSF3 format, every meaningful state, a build that passes. Useful when stories drift and break the build. CX Codex +1 680installs storybook-testing OrchestKit The storybook-testing Claude Code skill guides component testing in Storybook 10. It covers story authoring, visual checks, CI setup, and migration from Storybook 9. CX Codex +1 224installs format-storybook podo format-storybook keeps Storybook files in one shape across a component library: stories beside components, a shared template, args and controls, MDX docs. CX Codex +1 213installs writing-react-native-storybook-stories storybookjs writing-react-native-storybook-stories teaches the agent to write and edit React Native stories in CSF: args, argTypes, decorators, addon parameters and portable stories for testing. CX Codex +1 722installs storybook-play-functions TheBushidoCollective Guides AI assistants in writing Storybook play functions for interaction testing using @storybook/test utilities. CX Codex +1 119installs storybook Mindrally Enforces Storybook best practices for component libraries, covering file structure, autodocs, controls, and interaction tests. CX Codex +1 970installs

From the same set106

The whole set →
tanstack-pacer Hands your agent a map of TanStack Pacer: debouncing, throttling, rate limits and async queues, with the matching React hooks. Useful when a handler fires too often. CX Codex +1 126installs tanstack-devtools tanstack-devtools guides AI coding agents in configuring Query cache, Router, and Form debugging panels across React applications. CX Codex +1 125installs seo-optimizer seo-optimizer — an SEO architecture skill: JSON-LD entities, E-E-A-T signals, topic clusters and a 30-point content audit. Runs in Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. CX Codex +1 125installs performance-optimizer performance-optimizer provides structured workflows for profiling, caching, and full-stack performance tuning. Helps eliminate slow database queries, optimize bundles, and reduce API latency. CX Codex +1 124installs shell-integration The shell-integration Claude Code skill provides terminal integration guides and Bash, Zsh, and Fish patterns for completions, prompt hooks, and portable POSIX wrappers. CX Codex +1 123installs usability-tester usability-tester plans usability test sessions, evaluates interfaces against heuristic standards, and scores UX friction points using severity formulas. CX Codex +1 122installs react-email Build responsive HTML emails from React Email components and render them as HTML or plain text. Useful for transactional messages and marketing templates. CX Codex +1 122installs rag-implementer rag-implementer guides an agent through a retrieval-augmented generation build, from chunking and embeddings to hybrid retrieval and quality metrics. CX Codex +1 121installs

Project sponsors

Companies that keep this analytics open