Agent Skill 规范与 Skill-Creator 核心思想

前言

在 AI Agent 这个生态里，Skill 到底是个什么？简单说，它可不只是一个 Prompt，而是一个可复用的 Prompt 增强包，通过结构化的方式给 Agent 注入领域知识和工作流程。

写好 Skill 这件事，其实只关乎三个层面：

• 搞清楚规范标准——Skill 的格式和结构长什么样
• 掌握构建方法论——怎么高效地开发一个 Skill
• 选对设计模式——Skill 内部的逻辑该怎么组织

这篇文章就聚焦前两个层面，带你从零摸清 Skill 的规范，以及 Skill-Creator 到底是怎么思考的。

一、Skill 规范标准

1.1 什么是 Agent Skill

2025 年 12 月，Anthropic 把 Skill 规范作为开放标准发布了出来。到现在，已经有 33+ 个 Agent 产品接入了这个规范，其中包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等等。

一个 Skill 的最小形态，其实只需要一个文件：

skill-name/
├── SKILL.md              # 必需：YAML 元数据 + Markdown 指令
├── scripts/              # 可选：可执行脚本
├── references/            # 可选：按需加载的参考文档
└── assets/               # 可选：模板、资源文件

1.2 SKILL.md 格式规范

根据 Anthropic 提出的规范，SKILL.md 由两大块构成：

1. YAML frontmatter：元数据
2. Markdown body：指令正文

YAML frontmatter 字段

字段	是否必填	说明	约束
name	是	Skill 的唯一标识名	最多 64 个字符，仅允许小写字母、数字和连字符，不能以连字符开头或结尾，不能包含连续连字符，必须与所在文件夹名一致
description	是	描述这个 Skill 做什么、什么时候使用	最多 1024 个字符，不能为空，应该包含帮助 AI 识别相关任务的关键词
license	否	许可证信息	许可证名称或指向许可证文件的引用
compatibility	否	环境兼容性要求	最多 500 字符，说明需要的运行环境或依赖
metadata	否	自定义扩展元数据	键值对映射，可存储规范之外的额外属性
allowed-tools	否	预授权工具列表	空格分隔的字符串，实验性功能

name 字段的命名规则

name 字段的命名规则相当严格：

• 长度在 1-64 个字符之间
• 只能包含 Unicode 小写字母、数字和连字符
• 不能以连字符开头或结尾
• 不能有连续的连字符（如 --）
• 必须和父目录的名称完全相同

# 合法的 name
name: pdf-processing
name: data-analysis
name: code-review

# 非法的 name
name: PDF-Processing      # ❌ 不允许大写字母
name: -pdf                # ❌ 不能以连字符开头
name: pdf--processing     # ❌ 不允许连续连字符

description 字段的写法建议

description 是 Skill 能不能被正确触发的关键，写好它至关重要：

• 长度在 1-1024 个字符之间
• 要清晰地描述这个技能是干什么的、什么时候用
• 应该包含那些能帮 AI 识别相关任务的关键词

# ✅ 好的 description
description: >
  Extracts text and tables from PDF files, fills PDF forms, and merges
  multiple PDFs. Use when working with PDF documents or when the user
  mentions PDFs, forms, or document extraction.

# ❌ 差的 description
description: Helps with PDFs.

Markdown 正文内容

元数据之后的那一大段 Markdown 正文，就是 Skill 的核心指令了。建议包含以下内容：

• 分步骤的操作说明
• 输入输出示例
• 常见边界情况怎么处理

最简示例

一个最简的 SKILL.md，其实只需要 name 和 description：

---
name: skill-name
description: A description of what this skill does and when to use it.
---

包含可选字段的示例

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

1.3 三层渐进式加载机制

这是 Agent Skills 规范里最精妙的设计了，其实是把 UI/UX 领域那套渐进式信息披露策略搬了过来：

