Codex Skills 编写验收清单：SKILL.md 触发条件与权限边界

写 Codex Skills 时，最常见的问题不是“不会写”，而是写完后难以稳定触发，或者触发后把执行范围说得过大，导致模型在不该改动的地方也动手。要解决这个问题，重点不是堆很多说明，而是把 用途、边界、步骤、验收 写成可复现结构。下面这份教程可作为 Codex Skills 怎么写的基础清单，适合你整理自己的 SKILL.md 模板。

先确定一个 Skill 只解决一种重复任务

在开始写之前，先把目标压缩成一句话，例如“为当前仓库执行前端构建前检查”或“把 issue 文本整理成发布说明草稿”。如果一个 Skill 同时负责分析、修改、提交和部署，触发条件就会变得模糊，后续也难做 Codex Skills 验收。更稳妥的做法是：一个 Skill 只处理一种场景，只面向一类输入，只产出一种主要结果。

你可以让 SKILL.md 至少覆盖这几项：适用场景、明确的触发语义、必需输入、执行步骤、禁止行为、完成标准。这样做的好处是，当 Codex 判断是否调用该 Skill 时，有更清晰的匹配线索；当它真的调用时，也更容易遵守你定义的边界。具体结构和安装方式可对照 官方文档 与 CLI 文档。

可直接改写的 SKILL.md 模板

# Skill Name

## Purpose
说明这个 Skill 解决什么问题，只写一个主目标。

## Use when
列出 3 到 5 条明确触发条件。
例如：用户要求检查当前仓库的构建前置条件；用户要求整理指定目录中的变更说明。

## Inputs
写清必需输入、可选输入、输入缺失时如何处理。

## Steps
1. 先确认当前目录或目标文件是否存在。
2. 只读取与任务相关的文件或目录。
3. 按固定顺序执行分析或修改。
4. 输出结果时给出结论、发现项、下一步建议。

## Boundaries
- 不修改未明确允许的目录。
- 不执行联网操作。
- 不提交代码、不推送、不删除文件。
- 输入不完整时先说明缺失项。

## Done when
列出验收标准，例如：给出检查结论；指出失败原因；如有修改，说明改动范围。

这个模板的核心价值在于“让模型少猜”。尤其是 Use when 和 Boundaries，决定了 Skill 是不是容易误触发。写触发条件时，尽量使用可判断的描述，不要只写“当需要帮助时”。写边界时，也不要只写“谨慎操作”，而要改成可验证的话，例如“仅允许读取 docs 与 src/config，不修改 package.json”。

权限边界怎么写才不含糊

很多人写 SKILL.md 模板时会忽略权限边界，结果就是 Skill 虽然可用，但行为不可预测。边界建议至少从四个方面写清楚：可读范围、可写范围、禁止动作、失败回退。

1. 可读范围：限定目录、文件类型或数据来源，例如“仅检查当前仓库中的 README、package.json 与 src 目录”。
2. 可写范围：如果允许改动，明确到路径级别，例如“只可修改 docs/ 下的 Markdown 文档”。
3. 禁止动作：例如不联网、不安装依赖、不执行删除操作、不生成提交。
4. 失败回退：当输入缺失、目录不存在或权限不足时，要求 Skill 停止并报告，而不是自行猜测。

如果你的任务必须改文件，建议再补一条：先汇报计划，再执行修改。这样更利于人工复核，也更适合后续做 Codex Skills 验收。边界越具体，本地测试时越容易判断 Skill 是“没工作”还是“超范围工作”。

本地验收按这 4 步做

1. 准备最小样本：新建一个小型测试目录，只放与 Skill 相关的文件，避免被大型仓库噪声干扰。
2. 设计 3 类提示词：一类应触发，一类不应触发，一类边界模糊。这样可以检查触发稳定性，而不是只测“理想输入”。
3. 核对输出结构：看结果是否按 SKILL.md 约定输出，是否遗漏输入检查、是否跨目录操作、是否在禁止情况下仍继续执行。
4. 做反向测试：故意删掉必要文件、提供错误路径或不给足输入，确认它会停下来说明原因，而不是编造结果。

如果你通过 Codex CLI 使用技能，本地验收时要特别留意当前工作目录是否正确，因为很多“Skill 不生效”其实是上下文不对，而不是文档没写好。目录发现、技能安装位置和基本调用行为可以结合 CLI 文档 复查；技能文件组织与说明结构则优先对照 Skills 文档。

交付前的最终自检清单

1. 标题与 Purpose 是否只描述一个任务。
2. Use when 是否包含可判断的触发条件，而非空泛描述。
3. Inputs 是否写明必需项、可选项与缺失处理方式。
4. Boundaries 是否精确到目录、动作或输出限制。
5. Done when 是否能让他人复验，不依赖作者脑补。

如果以上五项都能回答清楚，这个 Skill 通常已经具备可维护性。对多数场景来说，好的 SKILL.md 模板 不是写得长，而是让调用条件、权限边界和验收标准足够明确。这样你后续新增 Skill 时，也能复用同一套框架，持续降低误触发与越界执行的风险。