shetengteng/skill-builder

Skill Builder

skillix-hub 项目中创建新 Skill 的标准化流程和脚手架工具。

脚手架工具

初始化新 Skill 的完整目录结构和模板文件：

node skills/skill-builder/scaffold.js init '{"name":"my-skill","tech":"node","description":"简短描述"}'

参数：

• name（必填）：小写字母+数字+连字符，如 web-content-reader
• tech：node（默认）、python 或其他（根据 Skill 需求选择最合适的技术栈）
• description：简短描述

生成的目录结构：

skills/<name>/          # Skill 源码
  SKILL.md, tool.js, package.json, lib/
design/<name>/          # 设计文档
  YYYY-MM-DD-01-设计文档.md
tests/<name>/           # 测试
  run_tests.js, src/unit/test_example.js, reports/

开发流程（10 阶段）

当用户要求创建新 Skill 时，严格按以下顺序执行每个阶段。

---

Phase 1：需求命名

目标：确认 Skill 名称、技术栈、使用场景。

执行步骤：

1. 根据用户描述的功能需求，给出 3-5 个命名推荐，每个附带简要理由：

   推荐命名：
   1. data-analyzer — 强调数据分析能力
   2. data-insight  — 强调洞察输出
   3. csv-parser    — 强调具体输入格式
   推荐：方案 1，最准确描述核心功能
   

2. 命名讨论（必须）：使用 AskQuestion 工具让用户从推荐中选择或自定义，同时确认：

   • Skill 名称
   • 技术栈（Node.js、Python 或其他，根据需求选择）
   • 核心功能描述
   • 使用场景（Agent 内部 / 用户手动 / 两者）

3. 命名规范（强制）：

   • 全小写，单词用连字符分隔
   • 描述性名称，避免 helper、utils 等模糊词
   • 名称应准确反映核心功能，不要太宽泛也不要太狭窄
   • 考虑未来扩展性：如 agent-interact 比 agent-dialog 更通用
   • 示例：web-content-reader、api-tracer、swagger-api-reader、agent-interact

4. 命名记录：将所有候选方案、选择理由记录在设计文档的 Phase 1 章节中

5. 运行脚手架初始化目录：

   node skills/skill-builder/scaffold.js init '{"name":"<name>","tech":"<tech>","description":"<desc>"}'
   

---

Phase 2：可行性分析

目标：在投入设计之前，快速验证 Skill 的技术可行性和实现路径。

路径规范：design/<name>/YYYY-MM-DD-NN-可行性分析.md

文档结构：

1. 需求摘要：一段话描述 Skill 要解决的核心问题
2. 技术可行性：
   • 关键技术点逐一分析（是否有成熟方案、是否需要外部依赖）
   • 已知限制和约束（平台、权限、性能等）
   • 原型验证（如有必要，附上关键代码片段或 PoC 结果）
3. 方案对比：至少 2 种实现路径，含优缺点对比表
4. 推荐方案：选定路径及理由
5. 风险评估：技术风险、依赖风险、维护风险
6. 结论：可行 / 有条件可行 / 不可行，附建议

执行要求：

• 一次性输出完整文档，不在对话中碎片化讨论
• 用户确认可行后再进入设计文档阶段
• 如果结论为"不可行"，与用户讨论替代方案

---

Phase 3：设计文档

目标：编写完整设计文档，包含技术方案和待讨论问题。

重要原则：

• 设计文档优先：不要在 Plan 模式下讨论方案，直接将所有方案、对比、问题写入设计文档
• 问题驱动：在文档末尾添加"待讨论问题"章节，列出需要用户确认的关键决策
• 一次性输出：先完成完整文档，再让用户审阅，避免碎片化讨论

路径规范：design/<name>/YYYY-MM-DD-NN-描述.md

• YYYY-MM-DD：当前日期
• NN：当天序号（01 起步）
• 示例：design/web-content-reader/2026-02-21-01-Web内容读取Skill设计文档.md

文档结构（参考 templates/design-doc.md.tpl）：

