agentmentoragentmentor

第 07 节:让 Codex 生成一门课

本节 objectives:

  • 能说明 Codex skill 如何被显式或隐式触发。
  • 能用一句话触发 generate-course-from-topic,再用 guard 验收。
  • 能判断"一句话触发"什么时候够,什么时候要补边界。

先修:会处理权限、联网和工作树边界 ｜ 上一节 << 06 ｜ 下一节:无

一句话可以触发,但交付不能只靠一句话

OpenAI 的 Codex skills 文档说明,skill 是带 SKILL.md 的目录,可以包含指令、资源、脚本等;Codex 会先看到 skill 的 name、description 和路径,只有决定使用时才读取完整 SKILL.md。1 它也支持显式调用和隐式调用:你可以直接提到 skill,也可以让任务匹配 description。1

本仓库的 generate-course-from-topic 正是为"我想学 X / 给我做一门 X 的课 / teach me X / 产一门课 / learn-X"这类话设计的。它的 README 也把"为什么一句话就能触发"解释为:Codex 先看到 skill 的 name 和 description,任务匹配后再读取完整 SKILL.md 并执行。23

所以答案是:对轻量用户,一句话足够启动;对可发布课程,一句话只够触发,还要补主题边界、来源边界和验收命令。

讲解

这门课程生成 skill 的本地契约很明确:

  • 先用宿主 agent 的搜索/浏览能力取材;没有联网能力就请用户提供可靠资料,不能假装搜索。4
  • 课程结构固定:README.md、若干 NN-*.md、sources.md、glossary.json。4
  • 正文关键事实要用脚注形式引到 sources.md;每个 sources 块要有 - 权威:。45
  • 写完要跑 node scripts/course-guard.mjs <课目录>,失败就修。5

一句话触发的好处是低摩擦:

text
我想学 MCP server basics。

但如果你关心质量,应该加边界:

text
用 generate-course-from-topic 给我做一门 MCP server basics 课。受众:会 TypeScript、没写过 MCP。来源:优先官方 MCP 文档,关键事实要引用。节数:6 节左右。写完跑 node scripts/course-guard.mjs <课程目录>,修到通过。

跟我做一遍(worked example)

目标:让 Codex 生成一门"如何使用 Codex"课程。

可执行 prompt:

text
用 generate-course-from-topic 给我做一门"如何使用 Codex"的课。受众:已经装好 Codex 的新用户。范围:如何提任务、让 Codex 读项目、看 plan/status、审 diff、跑测试、处理权限/联网/工作树、让 Codex 生成课程。来源:Codex/OpenAI 产品事实只用 OpenAI 官方域;本 skill 机制用本地 SKILL.md、guide、templates、guard 和 README。交付到 agent-mentor/skills/generate-course-from-topic/examples/learn-using-codex/。写完跑 node scripts/course-guard.mjs agent-mentor/skills/generate-course-from-topic/examples/learn-using-codex。

这条 prompt 仍然像一句自然语言,但它补了四个关键边界:受众、范围、来源和验收。对课程这种会被别人复用的产物,这比"我想学 Codex"稳得多。

换你补全(faded example)

你想生成一门"如何写 PR review"课程。请补全:

text
用 ____________________ 给我做一门 ____________________。受众: ____________________。范围: ____________________。来源: ____________________。验收: ____________________。

参考答案:

text
用 generate-course-from-topic 给我做一门"如何写 PR review"。受众:会 Git、第一次做代码审查的新工程师。范围:读需求、看 diff、找风险、写 actionable comment、复查修复。来源:优先团队本地规范和官方平台文档;不要用无来源博客当关键事实。验收:写到 learn-pr-review/ 并跑 node scripts/course-guard.mjs <课程目录>。

关键判断点是:一句话负责启动,边界负责质量。

小结 + 通向下一节

Codex skills 让一句自然语言触发复杂工作流成为可能。课程生成 skill 的设计目标就是低摩擦启动:用户说想学什么,Codex 读取 SKILL.md,取材、写课、跑 guard。

但你已经学完这门课,所以不要停在魔法感。真正可靠的 Codex 使用方式是:一句话启动,清楚边界,真实来源,可复查 diff,可运行验证。

Footnotes

  1. Agent Skills — https://developers.openai.com/codex/skills ↩ ↩2

  2. agent-mentor-skill README ↩

  3. course-authoring-guide.md ↩

  4. generate-course-from-topic SKILL.md ↩ ↩2 ↩3

  5. course-guard.mjs ↩ ↩2

练习

Level 1: 写一条一句话触发 prompt。

提示 1

初学者入口可以一句话。

提示 2

发布样例要补边界。

提示 3

最终信任来自 sources 和 guard,不是来自 Codex 说"完成了"。

自评