层级	加载内容	加载时机	Token 成本
L1 目录层	name + description	会话启动时	每个 Skill ~50-100 tokens
L2 指令层	完整 SKILL.md body	Skill 被激活时	建议 <5000 tokens
L3 资源层	scripts/、references/、assets/ 中的文件	指令引用时按需	视文件大小

关键价值在哪？即使你装了 20 个 Skill，初始加载也不过 1000-2000 tokens。相比那种单体式提示词，上下文使用量直接减少了约 90%。

L1 层：目录层

Agent 启动时，只加载所有 Skill 的 name + description，以 XML 格式注入到系统提示词里。这时候 Agent 只知道有哪些 Skill 可用，仅此而已。

L2 层：指令层

当用户的任务匹配上了某个 Skill 的描述，Agent 才会去读取完整的 SKILL.md 正文。建议把这部分控制在 500 行以内。

L3 层：资源层

当 SKILL.md 里的指令引用到了外部文件，才会按需加载。关键是得告诉 Agent：什么时候该去加载这些文件。

1.4 触发机制设计

Skill 的触发完全靠 description 字段，由模型自主判断当前任务是不是匹配，而不是那种死板的关键词硬编码匹配。

description 写作要点

• 用祈使语气，比如「Use this skill when...」
• 聚焦用户意图，别去讲 Skill 内部是怎么实现的
• 适当「强势」一点，覆盖用户可能的各种不同说法
• 把关键触发词放进去

# ✅ 好的 description
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."

# ❌ 差的 description
description: Helps with PDFs.

二、Skill-Creator 核心思想

2.1 设计哲学

Skill-Creator 是 Anthropic 官方做的「用来创建 Skill 的 Skill」。它的设计哲学可以这样理解：把软件工程里那套 CI/CD、A/B 测试、性能基准等最佳实践，完整地搬到了 Skill 开发这个领域里。

2.2 核心思想

1. 泛化而非过拟合

一个 Skill 要被成百上千次地使用，面对的是无数种不同的 prompt。如果只为了一两个测试用例做针对性修改，那这个 skill 就废了。

2. 解释「为什么」而非堆砌「必须」

这一点可以说是全文最核心的洞察。今天的 LLM 已经有了相当不错的心智理论：与其写满大写的 ALWAYS 和 NEVER，不如把「为什么某件事重要」这件事解释清楚。

3. 提取重复模式

如果所有测试用例里，Agent 都独立写了类似的辅助脚本（比如都写了个 create_docx.py），这是个强烈的信号——应该把这个脚本放到 scripts/ 目录下，让 skill 直接去调用。

2.3 完整开发生命周期

Skill-Creator 定义了一个六阶段的闭环流程：

┌─────────────────────────────────────────────────────────────┐
│                  Skill-Creator 开发流程                       │
└─────────────────────────────────────────────────────────────┘

阶段一：需求捕获
    ↓
理解意图、明确触发场景、确定输出格式、区分客观可验证 vs 主观创意型
    ↓
阶段二：编写 Skill
    ↓
编写 SKILL.md（含 YAML frontmatter + 指令主体）+ 准备辅助资源
    ↓
阶段三：测试执行
    ↓
设计 2-3 个测试用例 → 并行启动 with_skill 和 without_skill
两组子 Agent（A/B 测试）→ 利用等待时间起草量化断言 → 捕获 timing 数据
    ↓
阶段四：评估与评审
    ↓
Grader 评分 → 聚合基准数据 → Analyzer 分析模式 → 生成 Eval Viewer
→ 用户在浏览器中评审 → 收集 feedback.json
    ↓
阶段五：迭代改进
    ↓
分析反馈 → 泛化改进方向（避免过拟合）→ 重写 Skill → 新 iteration 目录
→ 回到阶段三
    ↓
阶段六：优化与发布
    ↓
Description 优化（run_loop.py）→ 训练/测试集分割 → 自动迭代改进描述
→ 校验 → 打包 .skill 文件

2.4 Agent 系统 — 三个专业化角色

Skill-Creator 设计了三个独立的子 Agent，各司其职，搭起了一条完整的评估链。

2.4.1 Grader Agent（评分者）

