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

本文深入解析 Agent Skill 的规范标准和 Skill-Creator 的工程化开发范式，帮助你理解 Skill 的本质，掌握从规范到实践的完整方法论。

前言

在 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 的最小形态只需要一个文件：

bash 复制代码

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

1.2 SKILL.md 格式规范

根据 Anthropic 提出的规范，SKILL.md 由两个核心部分组成：

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

YAML frontmatter 字段

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

name 字段的命名规则

name 字段有严格的命名规则：

必须为 1-64 个字符
只能包含 Unicode 小写字母数字字符（a-z）和连字符（-）
不能以连字符 (-) 开头或结尾
不得包含连续的连字符（--）
必须与父目录名称匹配

yaml 复制代码

# 合法的 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 识别相关任务的特定关键词

yaml 复制代码

# ✅ 好的 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 的核心指令。建议包含以下内容：

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

建议正文控制在 500 行以内。如果内容较多，可以把详细的参考资料拆分到单独的文件中。

最简示例

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

yaml 复制代码

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

包含可选字段的示例

yaml 复制代码

---
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 body。建议控制在 500 行以内。

L3 层：资源层

SKILL.md 中的指令引用外部文件时按需加载。关键是告诉 Agent 何时加载：

"当 API 返回非 200 时，读取 references/api-errors.md"

1.4 触发机制设计

Skill 的触发完全依赖 description 字段，由模型自主判断当前任务是否匹配（Model-driven Activation），而非关键词硬编码匹配。

description 写作要点

使用祈使语气：「Use this skill when...」
聚焦用户意图，而非 Skill 内部机制
适当「强势」，覆盖用户可能的各种表述
包含关键触发词

yaml 复制代码

# ✅ 好的 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」，其设计哲学可以概括为：

像做机器学习一样做 Prompt Engineering

它将软件工程中的 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 定义了六个阶段的闭环流程：

css 复制代码

┌─────────────────────────────────────────────────────────────┐
│                    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 → 检查输出文件 → 评估断言 → 提取隐含声明
→ 读执行者笔记 → 评价评估本身 → 写结果 → 读指标数据

最精妙的设计是"自我批评"：

"A passing grade on a weak assertion is worse than useless --- it creates false confidence."

对一个薄弱断言给出"通过"的评级，其危害比毫无用处还要糟糕------它会制造出虚假的信心。

Grader 不仅评分，还会指出断言本身的问题：

一个通过的断言是否太容易满足（如只检查文件名存在，不检查内容）
是否有重要结果没有被任何断言覆盖
断言是否无法从可用输出中验证

评分标准：

PASS：不仅要有证据，还要证据反映"真正的任务完成"，而非"表面合规"
FAIL：包括"巧合通过"------断言技术上满足了，但底层任务结果是错的

2.4.2 Comparator Agent（盲比较者）

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

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

双维度评分体系：

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

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

2.4.3 Analyzer Agent（分析者）

Analyzer 有双重角色：

角色 A --- 事后分析器：在盲比较后"揭盲"，分析 WHY 赢家赢了：

对比两个 Skill 的指令差异和执行模式差异
生成按优先级排序的改进建议（high / medium / low）
按类别分类：instructions、tools、examples、error_handling、structure、references

角色 B --- 基准分析器：分析聚合统计数据隐藏的模式：

哪些断言在两种配置下都 100% 通过？
哪些断言高方差？
时间/token 的异常值

2.5 数据流与 JSON Schema 体系

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

css 复制代码

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 你的需求：

css 复制代码

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

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

Step 2：Claude 编写 Skill 草稿

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

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

Step 3：设计测试用例

json 复制代码

{
  "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

bash 复制代码

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：打包发布

bash 复制代码

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 场景：

less 复制代码

你花了 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 的关键要点

这是 writing-skills 中最重要的发现之一。

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

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

yaml 复制代码

# ❌ 总结了工作流 → 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 已经很聪明，只添加它不知道的信息：

markdown 复制代码

# ✅ 简洁（~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 available...

设置合适的自由度

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

工作流与反馈循环

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

工作流模式：将复杂操作拆分为清晰的顺序步骤，提供可追踪的检查清单：

markdown 复制代码

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

反馈循环模式：运行验证器 → 修复错误 → 重复，直到通过。

markdown 复制代码

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

四、总结

本文深入解析了 Agent Skill 的规范标准和 Skill-Creator 的工程化开发范式。三个关键认知：

Skill 不是 Prompt，而是围绕任务、工具、流程和输出边界的结构化行为设计
渐进式加载是核心机制，解决了 Agent 系统的上下文膨胀问题
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/