详解 skill-creator

skill-creator 是一个“创建 Skill 的 Skill”。它不负责某个具体业务，而是指导 Codex 把专业知识、固定流程、脚本和模板封装成可自动触发、可重复使用的能力包。

我已按它自身的说明完整检查过规范；这次只是讲解，没有创建或修改文件。

1. Skill 到底是什么

可以把 Skill 理解为给 Codex 准备的一份“岗位操作手册 + 工具箱”。

普通提示词只对当前对话有效；Skill 则是一个持久化目录，Codex遇到匹配的请求时可以自动加载。

例如：

• pdf Skill：告诉 Codex 如何创建、编辑和验证 PDF。
• weekly-to-monthly-report Skill：把周报转换成月报。
• company-data-query Skill：记录公司数据库结构、指标口径和查询流程。
• deploy-service Skill：封装发布流程、检查命令和回滚规则。

它尤其适合：

• 经常重复出现的任务
• 有固定操作顺序的流程
• Codex 本身不知道的公司内部知识
• 必须稳定执行的脚本操作
• 需要复用模板、图片、字体或代码骨架的任务

2. Skill 的标准结构

最小 Skill 只需要一个 SKILL.md：

my-skill/
└── SKILL.md

完整结构通常是：

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

各部分职责如下。

SKILL.md

这是 Skill 的核心，包含：

---
name: my-skill
description: 这个 Skill 做什么，以及什么请求应该触发它。
---

# 操作说明

按照以下步骤处理任务……

其中 YAML 头部只应包含：

• name
• description

不要随意增加版本号、作者、标签等字段。

agents/openai.yaml

这是面向 Codex 界面的展示信息，例如：

• 展示名称
• 简短说明
• 默认提示语

它主要影响 Skill 在界面中的显示，而不是核心执行逻辑。推荐通过生成脚本创建，不要手工猜测格式。

scripts/

存放需要稳定执行、反复使用的程序。

例如：

scripts/
├── rotate_pdf.py
├── validate_report.py
└── convert_dates.sh

适合放入脚本的内容：

• 每次都要重新编写的代码
• 容易出错的文件操作
• 输出必须确定一致的转换逻辑
• 多步骤 API 或数据处理过程

脚本必须实际运行测试，不能只检查代码看起来是否正确。

references/

存放需要按需读取的专业资料，例如：

• 数据库表结构
• API 文档
• 指标口径
• 公司政策
• 行业规则
• 详细工作流
• 大型示例

例如：

references/
├── database-schema.md
├── metrics.md
└── api.md

这些内容不应全部塞进 SKILL.md，否则每次触发 Skill 都会占用大量上下文。

assets/

存放用于制作最终结果、但通常不需要阅读的素材，例如：

• Word、PPT 模板
• Logo 和图片
• 字体
• HTML/React 项目骨架
• Excel 模板
• 示例配置文件

例如：

assets/
├── report-template.docx
├── logo.png
└── frontend-template/

3. Skill 如何被触发

Skill 使用三级渐进式加载。

name + description
        ↓ 匹配请求
SKILL.md 正文
        ↓ 任务需要
scripts / references / assets

第一级：元数据

Codex平时只看到 Skill 的：

• name
• description

因此，description 是最重要的触发机制。

错误示例：

description: 帮助处理报告。

问题是过于模糊，不知道处理什么报告、执行什么操作、什么情况下使用。

更好的写法：

description: Convert pasted Chinese weekly work reports into a concise monthly report and a one-sentence summary. Use when the user asks for 月报、本月总结、周报汇总、按点总结本月工作，或要求总结以“本月较好的完成了”开头。

它同时说明了：

• Skill 能做什么
• 输入是什么
• 输出是什么
• 中文触发词是什么
• 哪些用户场景应该使用

关键规则：所有“什么时候使用”信息都应写在 description 中，不要只写在正文里的“适用场景”章节。因为 Skill 尚未触发时，Codex看不到正文。

第二级：SKILL.md

只有匹配后，Codex才读取正文。

因此正文应集中写：

• 操作步骤
• 判断规则
• 文件使用方式
• 输出要求
• 验证标准
• 异常处理

第三级：资源文件

Codex根据任务再决定是否读取参考资料、运行脚本或使用素材。

这叫“渐进式披露”，目的是节省上下文。

4. Skill 的三种自由度

skill-creator 强调：指令精细程度要与任务风险相匹配。

高自由度

适合有多种正确方法的任务，使用原则和文字指导即可。

例如文章审稿：

检查文章的主张、证据、结构和实用性。根据文章类型决定检查重点。

中自由度

适合有推荐流程，但允许根据情况调整的任务。

例如：

解析输入
→ 判断报告类型
→ 提取工作成果
→ 合并重复事项
→ 生成月报

可以配合伪代码或带参数脚本。

低自由度

适合容易出错、顺序严格、结果必须一致的任务。

例如生产发布、财务计算、文件格式转换，应提供：

• 明确命令
• 固定脚本
• 参数约束
• 验证步骤
• 失败处理

原则是：越像“窄桥”，护栏越具体；越像“开阔地”，越应保留判断空间。

5. 官方创建流程

skill-creator 规定了六个阶段。

第一步：收集具体使用案例

不要一开始就写 SKILL.md。先明确用户真正会怎样提出请求。

需要弄清：

• Skill 要支持哪些任务？
• 哪些任务明确不支持？
• 用户会怎样表达？
• 哪些话应触发它？
• 输入和输出分别是什么？
• Skill 要安装在哪里？

例如创建图片编辑 Skill，可以先确定：

