指南
基于 agentskills/agentskills 规范、Anthropic 官方创作最佳实践与 mattpocock/skills
writing-great-skills编写。
速查
- 规范只保证格式，不保证质量——好技能靠工艺：加 agent 不知道的，删 agent 已会的
- 花上下文要精打细算：正文每一行都与对话历史争夺注意力；对每句自问「不写它 agent 会做错吗？」不会就删
- 按脆弱度校准控制：多解且容错 → 给自由 + 讲「为什么」；操作脆弱/须固定顺序 → 强指令 + 精确命令
- 给默认，不给菜单：选一个默认工具 + 一句逃生出口，别把 4 个等价选项摆出来
- 教方法，不教答案：技能应教「怎么解决这类问题」而非「这道题的答案」
- 高价值内容 = gotchas：违反合理假设的环境事实（软删除、字段异名、假健康检查）
- 失败模式：premature completion（过早收工）/ duplication（重复）/ sediment（沉积）/ sprawl（臃肿）/ no-op（空操作）/ negation（负向指令）
- leading word：用模型预训练里已有的紧凑概念（tight、red、relentless）锚定一整片行为，省 token 又更准
规范解剖：五个部分
一份 SKILL.md 的信息，按 agent「多快需要」分层：
- frontmatter 元数据——
name+description是唯一必填，启动即加载，是触发的全部依据 - 正文指令——激活后读进上下文，写「做什么、按什么顺序」
scripts/——可执行代码，agent 按指令运行（自包含或注明依赖、给清晰报错）references/——按需加载的参考文档，每个文件聚焦一个主题、越小越省上下文assets/——模板、图片、schema 等静态资源
name 与 description：触发的全部依据
name 的硬规则（skills-ref validate 会查）：1–64 字符、仅小写字母/数字/连字符、不首尾连字符、不连续连字符、须与父目录同名。
description 是最该被打磨的一句话——它既说「是什么」，又列「何时触发」：
# 好：说清做什么 + 什么时候用 + 关键词
description: 从 PDF 提取文本与表格、填表单、合并多个 PDF。处理 PDF 文档、或用户提到 PDF/表单/文档提取时使用。
# 差：agent 无从判断何时该激活
description: 帮忙处理 PDF。官方创作最佳实践
从真实专长起步，别让 LLM 凭空编
最常见的翻车：让 LLM「生成一个技能」，产出的全是「妥善处理错误」「遵循最佳实践」这类正确的废话，没有让技能真正值钱的具体 API 模式、边界情况、项目约定。
两条靠谱的取材路径：
- 从一次真实任务里提炼——和 agent 一起做完一件真事，留意「哪些步骤奏效、你在哪纠正了它、输入输出长什么样、你补了哪些项目专有事实」，把这套可复用模式沉淀成技能
- 从既有产物合成——喂内部文档、runbook、API schema、code review 评论、git 补丁历史、真实故障案例。用团队真实事故报告合成的数据管道技能，永远强于用「通用数据工程最佳实践」文章合成的
精打细算花上下文
技能一旦激活，完整正文就与对话历史、系统上下文、其它技能同场竞争 agent 的注意力。
加 agent 缺的，删 agent 会的。 不必解释 PDF 是什么、HTTP 怎么工作、数据库迁移做什么。直接跳到 agent 靠自己会做错的部分：项目专有约定、领域专有流程、非显然的边界、该用哪个具体工具。
对每段内容自问：「没有这条指令，agent 会做错吗？」答案是「不会」就删；不确定就测。如果 agent 没有技能也能把整件事做好，这个技能可能根本没在增值。
按脆弱度校准控制
不是每部分都需要同等的规定性——把指令的具体程度匹配任务的脆弱度：
<!-- 多解且容错 → 给自由，讲「为什么」比死命令更有效 -->
## 代码评审
1. 检查所有数据库查询是否防注入（用参数化查询）
2. 核实每个端点都有鉴权
3. 排查并发路径的竞态
4. 确认错误信息不泄露内部细节
<!-- 操作脆弱、须固定顺序 → 强指令 + 精确命令 -->
## 数据库迁移
严格执行这条序列，不要改命令、不要加 flag：
python scripts/migrate.py --verify --backup给默认，不给菜单
多个工具都能用时，选一个默认 + 一句逃生出口，别摆等价清单：
❌ 「你可以用 pypdf、pdfplumber、PyMuPDF 或 pdf2image……」
✅ 「文本提取用 pdfplumber。需 OCR 的扫描件才改用 pdf2image + pytesseract。」
教方法，不教答案
技能应教 agent「怎么approach一类问题」，而非「为这个具体实例产出什么」：
<!-- 具体答案——只对这一道题有用 -->
把 orders 表 join customers 表 on customer_id，筛 region='EMEA'，对 amount 求和。
<!-- 可复用方法——对任何分析查询都成立 -->
1. 从 references/schema.yaml 读表结构，找相关表
2. 用 _id 外键约定 join
3. 把用户需求里的过滤条件写成 WHERE
4. 按需聚合数值列，输出 Markdown 表高价值模式：gotchas、模板、校验循环
这些是可复用的结构化技巧，不必全用，挑合适的：
- Gotchas 段——很多技能里最值钱的内容：违反合理假设的环境事实。不是「妥善处理错误」这种空话，而是「
users表用软删除，查询必须带WHERE deleted_at IS NULL，否则含已停用账号」。当你不得不纠正 agent 的某个错误，就把纠正加进 gotchas——这是迭代技能最直接的方式 - 输出模板——需要固定格式时给模板，比散文描述更可靠（agent 擅长对着具体结构做模式匹配）。短模板内联，长模板放
assets/按需引用 - 多步清单——步骤有依赖或校验门时，显式
- [ ]清单帮 agent 追踪进度、不漏步 - 校验循环——让 agent 自检：做工作 → 跑校验器 → 修问题 → 重跑直到通过
- plan-validate-execute——批量/破坏性操作时，先产出结构化中间计划，对照真相源校验，再执行。关键在校验那一步：
validate_fields.py把计划（field_values.json）对照真相源（form_fields.json），报错像「字段 signature_date 不存在，可用字段：…」给 agent 足够信息自我纠正
让技能「可预测」：工艺词汇
（源自 mattpocock 的 writing-great-skills。这一层解释「为什么好技能读起来是那样」。）
技能存在，是为了从随机系统里榨出确定性。根本美德是可预测性——agent 每次跑走同一套流程（不是产出同一份结果）。下面每个杠杆都服务于它。
两种「负载」的权衡
- 上下文负载（context load）：模型可触发的技能，其
description每一轮都待在窗口里——省这个负载就把技能设成「仅用户触发」 - 认知负载（cognitive load）：仅用户触发的技能零上下文负载，但你成了必须记住它存在的索引；用户触发技能多到记不住时，用一个router 技能（点名其它技能及何时用）来治
leading word：用一个词锚定一片行为
leading word 是模型预训练里已有的紧凑概念（lesson、fog of war、tracer bullets）。在正文里反复出现，它积累出一份分布式定义，用最少 token 锚定一整片行为——因为它调用的是模型已持有的先验。
它两头受益：在正文锚定执行（词一出现，agent 就伸手去做同一行为）；在 description 锚定触发（同一个词活在你的 prompt、文档、代码里，agent 把这份共享语言链到技能，触发更可靠）。
「fast, deterministic, low-overhead」→ 一个 tight（tight loop）；「一个你相信的循环」→ red（循环在 bug 上变红，或不变）。你赢两次：更少 token，且给 agent 一个更锋利的思维挂钩。
六个失败模式
用来诊断技能出的问题：
| 失败模式 | 症状 | 解法 |
|---|---|---|
| premature completion | 步骤没真做完就收工，注意力滑向「已完成」 | 先锐化完成判据（廉价）；仍抢跑再把后续步骤藏起来（拆分序列） |
| duplication | 同一含义出现在多处 | 折叠成单一真相源——省维护、省 token，也纠正它在信息阶梯上的虚高排名 |
| sediment | 陈旧层层堆积（加感觉安全、删感觉危险） | 无剪枝纪律的技能的默认结局；逐句跑 no-op 测试，整句删而非改词 |
| sprawl | 技能单纯太长（哪怕每行都有用） | 用信息阶梯：把参考下沉到指针后，按分支/序列拆分 |
| no-op | 一行模型默认就会照做，白付 token | 测试：它相对默认改变行为了吗？弱 leading word（be thorough）就是 no-op，换强词（relentless） |
| negation | 用禁令引导反而适得其反 | 「别想大象」把大象召唤出来；改用正向陈述目标行为，禁令只留作无法正向表达的硬护栏 |
与 CLAUDE.md、slash 命令、子代理的边界
- CLAUDE.md 常驻，技能按需加载——一段从「事实」长成「流程」的 CLAUDE.md，就该迁进技能
- 自定义命令已并入技能：
.claude/commands/x.md与.claude/skills/x/SKILL.md都生成/x，技能多了带目录、控触发、可自动加载的能力 - 技能影响 agent「怎么想」，hooks 影响 agent「跑工具时触发什么 shell」——两者互补：强制流程用技能，Edit 后自动格式化用 hook
下一步
- 参考 —— frontmatter 全字段表（可移植 vs Claude Code 扩展）、目录约定、字符串替换、校验 CLI、生态清单
- 官方：创作最佳实践 · Claude Code Skills