很多人第一次做 Skill，最容易卡在一个很尴尬的地方：文件写了，目录也建了，Codex 就是像没看见一样。
这时候先别急着把 SKILL.md 越写越长。Skill 能不能被找到、什么时候该触发，前两关比正文写得多漂亮更重要。
Skill 到底是什么
Skill 不是“把 Prompt 存成一个文件”这么简单。它更像一套可复用的小工作流：什么时候用、读哪些资料、执行什么步骤、遇到什么情况停下来，都可以放进去。
一个 Skill 至少要有 SKILL.md。需要时再加脚本、参考资料和资源文件：
my-review-skill/├── SKILL.md├── scripts/├── references/└── assets/
第一次别把四个目录全塞满。只做一个 SKILL.md，先证明它能被找到、能按预期触发，再逐步加东西。
先放对目录
Codex 会从不同范围加载本地 Skills。对大多数个人项目来说，最常用的是：
项目当前目录/.agents/skills/项目根目录/.agents/skills/$HOME/.agents/skills/
如果你只想让某个项目使用，就放项目里的 .agents/skills；如果希望不同项目都能调用，再考虑用户级目录。
比如：
demo-project/└── .agents/ └── skills/ └── check-release-notes/ └── SKILL.md
Codex 能自动发现 Skill 变更；如果新加的 Skill 没出现，先确认目录和文件名，再重开一次 Codex，不要第一反应就重装。
一个够用的 SKILL.md
先用最小版本：
---name: check-release-notesdescription: 检查发布说明是否缺少兼容性、迁移步骤和回滚方式。只在审核 release notes 时使用。---# Release notes check1. 读取用户指定的发布说明。2. 检查是否包含变更内容、兼容性、迁移步骤和回滚方式。3. 只报告缺项，不直接修改原文件。4. 如果信息不足，明确标记“待确认”，不要自行补全。
这里最值得花时间的是 description。
“帮我处理文档”这种描述几乎等于没写；“检查发布说明是否缺少迁移和回滚信息”就清楚得多。Codex 在决定是否隐式调用 Skill 时，会先看名字和描述，所以描述要像一个明确的“使用说明”，而不是宣传语。
验证时别只测一次
我更建议做两轮。
第一轮，直接显式调用。CLI/IDE 里可以运行 /skills，也可以输入 $ 后从列表里选 Skill；如果已经知道名字，也可以直接写 $skill-name。先确认“这个 Skill 本身能用”。
例如：
$check-release-notes请检查 docs/release-note.md，只报告缺项，不修改文件。
第二轮，再不点名 Skill，发一个与描述高度匹配的请求：
请检查这份发布说明有没有漏掉迁移步骤和回滚方式。
如果这时 Codex 能自己选中它，才说明隐式触发也基本正常。
最后再做一个反向测试，比如：
帮我总结今天的会议记录。
这条不该触发发布说明检查。正向能触发、反向不乱触发，比“偶尔成功一次”更有意义。
Skill 不触发，按这个顺序查
不要一上来改十处配置。先看最基础的几项：
- 目录是不是 .agents/skills/<skill-name>/SKILL.md；
- SKILL.md 的 YAML 里有没有 name 和 description；
- description 是否明确写出“什么时候应该用”；
- 请求和描述是否真的匹配；
- 引用的 references/...、scripts/... 相对路径是否存在；
- 如果刚修改过 Skill，重开一次任务再测。
如果脚本参与流程，脚本先在终端单独跑通。脚本自己都报错时，别把问题归到 Skill 触发上。
scripts 和 references 什么时候加
有些规则只是文字说明，适合放 references/；有些工作必须稳定执行，比如格式校验、文件转换、运行固定测试，才适合加 scripts/。
这样做还有一个好处：不用每次都把一大坨材料塞进 SKILL.md。Codex 采用渐进式加载，Skill 被选中后再读取完整说明和需要的资源，结构越清楚，后面越好维护。
如果 Skill 里还涉及模型选择，别把价格写死
如果你本来就通过 AI Code With 调模型，这里正好可以把实时页面当成外部事实源。
比如你做的是“根据任务复杂度选择模型”的 Skill，可以规定流程：先读当前模型和渠道信息，再决定用哪个模型；但不要在 SKILL.md 里永久写死“某模型多少钱”“某渠道永远几折”。
AI Code With 的模型和渠道页面本身就是动态信息源：
- 模型与计费：https://aicodewith.ai/zh/dashboard/pricing?ref=docs&src=codex-skills-tutorial
- 渠道状态：https://aicodewith.ai/zh/dashboard/channels?ref=docs&src=codex-skills-tutorial
这样做的好处是：Skill 只保存“怎么判断”，价格和渠道这种会变化的信息留在实时页面。普通的文档整理 Skill 如果根本不涉及模型，就不用额外增加这一层。
最后
Skill 最容易做成“大而全”，也最容易因此失控。
先做一个十分钟能验收的小 Skill：能被发现、能显式调用、能隐式触发、不会误触发。跑顺之后，再加脚本、参考资料和更复杂的自动化。
参考资料
- OpenAI：Build skills — https://developers.openai.com/codex/skills
- AI Code With：Codex 配置文档 — https://aicodewith.com/zh?s=k7m2q9
