编写技能

技能把一类任务的判断、步骤和验收标准写成 Agent 可读取的工作说明。它的质量取决于能否稳定指导实际任务，不取决于说明有多长。技能管理与导入操作见技能管理。

先定义使用契约

写正文之前，明确触发条件、必要输入、允许的工具、输出以及停止条件。把只适用于某个项目的规则留在项目中，不把一次任务的文件名、账号或秘密写成公共技能默认值。

创建一个最小技能

在扩展的技能入口选择创建，填写固定的 ID、三段数字版本、描述和 SKILL.md 正文。命令执行、文件写入、网页读取、搜索和允许域名按实际需要声明，不为方便而全部开启。

下面的正文用于指导一次代码审阅，不包含任何自动提交步骤：

## Review a focused change

Use for reviewing a bounded repository change.

1. Read the request, repository instructions, and current diff.
2. Separate existing user changes from this task.
3. Inspect affected callers, tests, and failure paths.
4. Run the checks required by the repository.
5. Report actionable findings with file locations and evidence.

Do not commit, push, or discard files without task authorization.
If the diff is incomplete, identify the missing scope before judging it.

技能正文描述工作流程；能力声明不扩大运行时权限，允许域名也不提供服务账号或凭证。

填写一个可验证的技能

在扩展的技能入口选择创建，使用下面的元数据，并把上面的审阅正文填入正文区域：

描述用于帮助选择技能，正文负责规定执行步骤，能力声明负责表达需要的工具。正文里写“运行测试”却不准备执行条件，会让技能流程中断；开启能力也不等于免除项目的具体授权要求。

保存后重新打开技能，核对 ID、版本、正文与能力字段。不要把保存成功直接记作任务验证通过。

组织资源与验证

把反复使用的模板、示例和脚本作为技能资源，正文明确何时读取或执行。脚本应说明工作目录、依赖、写入范围、退出结果与失败恢复，不能把安装或外发隐藏在普通阅读步骤中。

使用正常输入、缺失输入和越界请求分别验证。检查 Agent 是否正确选择技能、遵守范围并生成规定产物。单次回复提到技能名称，不证明技能已正确执行。

用三类请求验收

对每个用例保留请求、实际读取范围、输出和验证结果。检查它是否误触发无关任务、跳过关键步骤或产生范围外写入，再修订描述和正文。行为改变后更新版本并重复这些用例。

更新与分发

保留可复现的验证材料和旧内容。修改触发条件、工具能力、外发或文件写入时重新审查，再通过个人技能编辑或技能来源同步更新。接收方分别完成依赖安装、连接配置与权限确认。

SKILL.md 是操作说明，Gene 是复用策略，Recipe 是经验编排；不要仅通过改文件后缀互相转换。已有经验的整理方法见蒸馏 Gene、Skill 与 Recipe。