第一次做一个 instruction-only Skill

这篇开始实操。

第一次做 Skill，不建议加脚本，不建议接 MCP，不建议做复杂插件。我们先做最稳的一种：


instruction-only Skill


也就是只有说明文件，没有脚本。
> 前置教程：什么时候应该做 Skill，什么时候继续用提示词
> 如果你还不能判断一个流程是否值得做 Skill，先看前置教程。
学习目标
完成后，你会得到一个“Bug 修复流程”的 Skill。它的目标是：


让 Codex 每次修 Bug 时都先复现、再定位、再最小修改、最后检查和汇报。


第 1 步：决定 Skill 放在哪里
新手有两个常见位置：
| 位置 | 适合什么 |
| :--- | :--- |
| 用户级 Skills | 你个人所有项目都想用 |
| 项目级 .agents/skills | 当前项目或团队共享 |
如果这个 Skill 是专门服务当前项目的 Bug 修复流程，建议放项目级：


.agents/ecosystem/skills/bugfix-flow/SKILL.md


如果你想在任何项目都用，才考虑用户级。本篇以项目级为例。
第 2 步：先让 Codex 设计，不要创建文件
先发：


我想做一个 Codex Skill，用来沉淀“Bug 修复标准流程”。
请先只做设计，不要创建文件。
要求：


判断这个流程是否适合做成 instruction-only Skill。

2. 建议 skill name。
3. 建议 description，必须写清楚什么时候触发、什么时候不触发。
4. 设计 SKILL.md 的结构。
5. 说明哪些内容应该留在当前任务提示词里，不应该写进 Skill。


预期结果：

Codex 不创建文件。
Codex 会给出名称和描述。
Codex 会说明适用和不适用场景。

第 3 步：确认 name 和 description
可以使用类似：

`yaml


name: bugfix-flow


注意 description 要包含：

触发词。
适用任务。
不适用任务。
关键输出要求。

不要写得太玄。错误示例：


帮助写好教程。


太短，Codex 不好判断。
第 4 步：创建 Skill 文件
确认后，让 Codex 创建：


请创建项目级 instruction-only Skill。
路径：
.agents/ecosystem/skills/bugfix-flow/SKILL.md
要求：


只创建这个 Skill 文件和必要目录。

2. 不要修改其他项目代码。
3. SKILL.md 必须包含 name 和 description。
5. 不要加入脚本。
6. 创建后告诉我文件路径。


预期文件结构：


.agents/
skills/
bugfix-flow/
SKILL.md


第 5 步：参考 SKILL.md 内容
第一版可以类似这样：

`markdown


name: bugfix-flow
description: 修复 Bug 时使用。适合用户提供现象、复现步骤、错误日志或失败截图，并要求 Codex 做最小修复、运行项目已有检查、用中文汇报风险。
Bug 修复标准流程
目标
让 Codex 修 Bug 时先确认问题，再做最小修改，最后给出可检查的结果。
适用场景

用户提供了错误现象。
用户提供了失败截图、日志或复现步骤。
某个功能表现和预期不一致。
构建、测试或页面交互出现明确失败。

不适用场景

新功能需求设计。
大范围重构。
单纯文案调整。
只有一句“帮我优化一下”的模糊任务。

必须包含
每次修 Bug 至少包含：


先复述问题现象和预期结果。
2. 说明准备检查哪些文件或模块。
3. 优先做只读分析，不要直接大改。
4. 找到原因后做最小修改。
5. 修改后检查 diff，说明是否有无关改动。
6. 运行项目已有检查；不能运行时说明原因。
7. 最后用中文汇报修改文件、原因、验证结果和风险。

执行规则

默认使用简体中文。
不要为了修一个 Bug 顺手重构无关代码。
不要修改接口协议、权限、支付、数据库等高风险逻辑，除非任务明确要求。
不要编造不存在的测试命令。
如果发现需求不清楚，先提问。
如果发现影响范围变大，先说明风险，再等用户确认。

最终汇报
完成后说明：


修改了哪些文件。
为什么这样改。
做了哪些检查。
哪些地方没有验证。
是否还有剩余风险。


这只是第一版。你可以根据站点写作经验继续补。
第 6 步：重新加载或重启 Codex
官方说明里，Codex 通常会检测 Skill 变化。如果你在界面里看不到新 Skill，可以尝试：


重启 Codex。
在命令菜单里执行类似“Force Reload Skills”的操作。
确认目录路径是否正确。

确认 SKILL.md 的 frontmatter 是否包含 name 和 description。


不要一看不到就乱改内容。
第 7 步：发起第一次显式触发测试
第一次建议显式触发。可以说：


$bugfix-flow 修复登录页手机号校验问题。
要求：


先只读分析，不要直接修改文件。

2. 说明你准备检查哪些文件。
3. 找到原因后再给出修复方案。


预期结果：

Codex 会先复述问题和预期。
Codex 会先做只读分析。
Codex 会给出更稳定的修复流程。

第 8 步：验证 Skill 是否真的有用
不要只看它有没有输出。要看它有没有稳定带来改进。
检查点：
| 检查点 | 合格表现 |
| :--- | :--- |
| 是否先复述问题 | 说明现象、预期和影响范围 |
| 是否先只读分析 | 不直接大范围改文件 |
| 是否最小修改 | 只改和 Bug 直接相关的地方 |
| 是否有检查结果 | 说明运行了什么检查或为什么没运行 |
| 是否避免编造 | 不写不存在的命令或结论 |
如果不合格，先不要怪 Codex。先改 Skill。
可以对 Codex 说：


请根据刚才 Skill 输出的问题，帮我改进 bugfix-flow 的 SKILL.md。
问题：


没有要求先复述问题。

2. 没有强调最小修改。
3. 最终汇报没有说明未验证项。
要求：


只修改 .agents/ecosystem/skills/bugfix-flow/SKILL.md。

2. 不要改其他文件。
3. 修改后总结改了哪些规则。


Skill 不是一次写完。它应该随着真实使用逐步变稳。
常见新手错误
错误 1：第一版 Skill 写太大

不要第一次就写：全能开发专家 Skill。太宽。先从一个小流程开始。


错误 2：description 太模糊
description 是触发关键。一定要写清楚适用和不适用场景。
错误 3：把项目规则写进 Skill

比如：本站品牌名是 Codex喂饭教程。 这更适合 AGENTS.md。Skill 应该写通用流程。


进阶方向
第一版先 instruction-only。流程稳定后，再考虑脚本。
总结
完成后你应该有：

一个项目级 bugfix-flow Skill。

一个有效的 SKILL.md`。
一次显式触发测试。
一次输出质量检查。
至少一条可迭代改进建议。

下一步可以进入 Hooks：当你不仅想“提醒 Codex 怎么做”，还想在关键动作前后做自动检查时，就需要 Hooks。