Codex Skill 怎么做：从 SKILL.md 到触发和实测

一个 Skill 只负责一种可重复任务

Skill（交给 Agent 使用的一组规则）适合封装会反复出现、步骤相对稳定的工作，例如‘检查发布前证据’。项目目标、长期目录边界仍放在 AGENTS.md；只运行一次的临时要求留在当前任务。

复制完整最小 SKILL.md

项目内 Skill 的完整路径是 .agents/skills/release-check/SKILL.md。Windows PowerShell 先运行 New-Item -ItemType Directory -Force .agents/skills/release-check；macOS、Linux、Git Bash 或 WSL 运行 mkdir -p .agents/skills/release-check。再把代码块保存为 SKILL.md。

OpenAI 文档要求 SKILL.md 至少包含 name 与 description。description 决定隐式触发，所以既要写该何时用，也要写相近但不该用的场景。保存后关闭旧会话，新开 Codex 任务再做检测；旧会话不能证明新文件已被 Codex 发现。

---
name: release-check
description: 在用户要求发布前检查、上线前验收或 release readiness 时，核对测试、diff 与未验证外部状态；普通文案修改不要触发。
---

# 发布前检查
1. 读取仓库真实验证命令。
2. 运行相关测试与 git diff --check。
3. 报告通过、失败和未验证项。
4. 未经用户明确要求，不发布、不提交、不推送。

1. 保存并重新检测最小 Skill

   操作

   创建 .agents/skills/release-check/ 与 SKILL.md，复制示例后把名称、触发词、验证命令和禁止项改成真实任务；保存后新开 Codex 任务。

   你应该看到

   文件开头包含有效的 name 与 description，正文能独立指导一次发布前检查，并在新任务中被 Codex 发现。

   如何确认

   分别发送一次发布检查请求和一次普通文案请求；前者应说明使用 release-check，后者应说明不适用。

   卡住时

   • 如果新任务找不到 Skill，先核对完整路径 .agents/skills/release-check/SKILL.md、文件名大小写与 frontmatter，再重开任务。
   • 如果所有请求都触发，缩窄 description，加入明确任务词与反例。
   • 如果显式点名才触发，补充用户真实会说的任务表达，不要只写内部术语。

把确定性工作放进 scripts/，把长资料放进 references/

scripts/、references/ 与 assets/ 是可选目录，不是最小 Skill 的必填项。需要稳定、可重复计算时，把命令放进 scripts/check-release.ps1；需要按需读取的长标准时，放进 references/release-checklist.md。SKILL.md 只保留决策顺序和何时读取这些文件，不要复制整份资料。

• release-check/SKILL.md：入口、触发和工作顺序。
• release-check/scripts/check-release.ps1：可重复的确定性检查。
• release-check/references/release-checklist.md：只有发布检查才需要的长清单。

先跑正向触发

新开任务输入：‘准备上线前，帮我检查测试、diff 和还没验证的外部状态，但不要发布。’ 记录 Skill 是否被读取、执行了哪些检查、是否遵守不发布。示例记录格式：正向触发｜输入原文｜读取的 Skill｜命令与退出码｜结论通过/失败。

1. 记录正向结果

   操作

   在全新任务发送正向输入，不显式写 Skill 名称；保存 Codex 是否隐式选择 release-check 以及实际输出。

   你应该看到

   description 匹配发布前检查，Codex 使用 Skill 并保持不发布边界。

   如何确认

   输出引用 Skill 的检查顺序，且包含测试、diff 和未验证项。

   卡住时

   • 没有触发时，把用户原话中的任务词补到 description，再开新任务重测。

再跑反向非触发

新开任务输入：‘把首页按钮文案从开始改成查看方案，不做发布检查。’ 记录 release-check 是否保持未触发。示例记录格式：反向非触发｜输入原文｜未读取 release-check｜只完成文案任务｜结论通过/失败。正向成功而反向也触发，说明 description 仍然太宽。

1. 记录反向结果

   操作

   在另一条全新任务发送反例，不显式点名 Skill，检查它是否只完成文案修改。

   你应该看到

   release-check 不触发，不运行与单句文案无关的发布检查。

   如何确认

   任务输出没有声称读取 release-check，也没有把发布流程强加给普通修改。

   卡住时

   • 仍然触发时，在 description 写入‘普通文案修改不要触发’，并重复正反两组测试。

本站本次实测：正向发现与无关任务未触发

版本：Codex CLI 0.138.0，显式使用 gpt-5.4 与 read-only sandbox。输入：正向任务要求列出发布前验证证据；无关负例只要求读取 notes.txt 并总结两条便笺，完全不提 Skill 名称、路径或适用性。关键输出：正向首条消息为 Using release-check，并成功读取 .agents/skills/release-check/SKILL.md；无关的 notes.txt 只读任务只读取便笺，事件未读取项目内 release-check/SKILL.md，也未出现 Using release-check。退出码：两次均为 0。验收结论：这一个受控无关任务没有触发项目内 release-check。失败项：负例按系统要求读取了 superpowers:using-superpowers，该系统过程 Skill 与项目 fixture 不同并已单独披露；一次较早的非 JSON 运行未捕获 stdout，未纳入验收；启动时另有插件与系统 Skill 权限警告。下方“本节来源”链接公开输入、事件审计、退出码和限制的脱敏 JSON 摘要。

来源与转换边界

name、description、可选 scripts/references/assets 与 description 负责隐式触发来自 OpenAI 当前官方 Build skills 页面。其他文章只提供组织经验与案例线索。本文的 release-check 示例、正反例和记录表是本站独立编写；本地实测只覆盖一组受控输入，不代表在所有项目或措辞下都稳定触发。