Skill 示例:官方 skill-creator 的结构
以 Anthropic 官方仓库里的 skills/skill-creator 为例。这里不自造示例,只看它如何把 SKILL.md、评测、脚本、审查页面和子代理拆开。
SKILL.md 负责主流程,其他目录负责评测、聚合、审查、打包和专门分析。官方目录结构
skill-creator/
├── SKILL.md
├── LICENSE.txt
├── agents/
│ ├── analyzer.md
│ ├── comparator.md
│ └── grader.md
├── assets/
│ └── eval_review.html
├── eval-viewer/
│ ├── generate_review.py
│ └── viewer.html
├── references/
│ └── schemas.md
└── scripts/
├── __init__.py
├── aggregate_benchmark.py
├── generate_report.py
├── improve_description.py
├── package_skill.py
├── quick_validate.py
├── run_eval.py
├── run_loop.py
└── utils.py
SKILL.md 的官方核心标题节选
---
name: skill-creator
description: Create new skills, modify and improve existing skills,
and measure skill performance. Use when users want to create,
edit, evaluate, benchmark, or optimize a skill.
---
# Skill Creator
## Communicating with the user
## Creating a skill
### Capture Intent
### Interview and Research
### Write the SKILL.md
### Skill Writing Guide
### Test Cases
## Running and evaluating test cases
## Improving the skill
## Advanced: Blind comparison
## Description Optimization
### Package and Present
## Claude.ai-specific instructions
## Cowork-Specific Instructions
## Reference files
结构分工
| 目录 / 文件 | 在闭环中的职责 |
|---|---|
SKILL.md | 定义触发描述和主工作流;创建、评测、改进都从这里进入。 |
agents/ | 分别负责评分、盲测比较和失败模式分析。 |
assets/ + eval-viewer/ | 把触发评测和输出结果交给人审查。 |
references/schemas.md | 固定 eval、grading、benchmark 等数据结构。 |
scripts/ | 验证、运行、聚合、报告、触发描述优化和打包。 |
如何创建 Skill:官方流程是一条迭代闭环
官方 skill-creator 的默认路径不是“生成一个 SKILL.md 就结束”,而是明确意图、写草稿、运行样例、让用户审查并按反馈重写;具体评测强度会随任务类型和运行环境调整。
官方流程只看三个阶段
1 · 创建前先问清楚
官方先捕捉意图:这个 skill 要让 Claude 做什么、什么时候触发、输出格式是什么、是否值得建立测试用例。
产物:目标、触发场景、输出契约、测试策略。
2 · 写草稿时分清层级
description 写触发条件,正文写工作流;重复、确定性的步骤放进 scripts/,大资料放进 references/。
产物:SKILL.md + 可选资源目录。
description 是入口控制面
官方把 description 是skill 的主要触发机制。关键不是写得更长,而是让该触发的触发、不该触发的退出。
SKILL.md 正文决定怎么做,description 决定什么时候进来。入口过宽时,正文可能改变原本的首选方向。3 · 跑评测,再优化
先写真实测试 prompt
官方会生成 2-3 个真实用户会说的话,保存到 evals/evals.json;也可以自己编写。
并行跑评测
“不使用 Skill”和“使用 Skill“。或者是“v1 版本 Skill“ 和 “v2 版本 Skill“。
给人审查界面
有浏览器或静态 HTML 能力时,使用 eval-viewer/generate_review.py 展示输出、反馈和 benchmark;受限环境则在对话中逐项审查。
agent会自动创建一些评测集,也可以手动填充一些评测集
例子:坏评测 vs 好评测
坏:太抽象
格式化数据
从PDF中提取文本
这些短句没有上下文,也不是复杂任务。即使 description 命中,Claude 也可能直接用基础能力完成,不一定调用 skill。
好:具体到真实任务
用户在访问公告页面点击编辑操作调用update接口时遇到492错误,需要排查下具体原因。
它有接口位置、业务语境、要求;这类 query 才能真实测试 skill 功能是否正常。
创建闭环:draft → eval → review → rewrite。重点看下四类问题。
四种常见问题
四类问题对应四个审核点:触发边界、事实可靠性、流程弹性、退出条件。
开始优化:单次偏移不能直接归因于 Skill
比较同一批问题在 with skill 和 without skill 的表现进行优化。
案例设定:先认识 debug-playbook
这是本节的被优化对象。问题不是它完全没用,而是触发范围和正文流程把“接口正常但数据内容不对”的场景也吸了进来。
description 覆盖面过宽;② 正文要求严格按顺序;③ 规则压低业务代码方向。强制顺序可能让首步被清单带偏,是否形成稳定退化仍需针对性评测。真实证据:一次首步偏移,不是稳定退化
第三方详情接口前 25 次请求均返回 200,随后稳定返回 429;响应头明确包含 Retry-After: 60,等待一分钟后恢复。接口响应尚未进入本地业务处理。第一步排查哪个方向?
检查请求参数是否完整、格式正确、必填项齐全, 按故障排查标准流程要求,必须严格按 1→5 顺序逐步排查,第 1 步是查参数——即便表面现象指向限流,也需先确认上一步无误才能进入下一步。
面对明确的 429 + Retry-After,第一动作仍是“检查请求参数是否完整”。
真实文件差异:改边界,不给单题打补丁
v2 先区分请求层失败和数据内容问题,同时把强制顺序改成优先级提示;它没有记忆任何一道评测题。
description: 排查接口/爬虫类故障的标准流程。当遇到接口报错、返回空、数据异常、数据缺失、抓取失败等任何故障时,使用本流程定位问题。
description: 排查接口/爬虫类故障时的诊断线索清单。当接口整体报错、被限流、鉴权失败这类请求层问题时参考;若接口正常返回、只是数据内容不对,优先直接读相关代码,不要套用本清单。
# 接口故障标准排查流程
# 接口故障诊断线索(优先级提示,非强制顺序)
遇到故障,严格按以下五步顺序排查。
先判断根因在哪一层,再决定是否套用本清单。
接口正常返回、但数据内容不对 → 先直接读处理数据的代码。
- 必须按 1→5 的顺序逐步排查。
## 何时不要用本 skill
只有接口整体报错、被限流、鉴权失败等请求层问题,才用本清单。
自动进化:自动优化闭环
Hermes Agent Self-Evolution:把 Skill 接进真实优化器
支持 synthetic、golden 和 sessiondb;sessiondb 会读取 Claude Code、Copilot 与 Hermes 的历史会话。
SkillModule 把 Skill 正文包装成 DSPy 模块,再用 train / val 运行反思式优化。
候选必须通过尺寸、语义、测试和留出集门禁。
hermes-agent-self-evolution/
├── evolution/
│ ├── skills/
│ │ ├── evolve_skill.py # 编排数据、优化、门禁、holdout、PR
│ │ └── skill_module.py # 把 SKILL.md 包成 DSPy Module
│ └── core/ # dataset / fitness / constraints
├── datasets/
├── reports/
└── tests/
# README 给出的真实入口:从历史会话进化一个 Skill
export HERMES_AGENT_REPO=~/.hermes/hermes-agent
python -m evolution.skills.evolve_skill \
--skill github-code-review \
--iterations 10 \
--eval-source sessiondb
其他开源路线:优化对象正在变大
| 项目 | 它进化什么 | 核心机制 / 适合场景 |
|---|---|---|
| Microsoft SkillOpt | 一个自然语言 Skill 文档 | 轨迹驱动的受限增删改 + validation gate,输出 best_skill.md;适合把一个已有 Skill 训练扎实。 |
| EvoSkill | Agent program:系统提示 + 多个 Skills | 失败分析 → 生成变体 → held-out 评测 → Git frontier;支持 Claude Code、Codex 等多种 harness。 |
| AutoSkill | 长期 SkillBank 与 Skill 生命周期 | 从对话和轨迹中做 discard / improve / merge / create,再通过 SkillEvo 回放、评测、变异和晋升。 |
Hermes 当前实现边界
| 阶段 | 优化对象 / 引擎 | 仓库状态 |
|---|---|---|
| Phase 1 | Skill 文件 / DSPy + GEPA | 已实现:evolution/skills/evolve_skill.py 与 skill_module.py 有实际代码。 |
| Phase 2–3 | 工具描述、系统提示 / DSPy + GEPA | 规划中:对应目录目前只有初始化文件。 |
| Phase 4 | 工具实现代码 / Darwinian Evolver | 规划中:README 标为 planned,evolution/code/ 尚无实现。 |
| Phase 5 | 持续改进流水线 | 规划中:还不是无人值守的连续自进化系统。 |
Harness 自进化:从 Skill 到 Agent System
Skill 自进化只修改 Agent 系统的一部分。研究前沿开始把 system prompt、工具、记忆、验证规则、运行时控制和失败恢复一起纳入可验证的演进对象。
Self-Harness:让模型修改包裹自己的运行系统
Skill 是 Harness 的一个可编辑面;Harness 还包括 system prompt、工具、记忆、验证规则、运行时控制和失败恢复。论文固定模型参数,让同一个模型根据自身执行失败提出有界修改,再由外部评测门禁决定是否晋升。
从初始的调整方案开始,具有固定模型的智能体会在一系列任务上运行,从而产生可验证的执行结果。智能体会对那些执行失败的案例进行分类分析,从而了解与特定模型相关的故障模式,而不仅仅是孤立的错误。
根据这些故障模式,智能体会提出一系列经过精心设计的调整方案,每个方案都针对特定的故障机制。这种限制确保了所提出的调整措施具有针对性,而不会过于笼统。
这些调整方案会通过回归测试进行评估。只有那些在提升性能的同时,不会对其他任务造成负面影响的调整方案才会被采纳。如果多个候选修改都通过了回归测试,它们就会被合并到下一个版本的测试工具中。该版本则成为下一次迭代的起点。
Terminal-Bench-2.0 · held-out 结果
| 固定模型 | 初始 Harness → 最终 Harness | 绝对提升 |
|---|---|---|
| MiniMax M2.5 | 40.5% → 61.9% | +21.4 pp |
| Qwen3.5-35B-A3B | 23.8% → 38.1% | +14.3 pp |
| GLM-5 | 42.9% → 57.1% | +14.2 pp |
结语
从一个具体问题开始,把 Skill 做成可以持续验证和改进的工作单元。
skill-creator 创建 Skill,并按它给出的流程提示完成评测与优化。参考链接
| 资源 | 用途 |
|---|---|
| Anthropic · skill-creator | 创建、评测与迭代 Skill 的官方工作流。 |
| Anthropic Skills | 官方 Skills 仓库与示例集合。 |
| Agent Skills Specification | 跨 Agent 使用 Skill 的目录与文件约定。 |
| Microsoft SkillOpt | 以评测门禁优化自然语言 Skill 的开源实现。 |
| Self-Harness | 把运行时约束、工具与验证规则纳入可评测演进对象的研究论文。 |
| Hermes Agent Self-Evolution | 以数据集、优化器和门禁驱动 Skill 演进的开源实现。 |
| DSPy + GEPA | 将文本组件包装为可评测程序,并以反思式搜索产生候选优化。 |
| Lessons from building Claude Code: How we use skills | Claude Code 团队关于 Skills 的实践经验与使用原则。 |