编写指南
概述 介绍了 Agent Skills 的来源、格式和 progressive disclosure。本页先对齐官方规范和 Anthropic
authoring best practices，再讨论更具体的开发过程：如何判断一个能力是否适合写成 Skill，如何写 SKILL.md，如何测试触发与效果，如何迭代而不过拟合少数样例。
写 Skill 不是把一份说明书搬进目录里。它要让 agent 能发现、加载、执行并复用一类能力。有效 Skill 通常同时满足三件事：来源可信、结构简洁、经过真实任务验证。
官方编写原则
官方 best practices 的核心不是“多写规则”，而是让 Skill 在上下文里足够轻、足够准、足够可验证。
| 原则 | 写作含义 |
|---|---|
| 简洁优先 | SKILL.md 会在触发后进入上下文，每一段都要证明自己的 token 成本。 |
| 假设模型已经很聪明 | 不补通识，只补模型缺少的项目约定、操作路径、边界和验证方法。 |
| 设置合适自由度 | 脆弱流程写窄，开放任务写宽；不要用同一种语气处理所有任务。 |
| 测试目标模型 | Skill 的效果依赖底层模型；重要 Skill 要在实际会使用的模型上测试。 |
| description 负责发现 | description 必须写清做什么、何时使用，并包含具体触发词。 |
| 渐进披露 | SKILL.md 像目录和入口，细节按需放进浅层 reference、asset 或 script。 |
| 验证闭环 | 能自动验证的步骤尽量自动化；不能自动验证的步骤给清晰的审阅标准。 |
| 避免过期知识 | 时效信息和版本变化要指向 source of truth，不要写死成长期规则。 |
下面的编写循环是在这组原则之上展开的实践流程。
常见结构选择
官方规范不要求 Skill 使用固定“设计模式”。但写作时经常会遇到几类结构选择，可以把它们当作轻量参考：
| 结构 | 适合场景 | 常用资源 |
|---|---|---|
| 工具包装 | 给 agent 补充某个工具、框架或团队约定 | references/ |
| 生成器 | 生成固定结构的报告、配置、页面、邮件或代码骨架 | assets/ + references/ |
| 审阅器 | 按 checklist 或 rubric 审查代码、文档、设计或合规风险 | references/ |
| 先问再做 | 缺少目标、约束、输入或验收标准时容易误做 | references/ 或 assets/ |
| 流水线 | 多步骤任务需要顺序、中间产物和验证 | references/ + assets/ + scripts/ |
这些结构只有在落实官方原则时才有价值：保持 SKILL.md 简洁，让 description 能正确触发，资源按需加载，并用真实任务验证效果。如果一个 Skill 只需要一页说明，就不要为了套结构强行加入模板或脚本。
编写循环
Skill 的第一版通常只是一个假设。真正的质量来自迭代：捕获意图、起草、测试、观察、改进。
- 捕获意图：确认能力边界、触发场景和不触发场景。
- 核查来源：确认规则、流程、工具行为、术语和示例是否可信、是否有版本限制。
- 起草最小结构：先写最小可用
SKILL.md，只在需要时加入references/、assets/、scripts/。 - 真实任务测试：用代表性 prompt 跑启用 Skill 与不启用 Skill 的对比，重要 Skill 覆盖目标模型。
- 阅读 transcript：看 agent 是否触发、是否读对资源、是否绕路、是否误解约束。
- 针对失败模式改进：修复一类问题，而不是给单个测试样例打补丁。
保持每一轮足够轻。复杂度要由测试反馈推动，而不是由作者一次性设计出来。
1. 捕获意图
动笔前先回答这些问题：
| 问题 | 为什么重要 |
|---|---|
| Skill 要让 agent 做什么？ | description 和正文都应该围绕能力，而不是围绕文件夹结构。 |
| 何时触发？ | agent 先看 metadata。触发语不清楚，正文再好也可能不会被加载。 |
| 何时不该触发？ | near-miss 场景能防止 Skill 抢走相邻任务。 |
| 输出是什么？ | 文件、补丁、审阅意见、表格、报告、命令结果，决定测试方式。 |
| 来源是什么？ | 技术规则、产品行为、论文结论、法律政策都需要可核查来源。 |
| 是否依赖工具或权限？ | Skill 只能指导 agent 使用已存在的工具，不能凭空提供权限。 |
| 哪些步骤适合脚本化？ | 解析、转换、校验等确定性工作适合放进 scripts/。 |
如果用户是在对话中说“把这个变成一个 Skill”，先从现有对话提取答案：用户目标、修正意见、使用过的工具、最终认可的输出、失败过的路径。只在信息缺口会影响设计时追问。
2. 核查来源
Skill 会被重复调用，所以错误知识会被重复放大。写入之前先确认内容是否可靠。
需要核查的内容：
- 产品或平台行为：优先看官方文档、规范、变更日志。
- API、CLI、配置项：确认版本、参数名、默认值、弃用状态。
- 论文或方法结论：区分论文主张、实验范围和二手解读。
- 安全、合规、法律、财务、医疗：必须标出范围，避免把一般建议写成确定规则。
- 时间敏感信息：不要把容易过期的价格、额度、名单、发布日期写成长期规则。
适合写进 Skill 的不是“今天查到的事实”，而是稳定的操作方法、判断框架、团队约定、模板、验证流程。若内容确实会变，写清 source of truth，让 agent 在执行前重新核查。
3. 起草 SKILL.md
Frontmatter
一个 Skill 至少需要 name 和 description。
---
name: pdf-processing
description: Extract text and tables from PDFs, fill PDF forms, and merge or split PDF files. Use when the user asks to inspect, transform, validate, or generate PDF artifacts.
---写 frontmatter 时注意：
name应与目录名一致，使用小写字母、数字和连字符。description同时写清“做什么”和“何时使用”，不要只写一句抽象简介。description不要塞完整流程。流程放正文；metadata 只负责让 agent 判断是否加载。- 许可证、兼容性、metadata、允许工具等字段按需要补充，不要为了看起来完整而堆字段。
正文
正文应该回答三个问题：
- 触发后第一步做什么？
- 什么时候读取哪些资源？
- 完成前如何验证？
建议：
SKILL.md控制在 500 行以内。- 细节放进
references/，模板放进assets/，确定性操作放进scripts/。 - reference 链接保持浅层。agent 应该能从
SKILL.md直接知道读哪一份，不需要一路追索。 - 大 reference 文件应提供目录或明确小节名。
- 不要在 Skill 中写运行环境没有提供的工具能力。
多变体 Skill
当 Skill 覆盖多个变体，例如 AWS/GCP/Azure 或 Python/TypeScript/Rust，让 SKILL.md 做路由：
cloud-deploy/
SKILL.md
references/
aws.md
gcp.md
azure.md正文写清选择规则：什么情况下读哪份 reference。不要把所有变体塞进一个巨大正文。
4. 控制自由度
Skill 不是越强硬越可靠。关键是给任务合适的自由度。
低自由度适合：
- 脆弱流程，例如发布、迁移、表单填充、数据转换。
- 高一致性输出，例如合规报告、配置文件、固定模板。
- 明确安全边界，例如不要提交凭据、不要绕过审批。
写法：明确步骤、输入输出、验证条件、失败时停止条件。
高自由度适合：
- 写作、解释、研究、设计评审。
- 需要综合判断的开放任务。
- 用户偏好会明显影响结果的任务。
写法：给原则、示例、评价标准，而不是把每句话写死。
如果你正在大量使用 ALWAYS、NEVER、MUST 这类大写命令，先停一下。很多时候，更好的写法是解释规则背后的原因，让模型在未覆盖场景中能泛化。
5. 调优 description
description 是 agent 决定是否加载 Skill 时最关键的信号。它应该像一个触发条件，而不是像文章摘要。
差：
How to build a dashboard to display internal data.好：
Build dashboards for internal metrics and company data. Use when the user mentions dashboards,
charts, internal reporting, KPI views, operational metrics, or displaying business data.好 description 通常包含：
- 用户真实会说的触发短语。
- 文件类型、工具、领域或输出形式。
- 范围边界：什么属于，什么不属于。
- 近义词和常见说法，而不仅是 Skill 名称。
测试触发时，不只跑正例。还要准备 near-miss 负例：共享关键词但不应该触发的任务。比如 PDF Skill 的负例不应该是“写一个斐波那契函数”，而应该是“解释 PDF 这个文件格式的历史”或“帮我写一个展示 PDF 下载按钮的网页”。
6. 测试与迭代
至少准备几类测试：
| 测试类型 | 看什么 |
|---|---|
| 正例触发 | 应该加载 Skill 的任务是否加载了。 |
| near-miss 负例 | 相邻但不属于范围的任务是否被放过。 |
| 启用/禁用对比 | Skill 是否真的改善结果，而不是只是增加 token。 |
| 目标模型测试 | 目标模型是否都能按 Skill 工作。 |
| transcript 评审 | agent 是否读对资源、调用对脚本、绕开了哪些步骤。 |
| 客观断言 | 文件结构、字段完整性、构建、单测、schema、校验脚本。 |
主观任务也要测试，但不必强行写自动断言。写作质量、解释清晰度、审阅价值、设计判断更适合通过人工评审、样例对比和用户反馈判断。
每一轮迭代只改一两个点：
- 记录失败模式。
- 判断是触发问题、资源组织问题、说明问题、脚本问题，还是任务本身不适合 Skill。
- 改动最小必要部分。
- 重跑正例和 near-miss，确认没有修好一个点又破坏另一个点。
不要把测试 prompt 直接写成规则。如果用户问 Q4，就输出 X 这种补丁会降低泛化能力。
7. 什么时候写 scripts/
脚本适合处理稳定、可重复、可验证的工作：
- 解析文件、抽取结构化数据、转换格式。
- 运行 lint、测试、schema 校验、PDF 渲染、截图检查。
- 生成固定资产或批量处理文件。
- 封装复杂 API 调用或容易写错的命令序列。
脚本写法建议：
- 让脚本直接解决问题，不要只打印“请模型继续处理”。
- 输入输出尽量结构化，例如 JSON、CSV、明确文件路径。
- 错误信息要可行动，说明失败原因和下一步。
- 依赖和兼容性写清楚。
- 如果希望跨平台使用，避免写死本机路径或只适用于单一 shell 的命令。
不要为了“高级”而加脚本。如果 SKILL.md 加 reference 已经能稳定完成任务，保持轻量。
8. 模式演进
Skill 的结构应该随证据演进。
常见信号：
- 反复生成同一结构：加入
assets/template.*，从工具包装演进为生成器。 - 反复按同一 checklist 评估：把标准拆到
references/checklist.md，形成审阅器。 - 反复遗漏步骤顺序或验证：加入分步流程和脚本，演进为流水线。
- 反复先做错再补问：加入澄清阶段，演进为先问再做。
- scripts 或 reference 长期不用：删掉或合并，降低维护成本。
目标不是让 Skill 越来越复杂，而是让结构刚好承载重复任务。
反模式
- 把 Skill 当资料库。 只堆资料但没有触发条件、流程和验证，agent 很难稳定使用。
- 来源不清。 把二手说法、过期 API、临时价格、旧产品行为写成长期规则。
- description 太抽象。 “Help with documents” 这种描述很难可靠触发。
- 正文过长。 大段细节放进
SKILL.md会增加上下文成本，也让 agent 难以抓住主线。 - 深层 reference 链。 agent 需要一层层点开才能找到关键规则，通常说明结构需要重排。
- 假装拥有工具。 Skill 不能让 agent 获得不存在的 API、账号、权限或联网能力。
- 脚本只是装饰。 如果脚本没有减少重复推导、没有提高确定性，就不该存在。
- 只测正例。 没有 near-miss 负例，就很难发现误触发。