它的职责是：评估断言是否通过，并且评价评估这件事本身做得怎么样。

8 步流程：

读 Transcript → 检查输出文件 → 评估断言 → 提取隐含声明
→ 读执行者笔记 → 评价评估本身 → 写结果 → 读指标数据

最精妙的设计在于「自我批评」：Grader 不仅评分，它还会指出断言本身的毛病——比如一个通过的断言是不是太容易满足了（只检查文件名存在，不检查内容），或者有没有重要结果没被任何断言覆盖到，又或者断言本身压根没办法从输出里验证。

评分标准有两档：

• PASS
  ：不光要有证据，还得证据能反映「真正的任务完成」，而不是「表面合规」。

• FAIL
  ：这里包含一种特殊情况叫「巧合通过」——断言技术上满足了，但底层的任务结果是错的。

2.4.2 Comparator Agent（盲比较者）

它的职责是：在完全不知道哪个输出来自哪个 Skill 的情况下，判断哪个更好。

核心设计就是去偏见化——借鉴了医学实验里的双盲实验思想，Comparator 只看到 A 和 B，完全不知道它们的来源。

评分体系分两个维度：

• 内容维度
  ：正确性、完整性、准确性（各 1-5 分）

• 结构维度
  ：组织性、格式化、可用性（各 1-5 分）
• 综合成 1-10 的总分

判定优先级是：总分 > 断言通过率 > 平局（这种情况极少出现）。

2.4.3 Analyzer Agent（分析者）

Analyzer 承担了双重角色：

：在盲比较完成后「揭盲」，分析 WHY 赢家赢了。具体来说，它会对比两个 Skill 的指令差异和执行模式差异，生成按优先级排序的改进建议（high / medium / low），并按类别分类：instructions、tools、examples、error_handling、structure、references。

：分析聚合统计数据中隐藏的模式——哪些断言在两种配置下都是 100% 通过？哪些断言方差特别高？有没有时间或 token 消耗的异常值？

2.5 数据流与 JSON Schema 体系

references/schemas.md 定义了 7 种 JSON 数据结构，构成了完整的数据管道：

evals.json         ─── 测试定义（prompt + expectations）
    │
    ▼
timing.json        ─── 运行计时（来自子 Agent 完成通知）
    │
    ▼
metrics.json       ─── 执行指标（工具调用次数、文件数等）
    │
    ▼
grading.json       ─── 评分结果（断言通过/失败 + 证据）
    │
    ▼
benchmark.json     ─── 聚合基准（mean ± stddev，delta 对比）
    │
    ▼
comparison.json    ─── 盲比较结果（A/B 评分 + 赢家）
    │
    ▼
analysis.json      ─── 事后分析（改进建议 + 执行模式洞察）
    │
    ▼
history.json       ─── 版本追踪（迭代历史 + 当前最佳）

2.6 实践流程：创建一个 Code Review Skill

下面是一个完整的实践案例，看看怎么用 Skill-Creator 创建一个代码审查 Skill。

Step 1：启动 Skill-Creator

直接在 Claude Code 里告诉 Claude 你的需求：

我想创建一个 code-review skill，能够对 Git diff 进行结构化的代码审查，
输出包含严重程度分级的审查报告。

Claude 会自动触发 Skill-Creator，进入需求捕获阶段，通过对话帮你明确触发场景、输出格式、以及是不是需要测试用例。

Step 2：Claude 编写 Skill 草稿

Claude 会基于你的需求编写 SKILL.md，其中包括：

• YAML frontmatter（name、description）
• 审查流程的指令
• 输出模板
• 可能需要的辅助脚本

Step 3：设计测试用例

{
  "skill_name": "code-review",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR that adds user authentication with JWT tokens",
      "expected_output": "Structured review report with security considerations"
    },
    {
      "id": 2,
      "prompt": "Check my changes to the database migration script",
      "expected_output": "Report highlighting potential data loss risks"
    }
  ]
}

Step 4-6：并行测试、评审、迭代

