前言¶

Agent Skills 正在快速普及：Cursor、Claude Code、Codex CLI 等 AI 编程工具都支持用 SKILL.md 把领域知识打包成可复用能力。但很多人第一次动手时会卡在几个地方——不知道 description 该怎么写才能被正确触发、写好的 Skill 没有测试手段、改了几版也不确定是否真的更好。

Anthropic 在开源仓库 anthropics/skills 里提供了一个专门解决这些问题的 Skill：skill-creator。它本身也是一个 Skill，但职责是「教你怎么写 Skill、怎么测 Skill、怎么迭代 Skill」。如果你打算系统入门 Agent Skills，从这里开始比直接啃文档更高效。

这是什么¶

skill-creator 是 Anthropic 出品的 Agent Skill「元技能」——不直接帮你写业务代码，而是引导你完成 Skill 从构思、起草、评测到优化的完整闭环。

它的核心定位可以用官方 description 概括：

创建新 Skill、修改和优化已有 Skill，并通过 eval 评测与基准测试衡量 Skill 性能。适用于从零创建 Skill、编辑优化现有 Skill、运行 eval 测试、做方差分析基准测试，或优化 description 以提升触发准确率。

Agent Skills 采用通用的 SKILL.md 格式：YAML frontmatter 声明元数据，Markdown 正文写操作指引，可选附带 scripts/、references/、assets/ 等资源目录。Claude Code、Cursor 等工具在会话启动时加载各 Skill 的 name 与 description，在任务匹配时按需读取完整 SKILL.md——这就是官方文档所说的「渐进式披露」（Progressive Disclosure）。skill-creator 正是围绕这套机制，帮你把 Skill 写「对」、测「准」、改「稳」。

核心功能与亮点¶

1. 结构化创建流程¶

skill-creator 把 Skill 开发拆成可执行的步骤：

1. Capture Intent（捕获意图）：明确 Skill 要做什么、何时触发、输出格式是什么，以及是否需要测试用例。
2. Interview and Research（访谈与调研）：主动追问边界情况、依赖和成功标准；可借助 MCP 或联网检索类似 Skill 与最佳实践。
3. Write the SKILL.md：按规范填写 name、description 和正文指令。

其中 description 是触发机制的关键——官方建议把「做什么」和「什么时候用」都写进 description，而不是正文；并适当「积极」一些，以对抗模型「undertrigger」（该用却不用）的倾向。

2. Skill 目录规范与写作指南¶

skill-creator 内置了 Skill 解剖结构与写作模式，标准目录如下：

skill-name/
├── SKILL.md          # 必需：frontmatter + 指令正文
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需加载的参考文档
└── assets/           # 可选：模板、图标等输出资源

关键原则包括：

• 渐进式披露：元数据常驻上下文（约 100 tokens），正文在触发时加载（建议 SKILL.md 正文控制在 500 行以内），资源文件按需读取。
• 按领域拆分 references：多框架/多云场景用 references/aws.md 等形式组织，避免一次性塞满上下文。
• 解释「为什么」：比起堆砌 MUST/NEVER，更推荐说明理由，让模型理解意图后灵活执行。
• 不惊喜原则：Skill 内容不得包含恶意代码或与描述不符的行为。

3. Eval 评测与基准测试¶

这是 skill-creator 区别于普通文档的最大亮点。它提供一套完整的评测工作流：

测试用例：保存到 evals/evals.json，每条包含 prompt、期望输出描述和可选输入文件：

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "用户的任务提示词",
      "expected_output": "期望结果的描述",
      "files": []
    }
  ]
}

并行对比运行：对每个测试用例，同时启动「有 Skill」和「无 Skill（baseline）」两次运行——新建 Skill 时 baseline 是无 Skill；改进已有 Skill 时 baseline 是旧版本快照。结果按迭代目录组织：

<skill-name>-workspace/
├── iteration-1/
│   ├── eval-0/
│   │   ├── with_skill/outputs/
│   │   └── without_skill/outputs/
│   └── benchmark.json
└── iteration-2/
    ...

量化断言（assertions）：对可客观验证的输出（文件格式、数据提取、固定流程步骤）编写断言；主观类 Skill（文风、设计审美）则侧重人工评审。

基准聚合：运行聚合脚本生成 pass rate、耗时、token 用量及均值 ± 标准差：

python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>

可视化评审：通过 eval-viewer/generate_review.py 启动浏览器评审界面（Outputs 与 Benchmark 两个 Tab），用户逐条查看输出并填写反馈；无图形界面时可用 --static 生成独立 HTML 文件。

4. Description 触发优化¶

Skill 是否被调用，很大程度取决于 frontmatter 里的 description。skill-creator 提供专门的优化循环：

