Storybook Skills Extractor：让 AI 真正理解你的组件库

一款将 Storybook 组件文档转换为 AI 可读格式的 CLI 工具

背景：AI 时代的组件库文档困境

在 AI 辅助编程日益普及的今天，开发者越来越依赖 Cursor、Claude 等 AI 工具来提升编码效率。然而，当我们让 AI 帮忙使用内部组件库时，经常会遇到这样的问题：

AI 不了解组件的正确用法，生成的代码无法运行

AI 无法获取最新的 Props 定义，导致参数错误

AI 不知道有哪些可用的组件变体和样式

究其原因，是因为 AI 无法有效读取和理解我们的组件文档。

Agent Skills：AI 理解能力的新标准

Agent Skills 是一个开放规范，旨在为 AI 代理提供新的能力和专业知识。它定义了一种结构化的文档格式，让 AI 能够：

按需加载：只获取当前需要的文档，而非全量读取

结构化理解：清晰的层级结构便于 AI 导航和检索

跨工具兼容：支持 Cursor、Claude 等主流 AI 开发工具

storybook-skills-extractor 正是为了解决这个问题而生——它能自动将你的 Storybook 文档转换为 Agent Skills 格式。

适用场景

🏢 设计系统团队

如果你的团队维护着一个内部设计系统或组件库，使用这个工具可以：

让团队成员在使用 AI 编程时获得准确的组件建议

减少因 AI「幻觉」导致的错误代码

提升整体开发效率和组件复用率

📦 开源组件库作者

如果你是开源组件库的维护者，这个工具可以帮助你：

为用户提供更好的 AI 辅助开发体验

让你的组件库在 AI 工具中「开箱即用」

提升组件库的竞争力和用户体验

🚀 前端开发团队

即使只是日常项目开发，你也可以：

为项目中的业务组件生成 AI 友好的文档

让新成员更快上手项目

建立团队级别的 AI 知识库

核心优势

1. 🔄 自动化提取

无需手动编写额外文档，直接从现有的 Storybook 构建产物中提取：

组件 Props 定义和类型信息

组件描述和使用说明

Story 示例代码

MDX 文档页面

2. 📋 标准规范

生成的文档严格遵循 Agent Skills 规范：


---
name: my-design-system
description: Complete usage guide for My Design System
license: MIT
---

# My Design System

## Components

- **Button** - 按钮组件 → [View Details](./references/components/button.md)
- **Input** - 输入框组件 → [View Details](./references/components/input.md)

3. 🎯 模块化设计

每个组件独立生成详细文档，AI 可按需加载：


skills/
└── my-component-library/
    ├── SKILL.md                 # 主导航文件
    └── references/
        ├── index.md             # 组件索引
        ├── components/
        │   ├── button.md        # Button 详细文档
        │   └── input.md         # Input 详细文档
        └── pages/
            └── getting-started.md

4. 🔧 灵活配置

支持命令行参数和配置文件两种方式：


// skills.config.js
module.exports = {
  distPath: 'storybook-static',
  skillName: 'My Design System',
  skillDescription: '设计系统组件库完整使用指南',
  license: 'MIT',
  metadata: 'version=1.0.0,author=Team',
};

实现原理揭秘

storybook-skills-extractor 的工作流程分为四个核心阶段：

阶段一：静态文件服务

工具使用 Playwright 的路由功能直接服务 Storybook 构建产物，无需启动额外的 Web 服务器：


await page.route('**/*', async route => {
  const filePath = resolveFilePath(route.request().url());
  const content = await readFile(filePath);
  await route.fulfill({ body: content });
});

这种方式比传统的 Express 服务器更可靠，避免了端口冲突等问题。

阶段二：Story Store 提取

Storybook 在客户端维护一个 Story Store，包含所有组件的元数据。工具通过 Playwright 在浏览器环境中访问这个内部数据结构：


const storeItems = await page.evaluate(async () => {
  const preview = window.__STORYBOOK_PREVIEW__;
  const storyStore = preview.storyStore || preview.storyStoreValue;

  await storyStore.cacheAllCSFFiles();
  return Object.values(storyStore.cachedCSFFiles);
});

这样可以获取到：

组件的 Props 定义（通过 __docgenInfo）

Story 的源代码

组件描述和文档

阶段三：MDX 内容转换

对于 MDX 格式的文档页面，工具会：

使用 Playwright 渲染 MDX 页面

提取 .sbdocs-content 区域的 HTML

使用 Turndown 库将 HTML 转换为 Markdown


const turndown = new Turndown({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
});
turndown.use([strikethrough, tables, taskListItems]);

阶段四：Skills 文件生成

最后，工具将提取的数据转换为 Agent Skills 格式：

SKILL.md：主导航文件，包含 YAML frontmatter 和组件列表

references/：每个组件的详细文档

index.md：完整的组件索引

快速开始

安装


npm install @acring/storybook-skills-extractor

使用


# 1. 先构建 Storybook
npm run build-storybook

# 2. 生成 Agent Skills
npx storybook-skills-extractor \
  --distPath "storybook-static" \
  --skillName "my-component" \
  --skillDescription "When using My Component, you can use the following components"

在 CI/CD 中集成


# GitHub Actions 示例
- name: Build Storybook
  run: npm run build-storybook

- name: Generate Agent Skills
  run: npx storybook-skills-extractor --config skills.config.js

- name: Upload Skills
  uses: actions/upload-artifact@v3
  with:
    name: agent-skills
    path: storybook-static/skills/

兼容性

Node.js: 16+

Storybook: 7.x 和 8.x

组件框架: React（支持 TypeScript Props 提取）

总结

storybook-skills-extractor 通过将 Storybook 文档转换为 Agent Skills 格式，架起了组件库与 AI 工具之间的桥梁。它让你无需额外工作，就能让 AI 真正理解你的组件库，从而生成更准确、更符合规范的代码。

在 AI 驱动开发日益普及的今天，让你的组件库「AI-ready」不再是可选项，而是提升开发效率的必备能力。

相关链接：

GitHub 仓库

NPM 包

Agent Skills 规范