企业官网建设流程全解析

Storybook 初始化 Skill（storybook-init）实战指南：三步为项目接入 Storybook 与 MCP

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

导读

storybook-init是 Storybook Claude Code 插件中负责"从零初始化"的入口技能（skill）：当一个项目尚未配置任何 Storybook 时，Agent 会调用该 skill，依次完成脚手架安装、MCP 插件接入，并把后续的项目级配置交接给storybook-setupskill。读完本文，你将掌握该 skill 的触发机制、每一步命令的精确写法与版本约束、它在整个插件技能体系中的分工，以及仓库中用于保证 skill 质量的测试与本地开发验证方式。

一、skill 是什么：插件体系中的自动化技能入口

在 code/lib/claude-plugin 目录下，Storybook 以 Claude Code 插件的形式向 Agent 暴露一组能力。插件的 README 明确指出：Agent 可以利用插件的 skills 和 tools 生成 UI、运行测试并在 Storybook 中预览成果。skills 是写入 Markdown 的"指令说明书"，Agent 在收到相关任务时会读取并遵循其中的步骤。

插件当前包含四个技能，分别对应一条完整的工作链：

• storybook-init（SKILL.md）：项目尚无 Storybook 时的初始化入口；
• storybook-setup（SKILL.md）：初始化完成后，为真实组件配置 preview 文件并编写 stories；
• stories（SKILL.md）：一切涉及 UI 改动的前置约束与工作流；
• storybook-upgrade（SKILL.md）：将现有 Storybook 升级到所需版本。

storybook-init处于链条最前端，其 frontmatter 中的触发描述非常明确："Use when adding Storybook to a project that does not have Storybook configured yet"（当项目尚未配置 Storybook、需要新增时使用）。这也意味着：如果项目已经存在.storybook/目录或package.json中的 Storybook 依赖，Agent 不应走这条路，而应转向storybook-upgrade或storybook-setup——这一判定逻辑在storybook-setup的前置条件中也有呼应。

二、步骤一：用脚手架命令完成初始化

skill 规定的第一步是在项目根目录运行：

npm create storybook@latest

这是 Storybook 官方脚手架命令。在 code/lib/create-storybook 包的 README.md 中可以看到同样的安装方式说明：

npm create storybook@latest

skill 特别强调：要根据项目实际使用的包管理器选择对应命令，例如：

# pnpm pnpm create storybook@latest # yarn yarn create storybook

版本前提：为什么提到@next

skill 中有一条容易被忽略但至关重要的版本约束：在 Storybook 10.6 正式发布之前，应运行npm create storybook@next。原因是本插件家族中的其他 skills（storybook-setup、stories、storybook-upgrade）都要求 Storybook 至少为 10.6 版本——storybook-init若初始化出旧版本，后续所有技能都将无法工作。

与之配套，storybook-upgradeskill 明确说明版本判定标准："10.6 未发布时，next满足要求（如10.6.0-alpha.x），任何 canary 构建（0.0.0-pr-*）也符合条件"。因此初始化时直接选择@next，可以避免后续反复升级。

三、步骤二：接入 @storybook/addon-mcp

初始化成功后，skill 要求立即执行：

npx storybook add @storybook/addon-mcp

这一步的作用是安装并注册 Storybook 的 MCP（Model Context Protocol）插件。在 code/addons/mcp 目录中可以找到该插件的源码与配套脚本（如scripts/generate-tools-api-doc.ts会同时覆盖插件 skills 与storybook aiCLI 的帮助输出），它向 Agent 暴露全部 Storybook MCP server 工具。插件 README 的 Tools 一节也印证了这一点：安装了插件之后，Agent 即可使用 Storybook MCP server 的全部工具集。

storiesskill 的前置条件进一步说明了该 addon 的必需性："确保@storybook/addon-mcp已安装，如果缺失，用npx storybook add @storybook/addon-mcp安装"——也就是说，即使在初始化之后的日常 UI 工作中，Agent 也会以此命令兜底校验 MCP 依赖。

四、步骤三：交接给 /storybook-setup

第三步是调用同级技能/storybook-setup，由它完成项目级配置：

• 确认 Storybook 已存在（检查package.json、.storybook/），否则回退到/storybook-init；
• 校验版本不低于 10.6；
• 在项目根目录（monorepo 中为 Storybook 所在包）运行npx storybook skills get setup，并严格按输出的 Markdown 执行，不自行替换计划。

storybook-setup的职责覆盖.storybook/preview.ts等配置文件，以及为多种组件类型编写 story 文件，其目标是"为 agentic 工作流配置好 Storybook，让组件能被正确渲染"。storybook-init的第三步本质是"交接棒"，把初始化之后的深水区工作交给专门的技能，避免 Agent 在初始化后自行猜测配置。

五、完整的调用链与命令工作目录约定

把三个步骤串联起来，storybook-init的实际效果等价于插件 README 中对init技能的描述："初始化 Storybook（即运行npm create storybook@latest）、安装@storybook/addon-mcp，然后运行 setup 技能。"

一个实操中容易踩坑的细节来自storiesskill 的工作目录约定：运行 Storybook dev server 和所有 Storybook CLI 命令时，都应使用同一工作目录——即安装 Storybook 的那个包（在 monorepo 中通常是packages/ui这样的叶子包）。这意味着npm create storybook@latest、npx storybook add ...、npx storybook skills get setup都应在该包目录下执行，而不是在 monorepo 根目录。

六、技能质量保障：仓库测试如何约束 skill

skill 不是普通的 Markdown 文档，它会被 Agent 读取并执行，因此仓库为它设计了自动化测试（code/lib/claude-plugin/plugin.test.ts），从侧面揭示了 skill 的工程约束：

1. 描述长度预算：Claude Code 在技能列表超出共享预算时，会"静默丢弃" skill 的描述，导致 Agent 只看到一个光秃秃的名字而不再调用它。测试以MAX_SKILL_DESCRIPTION_BYTES = 350为上限（实测约 384 UTF-8 字节是经验截断点），确保描述在插件繁多的环境中依然可见。storybook-init的 description 正是这样一句精炼的触发说明。
2. 跨插件一致性：测试会比对 Claude 插件与 Codex 插件的stories技能描述必须完全一致。
3. Marketplace 同步：测试校验包内与仓库根的.claude-plugin/marketplace.json内容同步，保证插件能通过统一入口被发现。

此外，插件本地的开发与验证流程见 code/lib/claude-plugin/LOCAL_DEVELOPMENT.md：在仓库根目录可用yarn workspace @storybook/claude-code-plugin run validate校验 marketplace 与插件清单，用yarn vitest run --project @storybook/claude-code-plugin跑上述测试（未安装 Claude CLI 时跳过），plugin:install则会把当前目录注册为本地 marketplace 并以用户级安装插件。

七、与相关 skills 的分工总结

结语

storybook-init是整个 Storybook Agent 工作流的地基：它以"初始化→接入 MCP→交接配置"三步走，把项目从零带入可被 Agent 驱动开发、测试与预览的状态。理解它的版本约束（10.6 /@next）、命令工作目录约定，以及仓库测试对 skill 的工程化约束，能帮助你在自己的项目中安全地复现这条链路，也可以作为自己编写 Agent skill 时"指令即代码、行为有测试"的参考范式。

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