每次让 AI 检查接口变更，都要重新解释兼容性、空值和错误码，说明这些经验适合整理成可复用的工作资料。Agent Skill 提供了一种文件组织方式；真正决定效果的，是资料是否告诉 AI 何时使用、依据什么判断，以及什么情况应该停下来。
技能目录如何按需加载#
技能由说明、脚本和资源组成一个目录。客户端先让模型看到简短元数据，需要时再读取正文与其他文件。这样可以把较长的操作方法按需加载，避免每个任务都携带同一大段说明。
最小技能包含 SKILL.md，由 YAML 元数据和 Markdown 正文组成；必填项为 name、description，还可以放置 scripts/、references/、assets/。名称应与目录名一致。安装前需要确认客户端支持的格式及执行能力。
选择一项能反复判断对错的工作#
“帮助团队提高代码质量”范围太大。可以先把目标收窄为检查一次 HTTP 接口变更是否有潜在兼容性问题，并产出供人审核的报告。
输入是变更前后的接口定义、相关实现和必要的测试说明；输出是问题、证据和影响。如果没有旧接口定义，技能应说明无法完成兼容性比较，而不是把当前实现当成原始约定。
这个目标允许我们设计明确的案例。例如旧响应中 enabled 始终为布尔值，新实现可能返回 null，应提醒调用方是否能够接受；如果只是局部变量改名且不改变外部行为，就不应硬找兼容性问题。
先选这类边界明确的任务，才能判断技能有没有提供帮助。泛泛要求“全面检查”，常常只能得到一篇看似完整、实际无法核验的评论。
目录怎么拆，取决于使用时机#
接口检查技能可以采用这样的目录：
api-change-review/
├── SKILL.md
├── references/
│ └── compatibility.md
└── assets/
└── report-example.mdSKILL.md 负责入口：需要哪些资料、按什么顺序检查、怎样输出。compatibility.md 放团队已经确认的具体约定，例如某个字段允许缺省但不允许显式空值。示例文件展示一份合格报告的形式，避免入口说明里塞满案例。
不必为了目录完整而添加脚本。一个技能如果主要检查接口语义，可能只需要三份文档。只有存在确定、重复的机械检查，例如从固定格式中提取字段列表时，再考虑增加脚本，并单独说明依赖、参数和副作用。
入口说明应该足够具体#
SKILL.md 可以从这些内容开始：
---
name: api-change-review
description: 比较 HTTP 接口变更前后的请求和响应约定；用于检查字段、空值、状态码和分页兼容性。
---
# 接口变更检查
先确定比较基线与目标版本。缺少基线时明确说明限制。
读取相关接口定义及实现，必要时参考 references/compatibility.md。
逐项检查请求、响应和错误行为，只报告有依据的变化。
输出：变化位置、旧行为、新行为、可能受影响的调用方、证据。
区分已确认问题与待确认约定，不修改代码或调用外部系统。说明中需要保留“待确认约定”的位置：例如改了分页大小上限，究竟算缺陷还是新需求，单凭代码差异无法决定。技能可以指出影响，却不能替产品负责人发明需求。
description 还承担选择入口的作用。“专业开发助手”无法告诉模型何时使用，而“比较 HTTP 接口变更前后”提供了可识别的任务边界。若实际使用时经常在无关任务触发，应先调整描述，不要在正文里堆更多禁止条款。
用一份小报告展示期望结果#
以接口 /api/items 为例，假设旧约定是空列表返回 []，新实现可能返回 null。一份有用的报告可以这样写：
观察：items 字段在无结果时的表现发生变化。
旧行为：空数组。
新行为：可能为空值。
影响：直接遍历 items 的调用方可能需要额外判断。
依据：旧接口样例与新实现对应分支。
待确认：是否已有正式变更约定及客户端迁移计划。这里不自动给问题定为最高严重等级。若客户端本来就兼容空值，实际风险会不同；若旧样例只是偶然输出，也需要补充接口约定。报告的价值在于把需要确认的位置讲清楚，而不是用强硬措辞制造确定感。
示例里应同时保留一个“无问题”的案例。否则 AI 容易把交付理解成必须找到问题，最终对无害改动也生成一段风险分析。
验证技能，要看它是否改变了判断#
可以准备四组小型资料：确实删除必需字段的变更、只重构内部代码的变更、缺少比较基线的任务，以及存在明确兼容迁移说明的变更。对每组资料先写出人工期望结果，再比较启用技能前后的报告。
记录漏报和误报，也记录模型是否承认资料缺失。只看报告是否套用了标题，无法判断技能有没有真正理解任务。如果改完技能后漏报减少但误报增加，就需要进一步收窄规则或补充反例。
团队维护时，可把每个新发现的错误转成一个小案例，而不是直接把整次聊天贴进技能。长聊天包含临时猜测、过期配置和重复解释，原样保存会让下一次工作继承这些噪声。
技能也需要有维护基线。可以在仓库里与代码一起评审，修改后保留对应案例的结果，说明究竟修正了哪一种误判。不要只写“优化提示词”，否则接手的人无法判断新增规则是否仍有必要。
如果两个项目对空值有不同约定，应把项目规则放在各自的参考文件中，并在入口明确选择条件。把两套相反要求直接拼进同一个说明，会迫使模型临时猜测优先级。找不到当前项目的约定时，宁可报告缺失，也不要选择自己更熟悉的一套。
技能里的要求不会自动变成权限#
技能可以描述如何工作，但它不能替代客户端和操作系统的访问控制。文件系统和网络隔离属于实际运行边界，与文档里的“请只读”处于不同层次。
接口检查通常不需要生产凭据，也不需要执行外部写入。若以后加入自动提交报告或修改代码，应该作为新的能力重新设计输入、权限和验收条件，不应藏在一个普通检查脚本里。
安装第三方技能前，也可以按代码审查的方式读它：入口说明让 AI 做什么，脚本会读写哪里，依赖从何获取，输出发往何处。目录结构符合规范，只能说明格式可识别，不能说明内容可信。
一份适合长期使用的技能，应让接手的人看得懂适用范围、资料来源和失败边界。先把一项重复工作写成短而明确的操作说明，再通过案例改进，通常比一开始就设计庞大的“万能技能”更容易维护。
参考来源#
- Barry Zhang、Keith Lazuka、Mahesh Murag，《Equipping agents for the real world with Agent Skills》，Anthropic，发布：2025-10-16，含 2025-12-18 开放标准更新。
- Agent Skills 标准维护者，《Specification》。
- David Dworken、Oliver Weller-Davies，《Beyond permission prompts: making Claude Code more secure and autonomous》，Anthropic，发布：2025-10-20。
- 配图：Anthropic，图片出处。