1. Phase 1 记录：命名候选方案、选择结果和理由
2. 需求：背景、目标、使用场景表格
3. 整体流程：Mermaid flowchart
4. 技术方案：至少 2 个方案对比，含优缺点和对比表
5. 推荐方案：架构图、CLI 命令设计、输出格式、目录结构
6. 实现计划：分 Phase 列出任务
7. 风险与注意事项：风险表格
8. 待讨论问题：列出需要用户确认的关键决策点（如技术选型、架构取舍等）

---

Phase 4：讨论迭代

目标：基于设计文档与用户确认方案。

执行步骤：

1. 不要切换到 Plan 模式，直接在对话中基于设计文档讨论
2. 使用 AskQuestion 工具让用户对"待讨论问题"逐一确认
3. 根据用户反馈直接修改设计文档
4. 迭代修改直到用户满意
5. 确认后进入代码开发阶段

---

Phase 5：代码开发

目标：实现 Skill 源码。

目录规范：

skills/<name>/
├── SKILL.md          # Skill 文档（Phase 完成后编写）
├── tool.js           # CLI 入口（Node.js）
├── main.py           # CLI 入口（Python）
├── package.json      # Node.js 依赖（Node.js 项目）
├── requirements.txt  # Python 依赖（Python 项目）
└── lib/              # 核心模块
    └── ...

根据选择的技术栈保留对应的入口文件和依赖文件。

CLI 入口规范：

# Node.js
node skills/<name>/tool.js <command> '<json_params>'

# Python
python3 skills/<name>/main.py <command> [--param value]

输出格式规范：所有命令返回 JSON 到 stdout：

{
  "result": { ... },
  "error": null
}

错误时：

{
  "result": null,
  "error": "error message"
}

编码规范：

• 模块化：每个功能一个文件放在 lib/ 下
• 不添加无意义注释
• 错误处理：所有命令 catch 异常返回 JSON error
• 长文本模板：代码中的长文本字符串（如生成的脚本、注入的 JS、Markdown 模板）必须提取到 templates/ 目录下，通过文件读取后替换占位符。不要在代码中内联大段模板字符串
• Node.js 项目使用 'use strict'
• Python 项目遵循 PEP 8 规范

install / update / uninstall 命令（强制）：

每个 Skill 必须实现 install、update 和 uninstall 命令，支持用户通过自然语言管理：

# Node.js
node skills/<name>/tool.js install '{"target":"~/.cursor/skills/<name>"}'
node skills/<name>/tool.js update '{"target":"~/.cursor/skills/<name>"}'
node skills/<name>/tool.js uninstall '{"target":"~/.cursor/skills/<name>"}'

# Python
python3 skills/<name>/main.py install --target ~/.cursor/skills/<name>
python3 skills/<name>/main.py update --target ~/.cursor/skills/<name>
python3 skills/<name>/main.py uninstall --target ~/.cursor/skills/<name>

install 命令要求：

1. 接受 target 参数，指定安装目标目录
2. 复制源码文件到目标目录（包括 SKILL.md、tool.js、package.json、lib/、templates/，排除 node_modules、dist、运行时数据）
3. 在目标目录执行依赖安装（如 npm install、pip install 等）
4. 如有前端构建（如 UI 目录），执行构建
5. 检查前置依赖是否存在，给出提示
6. 如有 rules/ 目录，安装规则文件到 ~/.cursor/rules/
7. 返回安装路径和依赖状态

update 命令要求：

1. 接受 target 参数
2. 备份用户数据（如工作流、配置、记忆数据等）
3. 删除旧版源码
4. 执行 install 逻辑
5. 恢复用户数据
6. 返回更新结果

uninstall 命令要求：

1. 接受 target 参数
2. 删除已安装的规则文件（如 ~/.cursor/rules/ 下的 .mdc 文件）
3. 询问是否保留用户数据（data 目录）
4. 删除安装目录
5. 返回卸载结果

SKILL.md 中必须包含安装/更新/卸载说明（根据技术栈选择对应命令）：

## 安装 / 更新 / 卸载