1. 生成约 20 条触发测试 query（含应触发与不应触发的「近义干扰」样本）。
2. 用户通过 HTML 模板审核 eval 集。
3. 运行优化脚本（最多 5 轮迭代，60% 训练 / 40% 留出测试）：

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id> \
  --max-iterations 5 \
  --verbose

脚本会评估当前 description 的触发率，让 Claude 提出改进方案，最终选出测试集得分最高的 best_description。

5. 打包分发¶

Skill 定稿后可打包为 .skill 文件便于安装：

python -m scripts.package_skill <path/to/skill-folder>

安装与启用¶

skill-creator 来自 Anthropic 开源仓库，需先克隆或下载对应目录：

git clone https://github.com/anthropics/skills.git
cp -r skills/skills/skill-creator ~/.claude/skills/skill-creator

各 AI 编程工具的安装位置略有不同（均以「Skill 目录 + SKILL.md」为最小单元）：

Claude Code 中 Skill 会在匹配 description 时自动加载，也可通过 /skill-creator 直接调用。Cursor 中可在 Agent 对话里提及「创建 Skill」「优化 Skill description」等意图，触发后 Agent 会读取对应 SKILL.md 并按流程引导。

依赖说明：完整评测流程（并行 subagent、基准聚合、description 优化循环）在 Claude Code 环境下体验最完整；Claude.ai 无 subagent，需串行执行测试并跳过 baseline 对比；description 优化依赖 claude -p CLI，在 Claude.ai 上不可用。

典型用法示例¶

场景一：从零创建一个新 Skill¶

假设你想把「每次写公众号技术文都重复的风格要求」固化成 Skill：

1. 对 Agent 说：「我想创建一个写公众号技术文章的 Skill，参考 data/style_reference.md 的风格。」
2. skill-creator 会先访谈：触发词是什么？输出格式？要不要 eval？
3. 起草 SKILL.md，生成 2–3 条真实测试 prompt 写入 evals/evals.json。
4. 并行跑 with_skill / without_skill，聚合 benchmark，打开 eval viewer 让你评审。
5. 根据 feedback.json 修改 Skill，进入 iteration-2，直到满意。
6. 可选：运行 description 优化，提升「写公众号」「技术文章」等表述的触发率。
7. package_skill 打包，分发给团队。

场景二：优化已有 Skill 的 description¶

已有 Skill 经常「该用不用」？可以只做触发优化：

1. 生成 20 条 should-trigger / should-not-trigger 测试 query。
2. 用 assets/eval_review.html 模板让用户审核。
3. 运行 scripts.run_loop，对比优化前后触发率。
4. 将 best_description 写回 SKILL.md frontmatter。

场景三：改进已有 Skill 的正文¶

若 Skill 能触发但输出质量不稳定：

1. 对现有 Skill 做快照作为 baseline。
2. 修改 SKILL.md 后重新跑 eval。
3. 查看 benchmark 中 pass rate、token、耗时的 delta。
4. 阅读运行 transcript，若多个 eval 都重复写了相同辅助脚本，考虑把脚本收进 scripts/ 目录——这是 skill-creator 明确推荐的「从重复劳动中提炼资源」模式。

适用场景与注意事项¶

适合谁用：

• 第一次写 Agent Skill、需要规范起步的开发者
• 团队需要统一 Skill 质量、希望有 eval 和 benchmark 的团队
• 已有 Skill 但触发不准或输出不稳定的维护者
• 想把一次性 prompt 沉淀为可复用、可测试能力的 AI 编程实践者

注意事项：

1. 评测成本：完整 eval 会并行启动多个 subagent，消耗 token 和时间；简单 Skill 或与用户「一起 vibe」快速迭代时，可跳过部分量化流程。
2. 环境差异：subagent 并行、基准对比、description 优化在 Claude Code 最完整；其他环境需按 skill-creator 文档中的 Claude.ai / Cowork 适配说明裁剪流程。
3. description 设计：测试 query 要足够具体、多步骤，太简单的「读个 PDF」类请求可能不触发 Skill——因为模型直接用基础工具就能完成。
4. 安全审计：Skill 可含脚本与外部引用，安装前应对 SKILL.md 和 scripts/ 做安全审查，官方文档也强调只使用可信来源的 Skill。
5. 跨平台不互通：Claude Code 的文件系统 Skill、API 上传 Skill、claude.ai 上传 Skill 互不自动同步，需在各自环境分别管理。

小结¶

skill-creator 把 Agent Skill 开发从「写个 Markdown 碰运气」变成了有流程、有测试、有基准、有触发优化的工程化实践。它既是 Anthropic Skill 生态的「元技能」，也是入门 Agent Skills 的最佳起点——先学会用它创建和评测 Skill，再扩展到业务领域的自定义 Skill，会少走很多弯路。

官方仓库：https://github.com/anthropics/skills/tree/main/skills/skill-creator
Agent Skills 总览文档：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview