第一次做一个 instruction-only Skill

这篇开始实操。

第一次做 Skill，不建议加脚本，不建议接 MCP，不建议做复杂插件。

我们先做最稳的一种：

instruction-only Skill

也就是只有说明文件，没有脚本。

前置教程：什么时候应该做 Skill，什么时候继续用提示词
如果你还不能判断一个流程是否值得做 Skill，先看前置教程。

本篇目标

完成后，你会得到一个“写喂饭级教程”的 Skill。

它的目标是：

第 1 步：决定 Skill 放在哪里

新手有两个常见位置：

位置	适合什么
用户级 Skills	你个人所有项目都想用
项目级 `.agents/skills`	当前项目或团队共享

如果这个 Skill 是专门服务本站“Codex喂饭教程”的，建议放项目级：

.agents/skills/tutorial-writing/SKILL.md

如果你想在任何项目都用，才考虑用户级。

本篇以项目级为例。

第 2 步：先让 Codex 设计，不要创建文件

先发：

我想做一个 Codex Skill，用来写“喂饭级中文教程”。

请先只做设计，不要创建文件。

要求：
1. 判断这个流程是否适合做成 instruction-only Skill。
2. 建议 skill name。
3. 建议 description，必须写清楚什么时候触发、什么时候不触发。
4. 设计 SKILL.md 的结构。
5. 说明哪些内容应该留在当前任务提示词里，不应该写进 Skill。

预期结果：

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

第 3 步：确认 name 和 description

可以使用类似：

name: tutorial-writing

注意 description 要包含：

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

不要写得太玄。

错误示例：

帮助写好教程。

太短，Codex 不好判断。

第 4 步：创建 Skill 文件

确认后，让 Codex 创建：

请创建项目级 instruction-only Skill。

路径：
.agents/skills/tutorial-writing/SKILL.md

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

预期文件结构：

.agents/
  skills/
    tutorial-writing/
      SKILL.md

第 5 步：参考 SKILL.md 内容

第一版可以类似这样：

---
name: tutorial-writing
---

# 中文喂饭级教程写作流程

## 目标

把教程写到用户可以照着操作并得到结果。

## 适用场景

- 编写教程文章。
- 编写操作步骤。
- 编写课程内容。
- 把粗略流程扩展成可执行文档。

## 不适用场景

- 普通代码修改。
- 单纯文案润色。
- 只需要回答一个概念问题。

## 必须包含

每篇教程至少包含：

1. 前置教程或前置条件。
2. 本篇目标。
3. 适合谁。
4. 逐步操作。
5. 每一步的预期结果。
7. 常见失败和排查。
8. 验收标准。
9. 下一篇链接或下一步建议。

## 写作规则

- 默认使用简体中文。
- 不要假设用户已经懂术语。
- 不要跳过路径、按钮、命令、预期结果。
- 如果需要用户手动操作，要写清楚点哪里、输入什么、看到什么。
- 如果当前步骤可能因系统、版本、权限不同而变化，要写失败分支。
- 不要编造不存在的命令、菜单或产品能力。

## 最终汇报

完成后说明：

- 写了哪篇教程。
- 放在哪个路径。
- 是否有未验证项。

这只是第一版。

你可以根据站点写作经验继续补。

第 6 步：重新加载或重启 Codex

官方说明里，Codex 通常会检测 Skill 变化。

如果你在界面里看不到新 Skill，可以尝试：

重启 Codex。
在命令菜单里执行类似“Force Reload Skills”的操作。
确认目录路径是否正确。
确认 SKILL.md 的 frontmatter 是否包含 name 和 description。

不要一看不到就乱改内容。

第 7 步：显式触发 Skill

第一次建议显式触发。

可以说：

$tutorial-writing 请帮我写一篇教程：第一次让 Codex 修复前端 Bug。

要求：
1. 按喂饭级教程结构写。
2. 先写草稿，不要创建文件。

预期结果：

Codex 会按 Skill 的结构写。
输出里会有失败分支和验收标准。

第 8 步：验证 Skill 是否真的有用

不要只看它有没有输出。

要看它有没有稳定带来改进。

检查：

检查点	合格表现
是否包含前置	有前置教程或前置条件
是否逐步操作	不跳步
是否有失败分支	不只写成功路径
是否有验收标准	用户知道怎么判断完成
是否避免编造	不写不存在的按钮或命令

如果不合格，先不要怪 Codex。

先改 Skill。

第 9 步：迭代 Skill

可以对 Codex 说：

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

问题：
2. 失败分支不够具体。
3. 验收标准没有写“用户看到什么算成功”。

要求：
1. 只修改 .agents/skills/tutorial-writing/SKILL.md。
2. 不要改其他文件。
3. 修改后总结改了哪些规则。

Skill 不是一次写完。

它应该随着真实使用逐步变稳。

常见错误

错误 1：第一版 Skill 写太大

不要第一次就写：

全能开发专家 Skill

太宽。

先从一个小流程开始。

错误 2：description 太模糊

description 是触发关键。

一定要写清楚适用和不适用场景。

错误 3：把项目规则写进 Skill

比如：

本站品牌名是 Codex喂饭教程。

这更适合 AGENTS.md。

Skill 应该写通用流程。

错误 4：还没验证就加脚本

第一版先 instruction-only。

流程稳定后，再考虑脚本。

这一篇的验收标准

完成后你应该有：

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

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