\`\`\`bash
# Node.js Skill
node skills/<name>/tool.js install '{"target":"~/.cursor/skills/<name>"}'
node skills/<name>/tool.js update '{"target":"~/.cursor/skills/<name>"}'
node skills/<name>/tool.js uninstall '{"target":"~/.cursor/skills/<name>"}'

# Python Skill
python3 skills/<name>/main.py install --target ~/.cursor/skills/<name>
python3 skills/<name>/main.py update --target ~/.cursor/skills/<name>
python3 skills/<name>/main.py uninstall --target ~/.cursor/skills/<name>
\`\`\`

自然语言管理示例（用户只需说）：

帮我从 https://github.com/shetengteng/skillix-hub 安装 <name> skill
帮我更新 <name> skill
帮我卸载 <name> skill

Agent 会自动克隆仓库并执行 install/update/uninstall 命令。

---

Phase 5.5：测试设计文档

目标：在编写测试代码之前，先编写测试设计文档，明确测试范围、用例和验证策略。

路径规范：

• tests/<name>/design/test-design.md

文档模板：

# <Name> Skill 测试设计

## 测试范围

| 模块 | 文件 | 说明 |
|------|------|------|
| response | lib/response.js | 标准输出格式 |
| ... | ... | ... |

## 测试用例

### 模块：<module>

| 用例 | 输入 | 预期输出 | 类型 |
|------|------|----------|------|
| 正常路径 | ... | ... | unit |
| 边界情况 | ... | ... | unit |
| 错误处理 | ... | ... | unit |

## 测试策略

- 沙箱隔离：所有文件操作在 testdata/runtime/ 下
- 模块覆盖：每个 lib/ 模块至少一个测试文件
- 依赖隔离：通过修改 config 模块路径实现

## 不测试的范围

- 需要真实浏览器的 Playwright 操作（集成测试阶段覆盖）
- 需要网络的 URL 采集（集成测试阶段覆盖）

要求：

• 在编写测试代码之前完成
• 列出所有需要测试的模块和用例
• 明确哪些是单元测试、哪些是集成测试
• 标注不测试的范围和原因

---

Phase 6：单元测试

目标：编写并运行单元测试。

路径规范：

• 测试设计：tests/<name>/design/test-design.md
• 测试文件：tests/<name>/src/unit/test_<module>.js
• 运行器：tests/<name>/run_tests.js

测试风格：

let passed = 0;
let failed = 0;

function assert(condition, msg) {
  if (condition) { passed++; console.log(`  PASS: ${msg}`); }
  else { failed++; console.error(`  FAIL: ${msg}`); }
}

// 每个用例为独立 async function test_xxx()
// main() 依次调用，最后打印结果
// 失败时 process.exit(1)

沙箱测试要求（强制）：

测试必须在沙箱环境中运行，绝不能在项目根目录下创建/修改文件。

• 测试目录下必须有 testdata/ 目录，用于存放测试数据和运行时沙箱
• 运行时沙箱创建在 tests/<name>/testdata/runtime/ 下，每次测试自动创建、测试后自动清理
• 如果被测代码使用硬编码路径（如 __dirname 推算项目根目录），必须支持通过环境变量（如 PROJECT_ROOT）覆盖，以便测试指向沙箱目录
• 测试中添加 .gitkeep 到 testdata/ 目录以确保 git 跟踪

const TESTDATA_DIR = path.resolve(__dirname, '../../testdata/runtime');

function makeSandbox(label) {
  const id = `${label}-${Date.now()}`;
  const dir = path.join(TESTDATA_DIR, id);
  fs.mkdirSync(dir, { recursive: true });
  return dir;
}

// 在 finally 中清理
fs.rmSync(sandbox, { recursive: true, force: true });

文件组织要求（强制）：

• 每个测试文件只测试一个模块：test_response.js 只测 response.js，test_store.js 只测 store.js
• 不要将多个模块的测试合并到一个文件中（如 test_example.js 测试所有模块）
• 文件命名：test_<module>.js，与被测模块名一一对应

覆盖要求：

• 每个 lib/ 模块至少一个测试文件
• 覆盖正常路径和边界情况

---

Phase 7：测试报告

目标：运行测试生成 Markdown 报告。

执行：

node tests/<name>/run_tests.js

报告路径：tests/<name>/reports/YYYY-MM-DD-NN-test-report.md

报告格式：

# <Name> Skill 测试报告

> 时间: YYYY-MM-DD HH:MM:SS
> 结果: PASSED/FAILED
> 耗时: X.XXXs

## 汇总
| 指标 | 数值 |
|---|---:|
| 总用例 | N |
| 通过 | N |
| 失败 | N |

## 单元测试
| 用例 | 状态 | 耗时 |
|---|---|---:|
| `test_xxx` | PASS | 0.XXs |

---

Phase 8：技术文档

目标：输出面向开发者的技术文档，详细说明代码结构、模块职责和数据流。

路径规范：design/<name>/YYYY-MM-DD-NN-技术文档.md

文档结构：

1. 概述：一段话描述 Skill 的技术架构
2. 代码结构：完整目录树 + 每个文件的职责说明
3. 核心模块：每个 lib/ 模块的 API 说明（函数签名、参数、返回值）
4. 数据流：从输入到输出的完整数据流图（文本或 Mermaid）
5. 配置项：所有可配置参数及默认值
6. 扩展指南：如何添加新功能（如新增交互类型、新增命令等）

执行要求：

• 代码开发完成后、README 同步前输出
• 内容基于实际代码，不是设计文档的复制
• 如果 Skill 包含前端（如 ui/ 目录），必须单独说明前端结构

---

Phase 9：README 同步

目标：更新项目 README 文件。

需要更新的文件：

1. README.md（中文）：

   • 在"可用 Skills"表格中新增一行
   • 在 Contributing 之前新增使用说明章节

2. README_EN.md（英文）：

   • 同步翻译上述内容

Skills 表格格式：

| [<name>](./skills/<name>/) | 简短描述 |

使用说明章节结构：

• 安装命令
• 核心工作流（代码示例）
• 参数说明表格
• 触发词列表

---

Phase 10：docs 同步

目标：更新 docs 展示页面数据。

每个 Skill 的数据存放在独立文件中，新增 Skill 需要 3 步：

Step 1：创建 docs/scripts/skills/<name>.js

/**
 * Skillix Hub - <Name> Skill Data
 */
window.SKILL_DATA_<NAME_UPPER> = {
    id: '<name>',
    name: '<name>',
    icon: '<icon>',  // lightbulb/document/chart/brain/globe/folder/code
    description: {
        zh: '中文描述',
        en: 'English description'
    },
    tags: [
        { zh: '标签', en: 'Tag' }
    ],
    features: [
        { zh: '功能', en: 'Feature' }
    ],
    scripts: ['tool.js'],
    version: '1.0',
    author: 'shetengteng',
    repo: 'https://github.com/shetengteng/skillix-hub/tree/main/skills/<name>',
    useCases: [
        {
            title: { zh: '标题', en: 'Title' },
            userInput: { zh: '用户输入', en: 'User input' },
            aiResponse: { zh: 'AI 响应', en: 'AI response' }
        }
    ]
};

其中 <NAME_UPPER> 是 skill id 的大写+下划线形式（如 web-content-reader → WEB_CONTENT_READER）。

Step 2：在 docs/index.html 中添加 script 引用（在 skills-data.js 之前）：

<script src="scripts/skills/<name>.js"></script>

Step 3：在 docs/scripts/skills-data.js 的 SKILL_KEYS 数组中添加变量名：

const SKILL_KEYS = [
    // ... 已有的 ...
    'SKILL_DATA_<NAME_UPPER>',
];

---

自然语言交互指南

| 用户说 | 执行 | |--------|------| | "创建一个新 skill" / "帮我写个 skill" | 从 Phase 1 开始，引导用户完成全流程 | | "初始化 skill 目录" | 运行 scaffold.js init | | "skill 开发流程是什么" | 展示 8 阶段流程 | | "skill 命名规范" | 展示命名规范 | | "设计文档模板" | 展示设计文档结构 | | "测试怎么写" | 展示测试风格和覆盖要求 |