企业官网建设流程全解析

Storybook Agentic Setup Skill 实战指南：让 AI Agent 自动生成可用的 preview 配置与组件 Stories

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

Storybook 10.6 起为 Claude Code 等 AI 编程助手提供了一套名为 skills 的指令化工作流，其中storybook-setup负责在 Storybook 已安装的前提下，为真实组件补齐可工作的preview文件与 stories。本文基于本仓库中 storybook-setup 的 SKILL.md 展开，结合其底层 CLI 实现与插件体系，讲解该 skill 的触发条件、执行流程、底层原理，以及它在 init / stories / upgrade 等 skill 协作中的定位，读完即可在自己的项目中让 Agent 正确完成 Storybook 的 agentic 配置。

Skill 是什么：Agent 可调用的指令化工作流

在 Storybook 的 Claude Code 插件体系中，每个 skill 是一个带 YAML frontmatter 的SKILL.md文件，frontmatter 中name定义 skill 名称、description描述其适用场景，正文则是 Agent 必须严格遵循的操作指令。插件安装后，这些 skill 便可供 Claude Code / Claude Desktop 中的 Agent 调用（既可在提示词中显式引用，也可由 Agent 在处理任务时自行调用），参见 code/lib/claude-plugin/README.md。

本仓库code/lib/claude-plugin/skills/下共定义了四个 skill，形成一个完整的 agentic 工作闭环：

按 storybook-init 的 SKILL.md 描述，init完成后会显式"Invoke the/storybook-setupskill"；而setup的前置条件不满足时又会让位给init或upgrade。因此storybook-setup处于"初始化之后、日常故事编写之前"的承上启下位置。

触发场景与前置条件（Prerequisites）

storybook-setup的description明确了它的适用边界：当 Storybook 已经安装，且用户希望获得一个可工作的preview文件、并为真实组件编写 stories 时使用。它不是初始化命令，也不是升级命令。

SKILL.md 正文列出了两条必须逐项核对的前置条件：

