Zhou retweetou
OpenAI Codex - Agent Skills Best Practices
只有四句话：
1. Keep each skill focused on one job.
2. Prefer instructions over scripts unless you need deterministic behavior or external tooling.
3. Write imperative steps with explicit inputs and outputs.
4. Test prompts against the skill description to confirm the right trigger behavior.
developers.openai.com/codex/skills
1. Keep each skill focused on one job
Skill 职责边界要单一：
· description 越单一，模型越容易判断“这次该不该用这个 skill”
· 一个 skill 做太多事，会出现触发不准
· 维护时也更容易改坏别的场景
举个例子：
· 不推荐：fullstack-helper，既管数据库，又管前端，又管部署
· 推荐：postgres-query-tuning、playwright-ui-debug、release-note-writer
判断标准：
· 你能不能用一句话说清“它只解决什么问题”
· 用户提一个任务时，你能不能很快判断“该用它”还是“不该用它”
2. Prefer instructions over scripts unless you need deterministic behavior or external tooling
默认先写清楚步骤，不要一上来就写脚本，为什么：
· 说明文字更灵活，模型可以根据现场情况调整
· 脚本需要维护、兼容环境、处理错误，成本更高
· 很多任务本来只是“怎么做”的问题，不一定需要固定程序
文档也给了两个例外：
· 你需要确定性行为
例如输出格式必须严格一致、每次都要按同样流程执行
· 你需要外部工具
例如调用 ffmpeg、数据库客户端、测试命令、浏览器自动化工具
可以这样理解：
· 能靠明确步骤完成，就先用文字
· 只有在“必须固定”或“必须调用工具”时，再加脚本
3. Write imperative steps with explicit inputs and outputs
用命令式写法，输入输出写明白：
· 用“先做 A，再做 B，然后检查 C”
· 不要写成背景介绍、经验分享、长篇解释
输入输出写明白指的是：
· 输入是什么：用户给什么、文件在哪、参数是什么
· 输出是什么：生成什么文件、返回什么格式、最终要交付什么结果
不好的写法：
“分析代码库并给出建议。”
更好的写法：
“读取 package.json 和 src/ 下的构建配置，找出构建失败原因。输出一个按严重程度排序的问题列表，并给出最小修改方案。”
4. Test prompts against the skill description to confirm the right trigger behavior.
Codex 会根据 description 做隐式匹配，所以你写完 skill 后，不能只看内容是否正确，还要测“会不会在对的时候被选中，在不对的时候不被选中”。
应该怎么测：
· 用 3 到 5 个“应该触发”的提示词试一下
· 再用 3 到 5 个“看起来有点像，但其实不该触发”的提示词试一下
真正要验证的是：
· description 是否太宽，导致误触发
· description 是否太窄，导致该触发时没触发
· skill 名字、说明、步骤之间是否一致
最后 - 给咱们的参考：一个好的 skill，应该同时满足
· 触发边界清楚
· 步骤可执行
· 结果可检查
· 只有在确实需要时才引入脚本
English
