# AI技能自动生成工具

`Agent技能` `代码助手` `自动化` `评估框架` `AI工作流`

# <img src="web/src/lib/assets/favicon.svg" width="32" height="32" align="center" alt="skill-maker logo"> skill-maker

一个用于创建其他 Agent 技能的 [Agent Skill](https://agentskills.io)。它引导 AI 编程助手完成完整的技能生命周期：捕获意图、起草 SKILL.md、通过子 Agent 运行评估循环、根据评分信号进行优化，以及优化描述以提高触发准确性。

**[访问 skill-maker.pages.dev](https://skill-maker.pages.dev)** 查看交互式工作原理概览、基准测试结果和快速安装命令。

评估循环是核心所在——它为每个测试用例生成独立的子 Agent，使用内置的 Bun TypeScript 脚本对断言进行评分，聚合基准测试数据，并持续迭代直到通过率趋于平稳（连续 3 次迭代的增量 < 2%）或达到 20 次迭代上限。

## 包含内容

```
skill-maker/
├── SKILL.md                        # 主技能指令
├── scripts/
│   ├── grade.ts                    # 对评估输出的断言进行评分
│   ├── aggregate-benchmark.ts      # 将评分聚合为 benchmark.json
│   ├── detect-plateau.ts           # 检测多次迭代中的通过率平稳
│   └── validate-skill.ts           # 根据规范验证 SKILL.md
├── references/
│   ├── schemas.md                  # 所有评估产物类型的 JSON Schema
│   └── spec-summary.md             # Agent Skills 规范的快速参考
├── assets/
│   └── skill-template.md           # 含 {{PLACEHOLDER}} 标记的起始模板
└── evals/
    └── evals.json                  # 含质量导向断言的测试提示
```

## 前置条件

- [Bun](https://bun.sh) — 运行所有内置脚本所必需

## 快速安装

```bash
npx skills add accolver/skill-maker
```

此命令会自动检测你的 AI 编程助手（Claude Code、Cursor、Windsurf、OpenCode 等），并将 skill-maker 安装到每一个。

### 安装选项

```bash
# 全局安装（用户级别，在所有项目中可用）
npx skills add accolver/skill-maker -g

# 仅安装到指定 Agent
npx skills add accolver/skill-maker --agent claude-code opencode

# 列出可用技能而不安装
npx skills add accolver/skill-maker --list
```

### 手动安装

如果不想使用 skills CLI：

```bash
git clone https://github.com/accolver/skill-maker.git
cd skill-maker
mkdir -p ~/.agents/skills
cp -r skill-maker ~/.agents/skills/skill-maker
```

### 验证安装

```bash
npx skills list
```

或运行内置验证器：

```bash
bun run skill-maker/scripts/validate-skill.ts skill-maker
```

## 使用方法

安装完成后，向你的编程助手发出创建技能的请求。该技能会在以下类型的提示下触发：

- "创建一个用于编写 git 提交信息的技能"
- "构建一个帮助数据管道验证的 SKILL.md"
- "为部署到 AWS 制作一个可复用的 Agent 工作流"
- "将这个调试流程打包为一个技能"

Agent 将自动遵循 5 个阶段的工作流：

1. **捕获意图** — 询问关于技能用途的澄清性问题
2. **起草** — 生成 SKILL.md、脚本、参考资料和资产文件
3. **评估循环** — 带/不带技能分别运行测试用例，对输出评分，检测平稳
4. **优化** — 根据失败的断言改进技能
5. **定稿** — 运行验证，优化描述，安装技能

## 基准测试结果

使用 skill-maker 构建的技能在 23 个领域与未经指导的 Agent 进行了对比评估。每个技能均经历完整的评估循环：独立的子 Agent 配对（有技能 vs 无技能）、断言评分，以及持续迭代直至平稳。

| 指标                     | 数值       |
| ------------------------ | ---------- |
| 评估技能数量             | 21         |
| 评估断言总数             | ~504       |
| 有技能通过率             | 100%       |
| 无技能平均通过率         | 37.1%      |
| **平均提升幅度**         | **+62.9%** |
| 达到 100% 的平均迭代次数 | 2.1        |

### 各技能结果

| 技能                      | 有技能 | 无技能 | 提升幅度   |
| ------------------------- | ------ | ------ | ---------- |
| nostr-client-patterns     | 100%   | 0%     | **+100%**  |
| nostr-social-graph        | 100%   | 0%     | **+100%**  |
| nostr-dvms                | 100%   | 0%     | **+100%**  |
| database-migration        | 100%   | 4.2%   | **+95.8%** |
| nostr-crypto-guide        | 100%   | 4.2%   | **+95.8%** |
| pdf-toolkit               | 100%   | 4.2%   | **+95.8%** |
| error-handling            | 100%   | 8.3%   | **+91.7%** |
| api-doc-generator         | 100%   | 16.7%  | **+83.3%** |
| pr-description            | 100%   | 20.8%  | **+79.2%** |
| changelog-generator       | 100%   | 20.8%  | **+79.2%** |
| nostr-marketplace-builder | 100%   | 25.0%  | **+75.0%** |
| monitoring-setup          | 100%   | 26.1%  | **+73.9%** |
| nostr-event-builder       | 100%   | 41.7%  | **+58.3%** |
| code-reviewer             | 100%   | 41.7%  | **+58.3%** |
| nostr-filter-designer     | 100%   | 54.8%  | **+45.2%** |
| gcp-foundation-fabric     | 100%   | 70.8%  | **+29.2%** |
| git-conventional-commits  | 100%   | 72.3%  | **+27.7%** |
| nostr-nip05-setup         | 100%   | 83.3%  | **+16.7%** |
| nostr-zap-integration     | 100%   | 91.7%  | **+8.3%**  |
| nostr-relay-builder       | 100%   | 95.8%  | **+4.2%**  |
| nostr-nip-advisor         | 100%   | 100%*  | 0%*        |

_*评分器启发式限制——详见 AGENTS.md。_

技能在以下场景中带来的价值最为突出：Agent 具备知识但缺乏结构——输出格式化、安全检查清单、全面覆盖以及特定约定的规则，在没有技能指导的情况下持续失败。

详细的各技能分析、收敛数据以及高价值技能使用场景的选择指南，请参见 [AGENTS.md](AGENTS.md)。

### 正面对决：skill-maker vs Anthropic 官方 skill-creator

我们将 skill-maker 与 [Anthropic 官方 skill-creator](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) 进行了基准对比，以评估哪种方案能生成更好的技能。两者均使用相同的领域简报，针对我们 3 个最高增益领域（database-migration、error-handling、pdf-toolkit）起草 SKILL.md，然后对相同的评估提示和断言（共 72 个）进行测试。

| 方案            | 通过数 | 总数 | 通过率    |
| --------------- | ------ | ---- | --------- |
| **skill-maker** | 72     | 72   | **100%**  |
| **官方方案**    | 67     | 72   | **93.1%** |

| 领域               | skill-maker  | 官方方案      | 差距   |
| ------------------ | ------------ | ------------- | ------ |
| database-migration | 24/24 (100%) | 21/24 (87.5%) | +12.5% |
| error-handling     | 24/24 (100%) | 22/24 (91.7%) | +8.3%  |
| pdf-toolkit        | 24/24 (100%) | 24/24 (100%)  | 0%     |

skill-maker 的优势来自**"常见错误"章节**（能捕获边界情况的防御性护栏）以及**基于推理的指令**（"因为 Y，所以做 X"，而非命令式的"做 X"）。官方方案有时能产出更好的工程建议（例如 PG15 专属优化），但这些建议会在保守的断言测试中失败。两种方案均表现强劲——5 个断言的差距相当微小，且存在争议空间。

完整的对比报告（含逐断言分析、失败原因分析和方法论说明）请参见[完整对比报告](workspaces/head-to-head/REPORT.md)。

### 自我评估

skill-maker 也对自身进行了测试（元评估）：

| 指标             | 分数   |
| ---------------- | ------ |
| 有技能通过率     | 100%   |
| 无技能通过率     | 57.3%  |
| 提升幅度         | +42.7% |
| 达到平稳的迭代   | 第 6 次 |

完整的迭代历史请参见 `workspaces/skill-maker-workspace/FINAL-BENCHMARK.md`。

## 许可证

MIT