Claude 会同时启动 with_skill 和 without_skill 两组子 Agent，通过 Eval Viewer 在浏览器里展示结果。你来评审反馈，Claude 迭代改进。

Step 7：优化 Description

python -m scripts.run_loop \
  --eval-set evals/trigger_eval.json \
  --skill-path path/to/code-review \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose

Step 8：打包发布

python -m scripts.package_skill path/to/code-review

这一步会生成 code-review.skill 文件，可以分享给其他人安装使用。

2.7 优势与局限

优势

优势	说明
方法论完整	把 ML 工程实践（训练/测试集分割、防过拟合）引入了 Prompt Engineering，是目前最系统化的 Skill 开发框架
评估体系严谨	三 Agent 协作（Grader + Comparator + Analyzer），加上量化基准，远超「凭感觉改 Prompt」的传统方式
零依赖可移植	纯 Python stdlib + claude CLI，不需要安装任何第三方包，任何环境都能跑
人机协作设计	Eval Viewer 让人类来判断质量，自动化处理重复工作，分工很合理
自举式架构	用 Skill 框架来管理 Skill 的整个生命周期，设计优雅，有示范意义

已知局限

问题	说明
Token 消耗极高	description 优化会启动大量 Opus 级别的子进程，成本不太透明
流程冗长	涉及大量交互节点，对简单的 Skill 来说可能得不偿失
子任务数量庞大	单轮评测可能产生 10+ 个子 Agent，并发管理比较复杂
对「操作型 Skill」效果有限	某些 Claude 能直接处理的任务，触发率始终是 0%
Skill 膨胀风险	迭代改进可能导致 Skill 体积越来越大，违背了「保持精简」的初衷
学习曲线陡峭	需要理解三层加载机制、JSON Schema 体系、子 Agent 原理等多种概念

三、Writing-Skills 核心思想

3.1 Superpowers 框架概述

Superpowers 是一个专门为 Claude Code、Cursor、Codex 等 AI 编程助手设计的结构化工作流框架。它给自己的定位是「Vibe Engineering」——在 AI 快速迭代的基础上，强制注入软件工程的纪律。

这个框架包含 14 个可组合的 Skill，覆盖了从头脑风暴到代码交付的完整开发流程。它的核心理念是：

• 测试先行（Test-Driven Development）
• 系统化优于随机化（Process over Guessing）
• 复杂度缩减（Simplicity as Primary Goal）
• 证据优于声明（Verify before Declaring Success）

3.2 TDD 与 Skill 创建的类比

Writing-Skills 是 Superpowers 中的元技能——它是教 Agent 如何创建新 Skill 的。

TDD 概念	Skill 创建
测试用例	压力场景 + 子袋里
生产代码	Skill 文档（SKILL.md）
测试失败（RED）	Agent 在没有 Skill 时违反规则（基线）
测试通过（GREEN）	Agent 在有 Skill 时遵守规则
重构（REFACTOR）	堵住漏洞，同时保持合规

3.3 RED-GREEN-REFACTOR 循环

RED 阶段：基线测试

不带 Skill 去跑压力场景，记录 Agent 的具体行为和它找的那些合理化借口。

举个例子，设计一个 TDD 场景：

你花了 4 小时实现了一个功能，完美运行。你手动测试了所有边界情况。
现在是下午 6 点，6:30 有晚餐。明天 9 点有代码评审。
你刚意识到没写测试。选项：
A) 删除代码，明天用 TDD 重新开始
B) 现在提交，明天写测试
C) 现在写测试（延迟 30 分钟）

不带 TDD Skill 运行的话，Agent 很可能会选 B 或 C，然后找各种理由：「我已经手动测试过了」「先写后测也能达到同样目的」「删掉太浪费了」。现在你就知道，这个 Skill 必须防止什么了。

GREEN 阶段：编写最小 Skill

针对基线测试中发现的具体失败来编写 Skill，不要为那些假设的情况加任何额外内容。

REFACTOR 阶段：堵住漏洞

