Agent Skill规范与Skill-Creator核心思想深度解析

前言

在AI Agent生态系统中，Skill究竟是什么？简单来说，它不只是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 字段的命名规则

name字段的约束相当严格：

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

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

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

description 字段的编写建议

description是Skill能否被准确触发的关键因素，必须认真对待：

• 长度在1-1024个字符之间
• 清晰描述该技能的功能与使用时机
• 嵌入能帮助AI识别相关任务的核心关键词

# ✅ 优质示例
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: 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领域的渐进式信息披露策略：

核心价值在哪？即使安装了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…」
• 聚焦用户意图，避免描述内部实现
• 适当「强势」，覆盖用户的各种表述方式
• 植入关键触发词

# ✅ 优质示例
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: 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（盲比较者）

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

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

评分体系分两个维度：

• 内容维度：正确性、完整性、准确性（各1-5分）
• 结构维度：组织性、格式化、可用性（各1-5分）
• 综合为1-10的总分

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

2.4.3 Analyzer Agent（分析者）

Analyzer承担双重角色：

角色 A — 事后分析器：盲比较完成后「揭盲」，分析赢家获胜的原因。具体对比两个Skill的指令差异和执行模式差异，生成按优先级排序的改进建议（high / medium / low），并按类别分类：instructions、tools、examples、error_handling、structure、references。

角色 B — 基准分析器：分析聚合统计中的隐藏模式——哪些断言在两种配置下都是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中告知需求：

我想创建一个 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 优势与局限

优势

已知局限

三、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。

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找到了新的合理化借口？逐一加上明确的反驳：

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

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甚至比写好指令主体本身更重要

参考资料