Codex Skill 教程：SKILL.md 创建、安装、调用与 Plugins 区别

先给结论：一个 Skill 只解决一个可重复的工作

Skill 是一个目录，核心是带有名称、描述和完整流程的 SKILL.md；还可以带脚本、参考资料和模板。Codex 会先读取技能列表中的名称、描述和路径，只有选择使用时才加载完整说明，这种方式可以避免每个对话都塞入所有流程细节。

适合做 Skill 的例子包括：按固定模板审查 PR、生成每周进度、从指定数据源制作简报、按团队标准创建发布说明。一次性的模糊任务、需要频繁临场判断但没有稳定流程的工作，不必强行做成 Skill。

Codex Skill、Plugin、MCP 和普通提示词有什么区别

如果只是要 Codex 遵循一个稳定流程，先用 Skill；如果要把多个 Skills 和连接器打包给别人安装，使用 Plugin；如果核心需求是让 Codex调用一个外部系统，重点在 MCP 或连接器。一个 Plugin 可以同时包含 Skill 和 MCP 配置。

官方参考：Skills & Plugins。

SKILL.md 与目录结构

my-skill/
├── SKILL.md          # 必需：元数据与完整工作流
├── scripts/          # 可选：稳定、可审查的执行脚本
├── references/       # 可选：规范、字段说明、示例
├── assets/           # 可选：模板与资源
└── agents/
    └── openai.yaml   # 可选：显示、调用策略和依赖

SKILL.md 至少要有 name 和 description。描述负责帮助 Codex判断何时使用，正文负责真正执行：

---
name: release-notes
description: 为已经合并且有可验证变更的版本生成中文发布说明；不用于规划尚未实现的功能。
---

# 工作流
1. 读取版本范围和变更记录。
2. 只写可以从提交、PR 或测试证明的变化。
3. 按新增、修复、兼容性与升级说明输出。
4. 缺少版本范围或证据时先请求补充，不猜测。

description 不要写成“万能开发助手”。它应前置关键触发词、明确输入和边界，否则隐式匹配会过宽或根本选不到。

创建 Codex Skill：从真实重复任务开始

1. 选择一个聚焦任务

   记录实际输入、当前人工步骤、完成标准和常见失败。不要同时塞入写文档、部署、客服和财务四套流程。

2. 先写说明版本

   把决策顺序、必需证据、停止条件和输出格式写入 SKILL.md。官方当前建议默认先做 instruction-only。

3. 用官方创建器辅助

   在 Codex 中显式调用 $skill-creator，说明用途、触发条件、输出和禁区；也可以手动创建目录与 SKILL.md。

4. 只在必要时增加脚本

   重复、机械且适合测试的步骤才写脚本。脚本必须有明确输入输出、错误处理，不能默默上传文件或扩大权限。

5. 用真实但非敏感样例测试

   至少测试正常输入、缺少输入、边界输入和不该触发的请求，并核对结果是否满足完成标准。

如果一个流程更容易演示而不是描述，OpenAI 当前还提供 Record & Replay，可从示范步骤起草 Skill；生成后仍应人工审查触发条件、权限和输出。

官方参考：Build skills。

Skill 放在哪里：项目、仓库与个人范围

Codex 会从当前工作目录向仓库根扫描项目技能。两个 Skill 使用同名时不会自动合并，因此团队应保持可识别名称，避免“同名但不同规则”让使用者选错。软链接目录也需要审查实际目标。

如何调用 Skill：显式调用与隐式匹配

• 显式调用：在 CLI / IDE 中运行 /skills 或输入 $ 选择 Skill；适合你明确知道要用哪个流程时。
• 隐式调用：当请求与 Skill 的 description 匹配时，Codex 可以自动选择。
• 关闭隐式调用：需要只允许手动选择的高风险流程，可在可选元数据中设置调用策略。
• 没有出现：先核对目录、SKILL.md 元数据和扫描作用域；官方当前说明变更通常会自动检测，未出现时再重启 Codex。

显式调用不代表可以跳过权限审批。Skill 只是工作流说明；文件、命令、网络和外部工具仍受当前 Sandbox、Approval、组织策略与工具自身权限控制。希望 Skill 周期运行时，先阅读 Codex Automations 定时任务教程，并在 Scheduled Prompt 中显式指定 $skill-name。

测试与调试：不要只看“它成功运行了一次”

更新 Skill 时像更新代码一样查看 diff。改变触发范围、权限建议、脚本命令或外部依赖属于实质变更，应重新测试并在团队内说明。

安装第三方 Skill 前的安全检查

1. 阅读完整 SKILL.md，确认它何时触发、会读取什么、会修改什么。
2. 检查 scripts/、依赖、下载地址、网络请求和环境变量，不只看 Skill 名称。
3. 核对 agents/openai.yaml 中声明的 MCP 或工具依赖与调用策略。
4. 优先在测试仓库和最小权限模式运行，先查看计划和命令。
5. 第三方更新后重新审查；不要因为它来自热门仓库就默认安全。
6. 卸载或停用不再使用的 Skill，避免旧流程继续被隐式匹配。

如果还没有添加 Server，先看Codex MCP 配置与 codex mcp add 教程；已经出现启动、握手或工具超时时进入Codex MCP 排查；如果修改配置后无法启动，进入config.toml 配置排查。

Codex Skills 常见问题

Codex Skill 是什么？

Skill 是面向一个聚焦任务的可复用工作流，可以把说明、参考资料、模板和可选脚本放在同一目录中。

Codex Skill 怎么调用？

CLI / IDE 可用 /skills 或 $ 显式选择；请求与 description 匹配时也可以隐式选择。

SKILL.md 应该放在哪里？

项目和仓库技能通常放在可扫描到的 .agents/skills；个人技能放在用户级 .agents/skills。按需要选择作用域。

Codex Skill、Plugin 和 MCP 有什么区别？

Skill 封装工作流；Plugin 用于安装和分发 Skills、连接器或 MCP 配置；MCP 用来连接外部工具和上下文。

Codex Skill 可以包含脚本吗？

可以，但应优先写清说明，只在需要稳定机械执行时增加脚本，并审查权限、网络和依赖。

为什么 Codex 没有自动使用我的 Skill？

先检查 description 是否明确包含真实触发词、Skill 是否处于当前扫描作用域、元数据是否有效。需要确定使用时直接显式调用。

Skill 和 AGENTS.md 有什么区别？

AGENTS.md 提供进入某个代码范围时持续适用的项目指令；Skill 是按任务选择的可复用工作流。两者可同时存在，发生冲突时还要遵守当前环境的指令优先级。

如何分享自己写的 Skill？

仓库范围可以随代码提交 .agents/skills；希望跨项目安装、组合多个 Skills 或连接器时，按官方当前方式打包为 Plugin。