{"_id":"@acring/storybook-skills-extractor","name":"@acring/storybook-skills-extractor","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@acring/storybook-skills-extractor","description":"A CLI tool that extracts documentation from Storybook builds and converts it to Agent Skills format.","version":"1.0.0","type":"commonjs","bin":{"storybook-skills-extractor":"bin/storybook-skills-extractor.js"},"main":"./dist/src/index.js","typings":"./dist/src/index.d.ts","dependencies":{"@swc/helpers":"^0.5.1","playwright":"^1.49.1","tslib":"^2.7.0","turndown":"^7.2.0","turndown-plugin-gfm":"^1.0.2","yargs":"^17.7.2"},"scripts":{"build":"tsc -p tsconfig.lib.json","clean":"rm -rf dist","prebuild":"npm run clean"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^24.3.0","@types/turndown":"^5.0.5","@types/yargs":"^17.0.33","typescript":"^5.0.0"},"gitHead":"faf7a1832d0bb3dd92348e729ccfdf8dd542eb54","_id":"@acring/storybook-skills-extractor@1.0.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-SEiCEje154xqyj5y4kgXtzooOzsybZtIWAKtX7OEhtBl6PZvJwLMQvGaJGjA2GcKMoyNnNVUWIY9HEKdhzVEwg==","shasum":"882e18c7896cb876db6eef075651d488d8c293a2","tarball":"https://registry.npmjs.org/@acring/storybook-skills-extractor/-/storybook-skills-extractor-1.0.0.tgz","fileCount":23,"unpackedSize":240952,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBbMUf4lrBOCFoQPNwqcmEVOURRuHnfyKJr1K/EDNZT5AiEA0c6H1ppBd3p+yUH0gJCC2EWEfRlDDng39LyrhYEmN1I="}]},"_npmUser":{"name":"acring","email":"392398434@qq.com"},"directories":{},"maintainers":[{"name":"acring","email":"392398434@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storybook-skills-extractor_1.0.0_1769151673485_0.8126430340564916"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-23T07:01:13.303Z","1.0.0":"2026-01-23T07:01:13.636Z","modified":"2026-01-23T07:01:13.885Z"},"maintainers":[{"name":"acring","email":"392398434@qq.com"}],"description":"A CLI tool that extracts documentation from Storybook builds and converts it to Agent Skills format.","readme":"# storybook-skills-extractor\n\n一个 CLI 工具，用于从 Storybook 构建产物中提取文档，并转换为 [Agent Skills](https://agentskills.io/) 格式，使 AI 智能体能够更好地理解和使用你的组件库。\n\n## 概述\n\n此工具处理 Storybook 生产构建，生成符合 Agent Skills 格式的结构化文档。它提取组件文档、属性、示例和 MDX 内容，创建一个 AI 智能体（如 Cursor、Claude 等）可以加载和使用的技能包，从而实现更准确的代码生成。\n\n## 特性\n\n- **Agent Skills 格式**: 生成符合 [Agent Skills](https://agentskills.io/) 规范的文档\n- **组件文档**: 从 React 组件中提取属性、描述和类型信息\n- **Story 示例**: 捕获所有 story 变体及其源代码\n- **MDX 支持**: 处理 MDX 文档页面并将 HTML 转换为 Markdown\n- **子组件**: 处理包含子组件的复杂组件\n- **导航结构**: 创建带有详细参考文件链接的 SKILL.md\n- **静态文件服务**: 使用 Playwright 路由替代 Express，提供更好的可靠性\n- **灵活配置**: 支持 CLI 参数和配置文件\n\n## 安装\n\n```bash\nnpm install @acring/storybook-skills-extractor\n# 或\nyarn add @acring/storybook-skills-extractor\n# 或\npnpm add @acring/storybook-skills-extractor\n```\n\n## 使用方法\n\n### 基本用法\n\n从 Storybook 构建产物中提取文档：\n\n```bash\nstorybook-skills-extractor --distPath \"storybook-static\" --skillName \"我的组件库\"\n```\n\n### CLI 选项\n\n| 选项                 | 类型   | 必填 | 默认值   | 描述                                           |\n| -------------------- | ------ | ---- | -------- | ---------------------------------------------- |\n| `--distPath`         | string | 是   | -        | Storybook 构建目录的相对路径                   |\n| `--skillName`        | string | 是   | -        | 生成的 Skill 名称                              |\n| `--skillDescription` | string | 是   | -        | Skill 的描述信息（最大 1024 字符，不能为空）   |\n| `--outputDir`        | string | 否   | `skills` | 生成技能的输出目录（相对于 distPath）          |\n| `--skillDir`         | string | 否   | (自动)   | outputDir 下的子目录名称（默认为 skillName 的 kebab-case 形式） |\n| `--skillPreamble`    | string | 否   | `\"\"`     | 在 SKILL.md 开头添加的自定义前言文本（位于标题之后） |\n| `--license`          | string | 否   | `\"\"`     | 许可证名称或引用许可证文件                     |\n| `--compatibility`    | string | 否   | `\"\"`     | 环境要求说明（最大 500 字符）                  |\n| `--metadata`         | string | 否   | `\"\"`     | 额外元数据，格式为逗号分隔的 key=value 对      |\n| `--allowedTools`     | string | 否   | `\"\"`     | 预批准的工具列表，空格分隔（实验性功能）       |\n\n#### Frontmatter 字段校验规则\n\n生成的 SKILL.md 包含 YAML frontmatter，字段校验规则如下：\n\n| 字段            | 必填 | 约束条件                                                                    |\n| --------------- | ---- | --------------------------------------------------------------------------- |\n| `name`          | 是   | 最大 64 字符。只允许小写字母、数字和连字符。不能以连字符开头或结尾。        |\n| `description`   | 是   | 最大 1024 字符。不能为空。描述技能的功能和使用场景。                        |\n| `license`       | 否   | 许可证名称或引用许可证文件。                                                |\n| `compatibility` | 否   | 最大 500 字符。环境要求（目标产品、系统包、网络访问等）。                   |\n| `metadata`      | 否   | 任意键值对映射，用于额外元数据。                                            |\n| `allowed-tools` | 否   | 预批准的工具列表，空格分隔。（实验性功能）                                  |\n\n### 配置文件\n\n对于复杂的配置，你可以使用配置文件（例如 `skills.config.js`）：\n\n```javascript\nmodule.exports = {\n  distPath: 'storybook-static',\n  skillName: 'My Design System',\n  skillDescription: '我的设计系统组件库完整使用指南',\n  outputDir: 'skills',\n  skillDir: 'my-design-system', // 可选，默认为 skillName 的 kebab-case 形式\n  skillPreamble: '这是 SKILL.md 开头的自定义前言文本。', // 可选，在 SKILL.md 开头添加的自定义前言\n  license: 'MIT', // 可选，许可证名称\n  compatibility: '需要 Node.js 18+', // 可选，环境要求\n  metadata: 'version=1.0.0,author=Team', // 可选，额外元数据\n  allowedTools: 'read_file write grep', // 可选，预批准的工具（实验性功能）\n};\n```\n\n然后运行：\n\n```bash\nstorybook-skills-extractor --config skills.config.js\n```\n\n## 输出结构\n\n该工具会在你的 Storybook 构建目录中生成以下文件：\n\n```\nstorybook-static/\n└── skills/\n    └── my-component-library/            # 子目录，由 skillDir 指定（或自动从 skillName 生成 kebab-case）\n        ├── SKILL.md                     # 主导航文件（Agent Skills 格式）\n        └── references/\n            ├── index.md                 # 完整组件索引\n            ├── components/\n            │   ├── button.md            # Button 组件详细文档\n            │   ├── input.md             # Input 组件详细文档\n            │   └── ...\n            └── pages/\n                ├── getting-started.md   # MDX 页面文档\n                └── ...\n```\n\n### SKILL.md（主导航）\n\n主 SKILL.md 文件作为 AI 智能体的导航索引：\n\n```markdown\n---\nname: my-design-system\ndescription: 我的设计系统组件库完整使用指南\nlicense: MIT\ncompatibility: 需要 Node.js 18+\nmetadata:\n  version: 1.0.0\n  author: Team\nallowed-tools: read_file write grep\n---\n\n# My Design System\n\n我的设计系统组件库完整使用指南\n\n## Summary\n\n此 Skill 提供组件库的完整使用指南。Agent 可以通过下方链接查看各组件和页面的详细文档。\n\n## Components\n\n- **Button** - 按钮组件 → [View Details](./references/components/button.md)\n- **Input** - 输入框组件 → [View Details](./references/components/input.md)\n...\n\n## Index\n\n[View Complete Component List](./references/index.md)\n```\n\n### 参考文件\n\n每个组件都会在 `references/` 目录中生成独立的详细文档文件：\n\n```markdown\n# Button\n\n按钮用于触发操作或事件。\n\n## 属性\n\n| 名称 | 类型 | 必填 | 默认值 | 描述 |\n|------|------|------|--------|------|\n| `appearance` | `\"primary\" | \"secondary\"` | 否 | `\"secondary\"` | 按钮外观 |\n\n## 示例\n\n### 主要按钮\n\n```tsx\n<Button appearance=\"primary\">点击我</Button>\n```\n```\n\n## 工作原理\n\n1. **静态文件路由**: 使用 Playwright 提供 Storybook 文件服务，无需 Web 服务器\n2. **Story 提取**: 访问 Storybook 的内部 story store 获取所有组件元数据\n3. **内容处理**: 将 HTML 文档转换为简洁的 Markdown 格式\n4. **Skills 生成**: 按照 Agent Skills 规范创建结构化文件\n\n## 集成示例\n\n### GitHub Actions\n\n```yaml\n- name: 构建 Storybook\n  run: npm run build-storybook\n\n- name: 生成 Agent Skills\n  run: npx storybook-skills-extractor --distPath storybook-static --skillName \"我的组件库\"\n```\n\n### 使用 npm scripts\n\n```json\n{\n  \"scripts\": {\n    \"build:storybook\": \"storybook build\",\n    \"build:skills\": \"storybook-skills-extractor --distPath storybook-static --skillName \\\"我的组件库\\\"\",\n    \"build\": \"npm run build:storybook && npm run build:skills\"\n  }\n}\n```\n\n## 开发\n\n### 构建\n\n```bash\nnpm run build\n```\n\n### 本地开发\n\n```bash\n# 本地链接包\nnpm link\n\n# 在其他项目中使用\ncd /path/to/your/storybook\nnpm link @acring/storybook-skills-extractor\nstorybook-skills-extractor --distPath storybook-static --skillName \"测试\"\n```\n\n## 环境要求\n\n- Node.js 16+\n- Storybook 7+（支持 Storybook 7 和 8）\n- 已构建的 Storybook 静态文件\n\n## 支持的格式\n\n- **组件**: 带有 TypeScript 属性的 React 组件\n- **Stories**: CSF（Component Story Format）格式的 stories\n- **MDX**: 使用 MDX 编写的文档页面\n- **子组件**: 复杂的组件层级结构\n\n## 故障排除\n\n### 常见问题\n\n**\"Unable to find Storybook story store\"（无法找到 Storybook story store）**\n\n- 确保你的 Storybook 构建已完成并包含必要的元数据\n- 检查 `distPath` 路径是否正确\n\n**组件属性缺失**\n\n- 确保你的组件有正确的 TypeScript 类型定义\n- 检查 Storybook 的 docgen 是否正常工作\n\n## Agent Skills 规范\n\n本工具遵循 [Agent Skills](https://agentskills.io/) 规范，这是一个为 AI 智能体提供新能力和专业知识的开放标准。Agent Skills 已被领先的 AI 开发工具支持，包括 Cursor 和 Claude。\n\nAgent Skills 格式的主要优势：\n\n- **模块化**: 每个组件都有独立的参考文件\n- **高效**: 智能体只加载所需的文档\n- **可移植**: 适用于支持该规范的不同 AI 工具\n- **版本控制**: Skills 可以与代码一起进行版本管理\n\n## 许可证\n\nMIT\n\n","readmeFilename":"README.zh-CN.md","_rev":"1-e16fae736db7491cd9bc444a6ca9d6aa"}