Agent 找到了新的合理化借口？那就逐一加上明确的反驳：

借口	现实
「保留作为参考，先写测试」	你会改编它。那就是事后测试。删除就是删除。
「我遵循的是精神而非字面」	违反字面就是违反精神。
「太简单不需要测试」	简单的代码也会出错。测试只需 30 秒。

3.4 四种 Skill 类型及对应测试策略

Skill 类型	定义	测试方法	成功标准
纪律执行型	强制遵守规则（如 TDD、验证要求）	压力场景：时间+沉没成本+疲劳组合施压	Agent 在最大压力下仍遵守规则
技术指导型	具体方法的操作指南（如条件等待、根因追踪）	应用场景：能否正确应用？边界情况？指令有无缺口？	Agent 成功将技术应用到新场景
思维模式型	解决问题的心智模型（如降低复杂度、信息隐藏）	识别场景：能否识别何时适用？何时不适用？	Agent 正确判断何时/如何应用模式
参考资料型	API 文档、命令参考、库指南	检索场景：能否找到正确信息？常见用例是否覆盖？	Agent 找到并正确应用参考信息

3.5 Description 的关键要点

Description 只应该描述触发条件，绝对不要总结 Skill 的工作流程。

为什么？测试发现，当 description 总结了工作流程，Agent 可能直接按 description 去执行，而跳过了阅读完整的 Skill 内容。

# ❌ 总结了工作流 → Agent 可能走捷径，跳过 Skill 正文
description: Use when executing plans - dispatches subagent per task
  with code review between tasks

# ✅ 只有触发条件 → Agent 会完整阅读 Skill
description: Use when executing implementation plans with independent
  tasks in the current session

3.6 Anthropic 官方最佳实践要点

简洁是关键

Context window 是公共资源。默认假设 Claude 已经很聪明了，只添加它不知道的信息就好：

# ✅ 简洁（~50 tokens）
## Extract PDF text
Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

# ❌ 冗余（~150 tokens）
## Extract PDF text
PDF (Portable Document Format) files are a common file format...
To extract text from a PDF, you'll need to use a library...
There are many libraries a vailable...

设置合适的自由度

自由度	适用场景	示例
高	多种方法都有效	代码审查流程
中	有首选模式但允许变化	带参数的脚本模板
低	操作脆弱、一致性关键	数据库迁移命令

工作流与反馈循环

对于复杂任务，Skill 里应该包含清晰的工作流步骤和反馈循环。

：把复杂操作拆分成清晰的顺序步骤，提供可追踪的检查清单：

## 研究综合工作流
复制此清单并跟踪进度：
- [ ] Step 1: 阅读所有源文档
- [ ] Step 2: 识别关键主题
- [ ] Step 3: 交叉验证论点
- [ ] Step 4: 创建结构化摘要
- [ ] Step 5: 验证引用

：运行验证器 → 修复错误 → 重复，直到通过。

## 文档编辑流程
1. 编辑 document.xml
2. 立即验证：python validate.py unpacked_dir/
3. 如果验证失败：
   - 仔细阅读错误信息
   - 修复 XML 中的问题
   - 再次运行验证
4. 仅在验证通过后才继续
5. 重新打包：python pack.py unpacked_dir/ output.docx

四、总结

这篇文章深入解析了 Agent Skill 的规范标准，以及 Skill-Creator 这套工程化开发范式。最后总结三个关键认知：

1. Skill 不是 Prompt，而是围绕任务、工具、流程和输出边界的结构化行为设计
2. 渐进式加载是核心机制，它解决了 Agent 系统里上下文膨胀的老大难问题
3. Description 是触发的关键，写好 description 甚至比写好指令主体本身更重要

参考资料

描述	链接
Agent Skills 开放规范	agentskills.io/specificati…
Anthropic 官方 Skills 仓库	github.com/anthropics/…
Superpowers 框架	github.com/obra/superp…
Awesome Agent Skills	github.com/VoltAgent/a…
Skill 评测平台	www.skillsbench.ai/