技能创建器 (skill-creator)

技能创建器（skill-creator）

概述

skill-creator 是用于创建、改进和测试 AI 技能的技能。它的核心是：帮助你从零创建新的 AI 技能，迭代优化，并量化评估技能表现。

作为 AI 开发者，你可能遇到过：

“我想创建一个专属 AI 技能，但不知道怎么开始”
“已有的技能效果不好，想改进”
“想测试技能效果，但不知道怎么量化评估”

skill-creator 就是解决这些的。

为什么需要技能创建器

1. 复用最佳实践

技能 = 最佳实践的封装

创建技能后：
- 团队成员可以直接使用
- 保证输出质量一致
- 减少重复工作

2. 量化评估

之前：
- "感觉效果还行"
- 主观判断，不可靠

之后：
- 量化指标
- 可对比
- 可追踪改进

3. 持续优化

技能创建是一个迭代过程：
- 创建 → 测试 → 评估 → 改进 → 重复
- 逐步接近完美

创建流程

第一步：理解意图

首先理解用户想要什么：

1. 这个技能让 AI 能做什么？
2. 什么时候触发？（用户说什么时）
3. 期望的输出格式是什么？
4. 需要测试用例吗？

检查点：
- [ ] 用户想实现什么？
- [ ] 触发条件是什么？
- [ ] 输出格式？
- [ ] 需要测试用例？

第二步：调研与访谈

主动询问：

1. 边界情况
2. 输入/输出格式
3. 示例文件
4. 成功标准
5. 依赖项

不要急着写，先问清楚！

第三步：编写 SKILL.md

技能文件结构：

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter (name, description)
│   └── Markdown 指令
└── Bundled Resources (可选)
    ├── scripts/    - 可执行脚本
    ├── references/ - 参考文档
    └── assets/     - 资源文件

第四步：编写测试用例

创建 2-3 个测试用例：

格式：
```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "用户的任务描述",
      "expected_output": "期望结果",
      "files": []
    }
  ]
}

原则：

真实场景
实际用户会说的话
包含文件名、上下文等细节

## 评估流程

### 1. 运行测试

同时运行两组测试：

A. 使用技能的版本 B. 不使用技能（baseline）

重要：

同时启动
同一prompt
便于对比

### 2. 量化评估

创建断言（assertions）：

好的断言：

客观可验证
描述性名称
易于理解

示例：

“输出包含关键词 X”
“生成的文件存在”
“代码可以运行”

### 3. 收集反馈

用户评估维度：

输出质量
完成度
格式正确性
改进建议

### 4. 迭代优化

改进循环：

分析反馈
识别问题
修改技能
重新测试
重复直到满意

## 技能结构详解

### Frontmatter

```yaml
---
name: skill-name
description: |
  技能描述：做什么的。
  触发条件：什么时候使用。
  确保描述稍微"强制"一点，
  以提高触发率。
---

编写模式

使用祈使句：

✅ 正确：
- "使用 XXX 格式"
- "先做 A，再做 B"

❌ 错误：
- "你可以考虑使用"
- "也许应该"

输出格式定义

## 输出格式
必须使用此模板：
# [标题]
## 摘要
## 详细内容

示例模式

## 提交信息格式
**示例：**
Input: 添加了用户认证
Output: feat(auth): 实现基于 JWT 的认证

渐进式披露

技能加载层级：

1. Metadata（name + description）
   - 始终在上下文 (~100词)

2. SKILL.md 正文
   - 触发时加载 (<500行)

3. Bundled resources
   - 按需加载（无限制）

测试用例设计

should-trigger 用例

应该触发技能的用例：

原则：
- 覆盖不同表述方式
- 正式/口语化都要有
- 包含不明显的情况

示例：
- "帮我处理这个 PDF"
- "老板让我把这个文档转成文字"
- "能从这个文件提取内容吗"

should-not-trigger 用例

不应该触发技能的用例：

原则：
- 相邻领域
- 模糊表述
- 关键字相似但需求不同

示例：
- "写一首关于 PDF 的诗"（不需要处理PDF）
- "给我讲个故事"（不需要文档处理）

描述优化

为什么重要

description 是触发的主要机制

AI 决定是否使用技能时：
- 只看到 name + description
- 描述越好，触发越准

优化步骤

1. 生成 20 个测试查询
   - 10 个应该触发
   - 10 个不应该触发

2. 混合 60% 训练 / 40% 测试

3. 运行优化循环（最多5次）

4. 选择测试集上表现最好的描述

实践案例

案例 1：创建 PDF 处理技能

需求：用户想要一个处理 PDF 的技能

步骤 1：理解意图

技能目标：提取 PDF 内容、转换格式
触发条件：用户提到 PDF、文档
输出：提取的文本/转换后的文件

步骤 2：编写 SKILL.md

---
name: pdf-processor
description: |
  处理 PDF 文档的技能。
  当用户提到 PDF、文档提取、PDF 转文字时使用。
  包括：读取、提取、转换 PDF 内容。
---

步骤 3：创建测试用例

{
  "evals": [
    {
      "prompt": "提取这个 PDF 的文字内容",
      "expected_output": "提取的文本"
    },
    {
      "prompt": "把 PDF 转成图片",
      "expected_output": "图片文件"
    }
  ]
}

案例 2：改进现有技能

场景：用户的代码审查技能效果不好

分析：

运行测试用例
收集用户反馈
识别问题：输出太简略

改进：

添加更详细的输出要求
增加示例
优化触发描述

验证：

重新运行测试
对比改进前后
量化改进效果

常见问题

Q1: 技能触发率低？

原因：description 不够"强制"

解决：
- 让描述更有针对性
- 添加更多触发关键词
- 提供具体场景

Q2: 测试效果不稳定？

原因：测试用例不够全面

解决：
- 增加测试用例数量
- 覆盖边界情况
- 多次运行取平均

Q3: 不知道如何评估？

原则：
- 客观可验证 → 量化评估
- 主观判断 → 用户反馈

结合使用：
- 量化指标（通过率、耗时）
- 用户主观评价

检查清单

创建前

明确技能目标
定义触发条件
确定输出格式
规划测试用例

创建中

使用标准结构
编写清晰的指令
提供示例
添加测试用例

创建后

运行测试
收集反馈
迭代优化
打包发布

速查卡片

核心流程

理解意图 → 编写技能 → 测试 → 评估 → 优化 → 打包

文件结构

SKILL.md + scripts/ + references/

测试要点

2-3 个测试用例
should-trigger / should-not-trigger
包含文件名、上下文

优化迭代

量化评估
用户反馈
描述优化