storybook-skills-extractor

一个 CLI 工具，用于从 Storybook 构建产物中提取文档，并转换为 Agent Skills 格式，使 AI 智能体能够更好地理解和使用你的组件库。

概述

此工具处理 Storybook 生产构建，生成符合 Agent Skills 格式的结构化文档。它提取组件文档、属性、示例和 MDX 内容，创建一个 AI 智能体（如 Cursor、Claude 等）可以加载和使用的技能包，从而实现更准确的代码生成。

特性

• Agent Skills 格式: 生成符合 Agent Skills 规范的文档
• 组件文档: 从 React 组件中提取属性、描述和类型信息
• Story 示例: 捕获所有 story 变体及其源代码
• MDX 支持: 处理 MDX 文档页面并将 HTML 转换为 Markdown
• 子组件: 处理包含子组件的复杂组件
• 导航结构: 创建带有详细参考文件链接的 SKILL.md
• 静态文件服务: 使用 Playwright 路由替代 Express，提供更好的可靠性
• 灵活配置: 支持 CLI 参数和配置文件

安装

npm install @acring/storybook-skills-extractor
# 或
yarn add @acring/storybook-skills-extractor
# 或
pnpm add @acring/storybook-skills-extractor

使用方法

基本用法

从 Storybook 构建产物中提取文档：

storybook-skills-extractor --distPath "storybook-static" --skillName "我的组件库"

CLI 选项

| 选项 | 类型 | 必填 | 默认值 | 描述 | | -------------------- | ------ | ---- | -------- | ---------------------------------------------- | | --distPath | string | 是 | - | Storybook 构建目录的相对路径 | | --skillName | string | 是 | - | 生成的 Skill 名称 | | --skillDescription | string | 是 | - | Skill 的描述信息（最大 1024 字符，不能为空） | | --outputDir | string | 否 | skills | 生成技能的输出目录（相对于 distPath） | | --skillDir | string | 否 | (自动) | outputDir 下的子目录名称（默认为 skillName 的 kebab-case 形式） | | --skillPreamble | string | 否 | "" | 在 SKILL.md 开头添加的自定义前言文本（位于标题之后） | | --license | string | 否 | "" | 许可证名称或引用许可证文件 | | --compatibility | string | 否 | "" | 环境要求说明（最大 500 字符） | | --metadata | string | 否 | "" | 额外元数据，格式为逗号分隔的 key=value 对 | | --allowedTools | string | 否 | "" | 预批准的工具列表，空格分隔（实验性功能） |

Frontmatter 字段校验规则

生成的 SKILL.md 包含 YAML frontmatter，字段校验规则如下：

| 字段 | 必填 | 约束条件 | | --------------- | ---- | --------------------------------------------------------------------------- | | name | 是 | 最大 64 字符。只允许小写字母、数字和连字符。不能以连字符开头或结尾。 | | description | 是 | 最大 1024 字符。不能为空。描述技能的功能和使用场景。 | | license | 否 | 许可证名称或引用许可证文件。 | | compatibility | 否 | 最大 500 字符。环境要求（目标产品、系统包、网络访问等）。 | | metadata | 否 | 任意键值对映射，用于额外元数据。 | | allowed-tools | 否 | 预批准的工具列表，空格分隔。（实验性功能） |

配置文件

对于复杂的配置，你可以使用配置文件（例如 skills.config.js）：

module.exports = {
  distPath: 'storybook-static',
  skillName: 'My Design System',
  skillDescription: '我的设计系统组件库完整使用指南',
  outputDir: 'skills',
  skillDir: 'my-design-system', // 可选，默认为 skillName 的 kebab-case 形式
  skillPreamble: '这是 SKILL.md 开头的自定义前言文本。', // 可选，在 SKILL.md 开头添加的自定义前言
  license: 'MIT', // 可选，许可证名称
  compatibility: '需要 Node.js 18+', // 可选，环境要求
  metadata: 'version=1.0.0,author=Team', // 可选，额外元数据
  allowedTools: 'read_file write grep', // 可选，预批准的工具（实验性功能）
};

