Agent Skill规范、构建与设计模式
前言
Skill 不是 Prompt——它是围绕任务、工具、流程和输出边界的结构化行为设计。 写好 Skill 的关键在于理解规范标准、掌握构建方法论、选择合适的设计模式。
一、Skill 规范标准
1.1 什么是 Agent Skill
在 AI Agent 生态中,Skill 是一种可复用的 Prompt 增强包,通过渐进式加载机制为 Agent 注入领域知识和工作流程。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 格式规范
根据Anthropic提出的规范,SKILL.md 由 YAML frontmatter(元数据) 和 Markdown body(指令正文) 两部分组成。
YAML frontmatter 字段:
字段 | 是否必填 | 说明 | 约束 |
name |
| Skill 的唯一标识名 | 最多 64 个字符,仅允许小写字母、数字和连字符,不能以连字符开头或结尾,不能包含连续连字符,必须与所在文件夹名一致 |
description |
| 描述这个 Skill 做什么、什么时候使用 | 最多 1024 个字符,不能为空,应该包含帮助 AI 识别相关任务的关键词 |
license |
| 许可证信息 | 许可证名称或指向许可证文件的引用 |
compatibility |
| 环境兼容性要求 | 最多 500 字符,说明需要的运行环境或依赖 |
metadata |
| 自定义扩展元数据 | 键值对映射,可存储规范之外的额外属性 |
allowed-tools |
| 预授权工具列表 | 空格分隔的字符串,实验性功能 |
1.2.1 name 字段的命名规则
name 字段有严格的命名规则:
必须为 1-64 个字符
只能包含 Unicode 小写字母数字字符(
a-z)和连字符(-)不能以连字符 (
-)开头或结尾不得包含连续的连字符(
--)必须与父目录名称匹配
合法示例:
name: pdf-processingname: data-analysisname: code-review
非法示例:
name: PDF-Processing # 不允许大写字母name: -pdf # 不能以连字符开头name: pdf--processing # 不允许连续连字符
1.2.2 description 字段的写法建议
description 应该清晰描述 Skill 的功能和适用场景:
必须为 1-1024 个字符
应该描述该技能的作用以及何时使用。
应包含有助于代理识别相关任务的特定关键词。
好的示例:
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.
1.2.3 Markdown 正文内容
元数据之后的 Markdown 正文部分就是 Skill 的核心指令。对正文格式没有硬性限制,只要能帮助 AI 有效执行任务即可。
建议包含以下内容:分步骤的操作说明、输入输出示例、常见边界情况处理。
建议正文控制在 500 行以内。如果内容较多,可以把详细的参考资料拆分到单独的文件中。
1.2.4 最简示例
一个最简的 SKILL.md 只需要 name 和 description:
---name: skill-namedescription: A description of what this skill does and when to use it.---
1.2.5 包含可选字段的示例
---name: pdf-processingdescription: Extract PDF text, fill forms, merge files. Use when handling PDFs.license: Apache-2.0metadata:author: example-orgversion: "1.0"---# PDF Processing## When to use this skillUse this skill when the user needs to work with PDF files...## How to extract text1. Use pdfplumber for text extraction...
1.2.6 文件引用规范
在 SKILL.md 中引用其他文件时,请使用相对于 Skill 根目录的路径。例如:
引用参考文档:references/REFERENCE.md
引用脚本:scripts/extract.py
建议文件引用保持在一层深度,避免深层嵌套的引用链。
1.2.7 可选目录结构
scripts/ 目录
存放 AI 可以运行的可执行代码。脚本应该是自包含的或明确说明依赖关系,包含有用的错误提示信息,并能妥善处理边界情况。常见支持的语言包括 Python、Bash 和 JavaScript。
references/ 目录
存放 AI 在需要时可以读取的补充文档,例如:REFERENCE.md(详细技术参考)、FORMS.md(表单模板或结构化数据格式)、或特定领域的文档(如 finance.md、legal.md)。
建议每个参考文件保持聚焦,因为 AI 是按需加载这些文件的,文件越小,消耗的上下文越少。
assets/ 目录
存放静态资源文件,包括:模板文件(文档模板、配置模板)、图片(示意图、示例图)、数据文件(查找表、Schema 定义)。
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 内部机制
适当「强势」,覆盖用户可能的各种表述
包含关键触发词
好的例子:
Analyze CSV and tabular data files — compute summary statistics,add derived columns, generate charts, and clean messy data. Use thisskill when the user has a CSV, TSV, or Excel file and wants toexplore, transform, or visualize the data, even if they don'texplicitly mention "CSV" or "analysis."
差的例子: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 定义了六个阶段的闭环流程:
阶段一:需求捕获 → 理解意图、明确触发场景、确定输出格式、区分客观可验证 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(分析者)
双重角色:
角色 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 数据结构,形成完整的数据管道:
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,开始需求捕获阶段,通过对话帮你明确:
触发场景("review my code"、"check this PR" 等)
输出格式(Markdown 报告,按严重程度分级)
是否需要测试用例(代码审查有客观标准,适合量化测试)
Step 2:Claude 编写 Skill 草稿
Claude 会基于你的需求编写 SKILL.md,包括:
YAML frontmatter(name、description)
审查流程指令
输出模板
可能的辅助脚本
Step 3:设计测试用例
Claude 会提出 2-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:并行运行测试
Claude 会同时启动 with_skill 和 without_skill 两组子 Agent,在等待期间起草量化断言。
Step 5:评审结果
Claude 运行 generate_review.py 在浏览器中打开 Eval Viewer:
Outputs 标签页:逐个查看每个测试用例的输出
Benchmark 标签页:对比 with_skill vs without_skill 的通过率、耗时、token 用量
你在 Viewer 中为每个输出写反馈,完成后点击 "Submit All Reviews"。
PEOMPT | OUTPUT | FORMAL GRADES | Benchmark Results | Eval Set Review |
[ { "query": "hey can you do a code review on this? i just finished writing the auth module and want to make sure its ok before i open the PR\n\n```python\ndef login(username, password):\n user = db.query(f\"SELECT * FROM users WHERE username = '{username}'\")\n if user and user.password == password:\n return generate_token(user.id)\n```", "should_trigger": true }, { "query": "我有一个 PR 需要合并,但想先做一下 code review,主要是看看有没有 bug 和性能问题,这是 diff:\n\n```diff\n+async function fetchData(id) {\n+ const res = fetch('/api/data/' + id)\n+ return res.json()\n+}\n```", "should_trigger": true }, { "query": "can you review this PR for me? https://github.com/myorg/myrepo/pull/142 — its a refactor of the payment service, mainly moving from callbacks to async/await. want to kn…