Skill 与 Codex Skills
Skill 用可复用的说明、参考资料和可选脚本，让 Agent 稳定遵循一类任务流程。
学习目标
- 能说明Skill 与 Codex Skills解决什么问题，以及何时适用。
- 能解释为什么“把 Skill 当成 Tool”是误区。
学习前需要掌握
背景与问题
重复处理报告、数据或代码时，每次重新粘贴长流程容易遗漏步骤，也难以维护统一版本。Skill 把可复用方法与本次任务输入分开，让同一工作有稳定的触发范围、资料和交付要求。
Skill 的价值不在于增加一层提示词，而在于把何时使用、需要什么输入、怎样验证和何时停止写清楚。一次性用户请求仍然需要提供真实文件、目标与授权。
概念定义
OpenAI 当前文档将 Skill 描述为包含 instructions、resources 与 optional scripts 的能力包；Codex 以包含 SKILL.md 的目录组织 Skill。
直观理解
Prompt 是这次工作的请求，Skill 是一本会在合适任务中启用的作业手册。Tool 是手里的器械，MCP 是连接外部器械和资料的协议。
核心原理
Skill 以包含 SKILL.md 的目录组织，名称与描述帮助发现和匹配，正文描述具体工作流程。触发说明应足够窄，既能覆盖目标任务，也能排除名字相近但实际不适用的工作。
渐进式加载先使用简短描述判断相关性，命中后阅读完整指令，长参考资料再按需要读取。references 可以保存规则细节，assets 可以保存模板；不能只因资源存在就全部加载或使用。
可选 scripts 承担适合确定性执行的部分，例如检查文件格式。脚本仍受路径、环境与权限约束，不能因来自 Skill 就免除输入验证；指令也应明确失败时保留哪些证据，而不是要求无条件执行到底。
维护时应测试正例、近似反例和缺失输入。流程更新要同时核对相对路径与资源版本，避免正文要求调用已经删除的脚本。下方 Markdown 展示的是目录与 SKILL.md 的写法示意，并没有包含验证脚本的实现。
案例：把本地报告审阅做成可复用 Skill
触发条件可以是“已提供本地报告，需要按检查表审阅”，正文要求先识别报告格式，再按需加载检查表，最后返回带位置的发现与未解决问题。报告路径是本次输入，检查表是可维护资源，输出模板可放在 assets。
若用户只问“如何写报告”，这个 Skill 不应因为出现“报告”二字就执行文件检查。若缺少检查表或脚本，系统应指出具体缺失，而不是虚构验证结果。这种正反例检验比只确认 SKILL.md 能被读取更接近实际质量。
理解与实践步骤
- 确定一个稳定且可复用的工作
- 写清触发范围与不适用范围
- 在 SKILL.md 编写可执行步骤
- 把长资料放 references
- 仅把确定性或外部操作放 scripts
- 准备模板到 assets
- 用正反例测试触发与结果
- 记录版本和兼容性
代码实现
示例 1
最小 SKILL.md 与目录结构
example_01.py用途：展示当前 OpenAI 文档所述的必需文件、渐进加载资源和清晰触发描述。
my-skill/
├─ SKILL.md
├─ references/
│ └─ checklist.md
├─ scripts/
│ └─ validate.py
└─ assets/
└─ report-template.md
---
name: local-report-review
description: Review a local report against the supplied checklist. Use only when a report file is provided.
---
1. Read the report and identify its format.
2. Load references/checklist.md only when checking coverage.
3. Run scripts/validate.py only after validating the input path.
4. Return findings, evidence, and unresolved questions.代码解析
解析始终位于完整代码下方，并按实际代码段逐项对应。
输入数据与任务
展示当前 OpenAI 文档所述的必需文件、渐进加载资源和清晰触发描述。
Step 1 · 1–8 行
name 和 description 用于发现与匹配。
my-skill/
├─ SKILL.md
├─ references/
│ └─ checklist.md
├─ scripts/
│ └─ validate.py
└─ assets/
└─ report-template.mdStep 2 · 10–13 行
正文给出命令式步骤和明确输入输出。
---
name: local-report-review
description: Review a local report against the supplied checklist. Use only when a report file is provided.
---Step 3 · 15–18 行
references、scripts、assets 按需使用，不应无条件全部加载。
1. Read the report and identify its format.
2. Load references/checklist.md only when checking coverage.
3. Run scripts/validate.py only after validating the input path.
4. Return findings, evidence, and unresolved questions.预期输出或运行结果
Agent 在匹配的报告审查任务中读取完整 SKILL.md，并按需加载检查表或运行验证脚本。
常见错误 · 3 条
- description 写成“处理所有任务”，导致误触发并加载大量无关上下文。
- 把 Skill 说明当作工具权限，或把目录示意中的脚本路径当成已经存在的实现。
- 只测试理想输入，不检查近似反例、资源缺失、相对路径和脚本失败情况。
实际应用
- 文档制作流程
- 代码审查规范
- 本地数据处理
常见错误
- description 写成“处理所有任务”，导致误触发并加载大量无关上下文。
- 把 Skill 说明当作工具权限，或把目录示意中的脚本路径当成已经存在的实现。
- 只测试理想输入，不检查近似反例、资源缺失、相对路径和脚本失败情况。
输入、输出与执行边界
输入
- 任务描述
- Skill 元数据
- 按需加载的参考资料
输出
- Agent 应遵循的流程
- 可选脚本或资产产生的结果
能力
- 文档制作流程
- 代码审查规范
- 本地数据处理
安全风险与信任边界
Skill 中的脚本和说明来自具体文件与维护者，名称和描述不能替代对来源及实际操作的核对。执行时仍需依据当前任务判断路径、参数和副作用；文档里的示例命令不应因被加载就自动成为本次必须执行的动作。
性能与失败模式
有用的 Skill 应减少重复探索并提升可复查性，过大的说明或过多重叠流程也会增加上下文与执行成本。可以用相同任务比较完成质量、人工修正和调用开销，并在工具或接口变化后检查示例是否仍有效。
推荐学习资料
参考库不会生成虚假资源或无效外部链接。