• 是否支持旋转？
• 是否支持去背景？
• 是否支持批量处理？
• 是否保留 EXIF？
• 用户可能说“把图片转正”还是“旋转 90 度”？

具体案例决定触发描述和操作流程。

第二步：规划可复用资源

逐个分析案例：

1. 如果从零处理，要做哪些事？
2. 哪些代码会重复写？
3. 哪些知识会重复查？
4. 哪些模板会重复制作？

对应关系是：

第三步：初始化目录

新 Skill 应使用 init_skill.py 初始化，不建议手工拼结构。

基本形式：

scripts/init_skill.py <skill-name> \
  --path <目标目录> \
  --resources scripts,references,assets

例如：

scripts/init_skill.py release-notes-writer \
  --path "${CODEX_HOME:-$HOME/.codex}/skills" \
  --resources scripts,references

如果用户未指定安装位置，默认使用：

$CODEX_HOME/skills

如果没有设置 CODEX_HOME，则使用：

~/.codex/skills

这样 Codex 可以自动发现 Skill。

初始化工具会：

• 创建 Skill 目录
• 创建带占位内容的 SKILL.md
• 创建 agents/openai.yaml
• 按要求创建资源目录
• 可选生成示例文件

如果生成了示例占位文件，完成后必须替换或删除。

第四步：实现 Skill

建议先完成资源，再写最终说明：

1. 编写并测试脚本
2. 整理参考资料
3. 放入必要模板和素材
4. 编写精简的 SKILL.md
5. 生成或更新 agents/openai.yaml

SKILL.md 正文使用命令式表达，例如：

1. Read the input report.
2. Extract completed work and measurable results.
3. Merge duplicate items.
4. Generate the monthly summary.
5. Verify that no unsupported facts were added.

而不是写成介绍性文章。

第五步：验证

完成后运行：

scripts/quick_validate.py <skill目录>

它主要检查：

• YAML 格式
• 是否存在必填字段
• Skill 名称是否合法
• 目录名与 Skill 名是否匹配

注意：这个验证只能发现结构问题，不能证明业务逻辑真的有效。

第六步：实际使用和迭代

完整循环是：

真实任务
→ 观察失败或低效之处
→ 修改说明、脚本或资料
→ 再次验证
→ 再做真实测试

复杂 Skill 还应使用一个上下文干净的独立执行环境做“前向测试”，避免测试者因为提前知道预期答案而产生虚假成功。

6. 命名规范

Skill 名称应满足：

• 仅使用小写字母、数字和连字符
• 不超过 64 个字符
• 文件夹名和 name 完全一致
• 优先使用简短、动作导向的名称
• 必要时加入工具命名空间

正确示例：

write-release-notes
convert-weekly-reports
gh-address-comments
linear-address-issue

不推荐：

My Skill
report_skill
A-Very-Long-And-Vague-Utility

7. 一个最小示例

假设要创建 convert-meeting-notes：

convert-meeting-notes/
├── SKILL.md
└── agents/
    └── openai.yaml

SKILL.md 可以写成：

---
name: convert-meeting-notes
description: Convert raw Chinese or English meeting notes into structured minutes containing decisions, action items, owners, deadlines, and unresolved questions. Use when the user asks to 整理会议纪要、提取待办、总结会议决定、生成 action items, or clean up raw meeting transcripts.
---

# Meeting Notes Conversion

1. Read the complete source notes.
2. Separate confirmed decisions from proposals and discussion.
3. Extract each action item with its owner and deadline.
4. Mark missing owners or deadlines as “待确认”; do not invent them.
5. List unresolved questions separately.
6. Produce the result in the user's source language.

Use this output structure:

- Meeting summary
- Decisions
- Action items
- Open questions

Preserve names, dates, quantities, and technical terms exactly.

这个 Skill 不需要脚本，因为主要是语言判断，属于高到中自由度任务。

如果要求读取固定会议系统的 JSON，则可以增加：

scripts/parse_meeting_export.py
references/export-schema.md

8. 常见错误

把所有内容塞进 SKILL.md

结果是每次触发都加载大量无关信息。详细资料应放到 references/。

描述写得太抽象

“处理文档”“帮助写作”几乎无法可靠触发。要写清任务、文件类型、用户场景和典型触发词。

在正文中才说明触发条件

Codex在 Skill 触发前看不到正文，所以不起作用。

为 Skill 创建大量辅助文档

规范明确不建议创建：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

除非它们本身是执行 Skill 必需的资源，否则只会制造噪声。

写了脚本但没有运行

脚本必须通过真实输入测试。语法正确不代表输出正确。

重复存储相同知识

同一内容不要既写在 SKILL.md，又复制到 references/。核心步骤留在正文，细节放参考资料。

参考文件嵌套过深

最好让所有参考文件都能从 SKILL.md 直接找到，避免：

SKILL.md → A.md → B.md → C.md

把 Skill 写成面向人的教程

Skill 的读者首先是另一个 Codex 实例。应告诉它“如何执行”，而不是花大量篇幅介绍背景。

9. 判断一个 Skill 是否优秀

一个成熟 Skill 通常满足以下条件：

• 用户的典型表达能够稳定触发
• 不相关请求不会误触发
• SKILL.md 足够短，核心步骤清楚
• 详细知识可以按需定位
• 重复操作已脚本化
• 脚本经过实际运行
• 不会编造缺失数据
• 有清晰的完成标准
• 能处理典型异常输入
• 换一个全新的 Codex 上下文仍能正确执行

最核心的设计思想可以概括为一句话：

把“触发条件”写进描述，把“执行方法”写进 SKILL.md，把“确定性操作”写进脚本，把“详细知识”放进参考资料，把“输出素材”放进 assets。