然后运行：

storybook-skills-extractor --config skills.config.js

输出结构

该工具会在你的 Storybook 构建目录中生成以下文件：

storybook-static/
└── skills/
    └── my-component-library/            # 子目录，由 skillDir 指定（或自动从 skillName 生成 kebab-case）
        ├── SKILL.md                     # 主导航文件（Agent Skills 格式）
        └── references/
            ├── index.md                 # 完整组件索引
            ├── components/
            │   ├── button.md            # Button 组件详细文档
            │   ├── input.md             # Input 组件详细文档
            │   └── ...
            └── pages/
                ├── getting-started.md   # MDX 页面文档
                └── ...

SKILL.md（主导航）

主 SKILL.md 文件作为 AI 智能体的导航索引：

---
name: my-design-system
description: 我的设计系统组件库完整使用指南
license: MIT
compatibility: 需要 Node.js 18+
metadata:
  version: 1.0.0
  author: Team
allowed-tools: read_file write grep
---

# My Design System

我的设计系统组件库完整使用指南

## Summary

此 Skill 提供组件库的完整使用指南。Agent 可以通过下方链接查看各组件和页面的详细文档。

## Components

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

## Index

[View Complete Component List](./references/index.md)

参考文件

每个组件都会在 references/ 目录中生成独立的详细文档文件：

# Button

按钮用于触发操作或事件。

## 属性

| 名称 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `appearance` | `"primary" | "secondary"` | 否 | `"secondary"` | 按钮外观 |

## 示例

### 主要按钮

```tsx
<Button appearance="primary">点击我</Button>

## 工作原理

1. **静态文件路由**: 使用 Playwright 提供 Storybook 文件服务，无需 Web 服务器
2. **Story 提取**: 访问 Storybook 的内部 story store 获取所有组件元数据
3. **内容处理**: 将 HTML 文档转换为简洁的 Markdown 格式
4. **Skills 生成**: 按照 Agent Skills 规范创建结构化文件

## 集成示例

### GitHub Actions

```yaml
- name: 构建 Storybook
  run: npm run build-storybook

- name: 生成 Agent Skills
  run: npx storybook-skills-extractor --distPath storybook-static --skillName "我的组件库"

使用 npm scripts

{
  "scripts": {
    "build:storybook": "storybook build",
    "build:skills": "storybook-skills-extractor --distPath storybook-static --skillName \"我的组件库\"",
    "build": "npm run build:storybook && npm run build:skills"
  }
}

开发

构建

npm run build

本地开发

# 本地链接包
npm link

# 在其他项目中使用
cd /path/to/your/storybook
npm link @acring/storybook-skills-extractor
storybook-skills-extractor --distPath storybook-static --skillName "测试"

环境要求

• Node.js 16+
• Storybook 7+（支持 Storybook 7 和 8）
• 已构建的 Storybook 静态文件

支持的格式

• 组件: 带有 TypeScript 属性的 React 组件
• Stories: CSF（Component Story Format）格式的 stories
• MDX: 使用 MDX 编写的文档页面
• 子组件: 复杂的组件层级结构

故障排除

常见问题

"Unable to find Storybook story store"（无法找到 Storybook story store）

• 确保你的 Storybook 构建已完成并包含必要的元数据
• 检查 distPath 路径是否正确

组件属性缺失

• 确保你的组件有正确的 TypeScript 类型定义
• 检查 Storybook 的 docgen 是否正常工作

Agent Skills 规范

本工具遵循 Agent Skills 规范，这是一个为 AI 智能体提供新能力和专业知识的开放标准。Agent Skills 已被领先的 AI 开发工具支持，包括 Cursor 和 Claude。

Agent Skills 格式的主要优势：

• 模块化: 每个组件都有独立的参考文件
• 高效: 智能体只加载所需的文档
• 可移植: 适用于支持该规范的不同 AI 工具
• 版本控制: Skills 可以与代码一起进行版本管理

许可证

MIT