用 Skills 复用能力

你是 Codex Skill 创建顾问，帮我把一个重复流程做成结构清晰、能被准确触发的 SKILL.md。

【角色】
你熟悉 skill 的基本结构、Codex 如何靠描述选择加载 skill、创建流程、保存位置和分发方式。

【输入】
- 我想沉淀成 skill 的重复流程：___
- 它的触发时机和输入：___
- 期望的输出：___
- 给个人用还是团队分发：___

【工作流程】
1. 提炼这个流程是否够稳定、值得做成 skill
2. 写 SKILL.md 骨架（触发条件 / 输入 / 步骤 / 输出 / 验证 / 边界）
3. 把 name 和 description 写得能被准确触发
4. 给保存位置和分发建议

【输出规范】
▌一、是否值得做成 skill 的判断
▌二、SKILL.md 骨架
▌三、能被准确触发的 name + description
▌四、保存位置 / 分发方式

【硬约束】
- 流程不够稳定时先建议多跑几次再沉淀
- description 要准确反映用途，避免误触发或漏触发
- 边界（不该碰什么）必须写清
- 脚本类 skill 要可审查，不藏黑盒逻辑
- 不确定的 skill 机制标注需查官方文档

Skill 是可复用工作流的编写格式。它把任务说明、资源和可选脚本放进一个目录，让 Codex 在匹配任务时按同一套方法执行。

Skill 解决什么

flowchart LR
    Repeat["重复 prompt / 重复纠错"] --> Skill["Skill"]
    Skill --> Stable["稳定流程"]
    Skill --> Trigger["清楚触发"]
    Skill --> Verify["固定验证"]

适合：

• 文档美化。
• PR review。
• release note。
• 日志分诊。
• migration planning。
• 安全检查清单。
• 固定格式输出。

不适合：

• 一次性任务。
• 还没跑稳的流程。
• 需要大量临场判断的开放问题。
• 只是存放一堆资料的目录。

基本结构

my-skill/
  SKILL.md
  scripts/
  references/
  assets/

SKILL.md 至少要说明：

• skill 名称。
• description：什么时候触发，什么时候不触发。
• 输入。
• 步骤。
• 输出。
• 验证方式。
• 风险边界。

脚本、模板和参考资料只在能提升可靠性时加入。不要为了显得复杂而加文件。

Codex 如何选择 skill

Codex 通常先看到 skill 的 name、description 和路径。只有判断任务需要时，才加载完整 SKILL.md。

所以 description 必须准确：

• 开头写核心任务。
• 写出用户真实会说的触发词。
• 写清不适用场景。
• 避免泛泛写“提高效率”。

描述越泛，误触发越多。

创建流程

推荐顺序：

1. 先用普通 prompt 跑通一次。
2. 重复多次，记录稳定步骤和失败点。
3. 用 $skill-creator 或手动创建 skill。
4. 用真实任务测试触发。
5. 修改 description 和验证步骤。
6. 需要团队分发时，再做 plugin。

Skill 是流程沉淀，不是流程想象。先实践，再封装。

保存位置和分发

官方 skills 支持 CLI、IDE extension 和 Codex app。保存位置决定谁能看到它：

Codex 支持 symlinked skill folders。对于大体积技能库，可以用软链接复用一份主库，避免复制多份。

如果要跨 repo、跨团队分发，或把 skill 与 MCP、app integration 一起打包，使用 plugin。

显式调用和隐式调用

Codex 使用 skill 有两种方式：

• 显式调用：在 CLI/IDE 中用 /skills 或 $skill-name 指定。
• 隐式调用：Codex 根据任务与 description 的匹配自动选择。

隐式调用依赖 description，所以描述要把触发词前置。例如：

---
name: release-note-writer
description: Use when turning merged PRs or git commits into concise release notes. Do not use for general blog writing.
---

这个 description 同时说明“用来写 release notes”和“不用于普通博客”。比“帮助写作”这类泛描述可靠得多。

Progressive disclosure

Skills 的关键机制是 progressive disclosure：Codex 启动时只把 skill name、description 和路径放进上下文；真正需要时才读取完整 SKILL.md。

这意味着：

• SKILL.md 可以放详细步骤，但 description 必须短而准。
• 长参考资料不要塞进 description，放到 references/。
• 大量 skills 会占初始上下文预算，描述会被压缩或省略，所以最重要的触发词要写在开头。
• 如果某个技能必须避免误触发，可以在 agents/openai.yaml 中关闭 implicit invocation，只允许显式调用。

质量检查

一个 skill 合格，应满足：

• 能被正确触发。
• 不会在错误任务中误触发。
• 步骤足够短而明确。
• 输出格式稳定。
• 验证方式可执行。
• 不包含密钥或私有路径。
• 修改后能在干净任务中复验。

Skill 的目标是让 Codex 少问重复问题、少犯重复错误、按稳定标准交付。

官方资料

• Agent Skills
• Build plugins
• Agent Skills specification