1. 确认 Storybook 确实存在：检查项目的package.json（依赖中应包含storybook/@storybook/*）以及.storybook/配置目录是否存在。若不存在，说明项目从未初始化过 Storybook，应切换至/storybook-init先完成初始化，而不是强行执行 setup。
2. Storybook 版本必须不低于 10.6：由于 10.6 发布前以 prerelease 形式存在，因此next通道（10.6.0-alpha.x）以及任何 canary 构建（版本号形如0.0.0-pr-*）均视为满足条件。若版本过旧、或需要先升级/修复，则切换到/storybook-upgrade——但有一个硬性约束：只有用户明确批准升级 Storybook 时才能执行升级。这一"先确认、再动手、升级需授权"的纪律贯穿整个插件体系，例如 stories 的 SKILL.md 同样声明"对于其他请求，仅在用户明确批准升级后才调用/storybook-upgrade"。

核心操作：运行npx storybook skills get setup

前置条件满足后，SKILL.md 给出唯一一条命令：

# 在项目根目录执行；monorepo 中则在安装 Storybook 的那个包（通常是叶子包，如 packages/ui）下执行 npx storybook skills get setup

并附有一条强约束指令："严格遵循打印出的 Markdown 输出，不要自行替换成你自己的计划"（Follow the printed Markdown precisely. Do not substitute your own plan.）。这是 agentic 工作流的关键设计：skill 本体只负责路由到正确的上下文，真正的、可执行的、项目定制的配置步骤由 CLI 根据当前项目探测结果动态生成，Agent 的角色是忠实执行而非自由发挥。

底层实现：CLI 如何动态生成 setup 指令

npx storybook skills命令的实现在 code/core/src/cli/skills/run.ts。其中runSkillsCommand对setup分支做了特殊处理：

• 与stories、write-story需要完整加载 Storybook 配置不同，setup只需要轻量的项目信息探测（getProjectInfo，配合resolveStorybookConfigDir解析配置目录），"它永远不需要为完整加载 Storybook 付费"（注释原文），因此执行更快速、失败路径更干净。
• 探测成功后将ProjectInfo交给getSetupMarkdown生成 Markdown 并原样输出（exitCode: 0）；若探测失败（例如目录不对、找不到配置），则返回一行精简错误信息而非原始 Node 堆栈，"一个用管道读取输出的 Agent 不应看到日常'目录搞错'场景下的裸堆栈"。
• skill 的合法 id 集合定义在 code/core/src/cli/skills/content/skills.ts：['stories', 'write-story', 'setup']，且注释明确这些 id 是公开的 CLI 词汇（插件桩会引用它们），重命名属于破坏性变更——这解释了为什么 SKILL.md 中写死的是skills get setup这一稳定接口。

setup 生成的指令包含什么：preview 与 stories 模板

setup 的 Markdown 生成逻辑位于 code/core/src/cli/skills/content/setup-prompts/（入口为index.ts，各变体文件如setup.ts、monorepo.ts、optimized-tests.ts、relaxed-limits.ts、pattern-copy-play.ts等对应不同的提示词实验变体）。以 setup-prompts/setup.ts 为例，生成的指令围绕两个核心产物展开：

1. 可工作的.storybook/preview文件

生成器会根据ProjectInfo中的hasCsfFactoryPreview与类型导入源（getTypeImportSource）输出两种风格的 preview 模板。经典 CSF 风格如下：

// .storybook/preview.tsx import type { Preview } from 'storybook/react'; // 类型导入源由 getTypeImportSource 按项目解析 import '../src/index.css'; // 导入全局样式 const preview: Preview = { decorators: [ (Story) => ( <ThemeProvider theme={theme}> <MemoryRouter> <Story /> </MemoryRouter> </ThemeProvider> ), ], }; export default preview;

若项目已采用 CSF Factory（hasCsfFactoryPreview为真），则输出基于definePreview的等价写法，并配套以import preview from '#.storybook/preview'开头的 story 模板。decorator 示例覆盖了真实项目中最常见的两类包装需求：主题上下文（ThemeProvider）与路由上下文（MemoryRouter），这正是一个可工作的 preview 文件在组件级预览时最容易缺失的部分。

2. 面向真实组件的 stories 模板

生成的 story 模板以'AI Generated/Simple/Button'这类命名空间组织，使用tags: ['ai-generated']标记来源，便于后续识别与批量管理：

import type { Meta, StoryObj } from 'storybook/react'; import { Button } from './Button'; const meta = { title: 'AI Generated/Simple/Button', component: Button, tags: ['ai-generated'], } satisfies Meta<typeof Button>; export default meta; type Story = StoryObj<typeof meta>; export const Default: Story = { args: { label: 'Click me' }, }; export const Disabled: Story = { args: { label: 'Disabled', disabled: true }, };

从 setup-prompts/index.ts 的目录结构可以推断，仓库对 setup 提示词存在多套实验变体（如针对 monorepo 的monorepo.ts、针对测试优化的optimized-tests.ts等），它们共同构成"setup 指令会随项目形态自适应"的机制。

与其他 skill 的协作编排

理解storybook-setup的最佳方式是把它放进整个 skill 编排链中：

• 前置链路：项目无 Storybook →/storybook-init（执行npm create storybook@latest后安装@storybook/addon-mcp，再调用/storybook-setup）；Storybook 过旧 → 用户批准后/storybook-upgrade。二者任一完成后都会回到/storybook-setup。
• 后置链路：setup 完成后，日常 UI 工作进入/stories的强制有序工作流。值得注意的衔接细节是，stories 的 SKILL.md 要求 Agent 在首次调用任何npx storybook tools命令前先以--help运行并通读输出——"工作流只点名命令，每个命令的参数形态与使用规则存在于各自的 help 输出中"；同时它要求从同一工作目录（monorepo 中即安装 Storybook 的包目录）运行 dev server 与所有 CLI 命令，这与storybook-setup中"在项目根目录（或 monorepo 中的 Storybook 包）运行"的指示完全一致。
• 版本门槛：setup、stories、init、upgrade四个 skill 共享同一个 10.6+ 版本门槛语义，storybook-upgrade 的 SKILL.md 将其描述为最终目标："Storybook 必须最终达到 10.6 或更高版本"。

在 Claude Code / Claude Desktop 中的落地路径

要让 Agent 实际具备调用这些 skill 的能力，需先安装插件（详见 code/lib/claude-plugin/README.md）：

# Claude Code claude plugin marketplace add storybookjs/storybook --scope user claude plugin install storybook@storybook --scope user claude plugin list # 确认插件可用

安装后，插件的全部技能（上述四个 skill）与 Storybook MCP server 的工具集对 Agent 开放；在 Claude Desktop 中，Agent 还会自动在 Agentic Development Environment（ADE）预览中打开相关 stories 供用户审阅。需要更新的场景下，由于插件尚未进入官方 marketplace，需先移除 marketplace 再重新安装。

小结：一条"轻量探测 + 动态生成 + 忠实执行"的 agentic 配置链路

storybook-setup的设计精髓可以概括为三点：

1. 职责单一：它只负责在 Storybook 已安装且版本达标（≥10.6）时触发，把环境缺失问题交给init、把版本问题交给upgrade，自身不做越界操作。
2. 动态生成：npx storybook skills get setup背后是 run.ts 的项目信息探测与 setup-prompts 的按项目形态定制，输出的 Markdown 不是静态文档，而是针对当前组件与配置目录的实操指令。
3. 忠实执行："Follow the printed Markdown precisely" 的指令意味着 Agent 的产出质量取决于 setup 输出与项目实际的一致性，这也正是该 skill 能在 eval 体系（本仓库 agent-eval 与 scripts/eval 目录可见其评测基建）中持续迭代、并用多套提示词变体做对比实验的原因。

对开发者而言，最直接的收益是：在已初始化 Storybook 的项目中，只需让 Agent 走一遍/storybook-setup，即可获得与真实组件匹配的 preview 装饰器与首批 stories，为后续的组件开发、测试与 AI 协作铺平道路。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook