CX-06 Skills 完整指南

CX 06 Skills 完整指南 CX 06 Skills 完整指南 • 同一流程重复使用三次以上。 • 团队多人需要统一做法。 • 流程包含多个检查步骤。 • 需要附带模板、脚本或参考文档。 • 希望被 Automation 调用。 ⠀ 临时任务不要急着写 Skill。 ⠀ 6. Skills、Commands、Automations 的分工 ⠀ 需求 首选 当前线程快速动作 Command 固定 SOP / 复用流程 Skill 定时或后台重复执行 Automation 外部工具连接 MCP / Connector 打包分发一组能力 Plugin ⠀ 例子： ⠀ • /review 是 Command。 • $code review 是 Skill。 • “每天早上 review 未合并 PR”是 Automation + Skill。 ⠀ 7. 带资源的 Skill ⠀ 复杂 Skill 可以带资源： ⠀ Code block Plain Text my skill/ SKILL.md references/ checklist.md style guide.md scripts/ validate.js ⠀ 原则： ⠀ • 大段参考资料放 references/。 • 重复性强、容易写错的逻辑放 scripts/。 • SKILL.md 只写入口、流程、路由规则和必要摘要。 ⠀ 带脚本的 Skill 要额外写清： ⠀ • 脚本需要什么运行时。 • 是否会写文件。 • 是否会联网。 • 失败时输出什么。 • 是否能在 Windows / macOS 都跑。 ⠀ 不要把一段危险脚本藏在 Skill 里让 App 自动执行。 ⠀ 8. 团队共享 ⠀ 团队共享方式： ⠀ 方式 适合 项目级 .codex/skills/ 当前仓库专用 用户级 skills 目录 个人跨项目复用 Plugin 打包给团队或市场分发 ⠀ 团队 Skill 要避免写个人路径、个人 token、个人偏好。 ⠀ 共享前验收： ⠀ 项 标准 触发 点名和自然语言都能稳定触发 输出 结果格式稳定，方便 Review 权限 不默认要求危险权限 平台 Windows / macOS 路径写法不冲突 资源 references 和 scripts 都能按相对路径找到 维护 有 owner，知道谁负责更新 ⠀ 9. Skill 与插件 ⠀ Plugin 可以携带 Skills，但 Skill 不等于 Plugin。 ⠀ 能力 关系 Skill 一个可复用工作流 Plugin 一个能力包，可以包含多个 Skills、MCP、Apps、配置 ⠀ 当你只需要一个团队审查流程，用 Skill。需要打包 GitHub 连接器、MCP、多个 Skills、配置时，才考虑 Plugin。 ⠀ 10. 常见反模式 ⠀ 反模式 问题 “做高质量代码” 不可验证 在 Skill 里写密钥 安全风险 把工具 API 伪装成 Skill 应该用 MCP 把长期周期任务写成 Skill 应该用 Automation 调用 Skill 一个 Skill 解决所有事 边界过大，难维护 ⠀ 常见问题 ⠀ Q1：Skills 是 slash commands 吗？ ⠀ 不完全是。Skill 可以被点名触发，也可能显示成命令入口，但本质是可复用工作流。 ⠀ Q2：Codex App 会自动加载所有 Skills 吗？ ⠀ 取决于当前会话、项目、用户目录和插件。以 App 当前可见列表为准。 ⠀ Q3：Skill 能运行脚本吗？ ⠀ 可以引用脚本资源，但是否执行取决于权限和当前环境。脚本要最小权限、可审计。 📝 总结与检查清单 ⠀ 完成本课后，请确认以下所有项： ⠀ 理解Skill是可复用工作流，不是快捷命令 知道什么时候该把prompt升级成Skill（重复3次+、团队统一） 能写出规范的SKILL.md（目标明确、步骤可执行、输出稳定） 理解Skill与Command、Automation、MCP、Plugin的分工 知道项目级、用户级、插件级Skill的放置位置 共享前做过触发、输出、权限、平台、资源、维护六维验收 ⠀ 如果以上全部勾选，恭喜你掌握Codex Skills！ 附录 ⠀ A. 能力分工速查 ⠀ 需求 首选 当前线程快速动作 Command 固定SOP/复用流程 Skill 定时或后台重复执行 Automation 外部工具连接 MCP / Connector 打包分发一组能力 Plugin ⠀ B. Skill文件结构 ⠀ Code block Plain Text .codex/skills/my skill/ SKILL.md 入口、流程、规则 references/ 参考文档 scripts/ 可选脚本 ⠀ C. 推荐学习资源 ⠀ • Codex Skills 官方文档：https://developers.openai.com/codex/skills • 本系列上一篇：CX 05 MCP 外部工具 • 本系列下一篇：CX 07 Plugins 连接器 课程制作：老金 最后更新：2026年5月30日 许可：本课程采用CC BY NC SA 4.0许可 • 同一流程重复使用三次以上。 • 团队多人需要统一做法。 • 流程包含多个检查步骤。 • 需要附带模板、脚本或参考文档。 • 希望被 Automation 调用。 ⠀ 临时任务不要急着写 Skill。 ⠀ 6. Skills、Commands、Automations 的分工 ⠀ 需求 首选 当前线程快速动作 Command 固定 SOP / 复用流程 Skill 定时或后台重复执行 Automation 外部工具连接 MCP / Connector 打包分发一组能力 Plugin 需求 需求 首选 首选 当前线程快速动作 当前线程快速动作 Command Command 固定 SOP / 复用流程 固定 SOP / 复用流程 Skill Skill 定时或后台重复执行 定时或后台重复执行 Automation Automation 外部工具连接 外部工具连接 MCP / Connector MCP / Connector 打包分发一组能力 打包分发一组能力 Plugin Plugin ⠀ 例子： ⠀ • /review 是 Command。 • $code review 是 Skill。 • “每天早上 review 未合并 PR”是 Automation + Skill。 ⠀ 7. 带资源的 Skill ⠀ 复杂 Skill 可以带资源： ⠀ ⠀ 原则： ⠀ • 大段参考资料放 references/。 • 重复性强、容易写错的逻辑放 scripts/。 • SKILL.md 只写入口、流程、路由规则和必要摘要。 ⠀ 带脚本的 Skill 要额外写清： ⠀ • 脚本需要什么运行时。 • 是否会写文件。 • 是否会联网。 • 失败时输出什么。 • 是否能在 Windows / macOS 都跑。 ⠀ 不要把一段危险脚本藏在 Skill 里让 App 自动执行。 ⠀ 8. 团队共享 ⠀ 团队共享方式： ⠀ 方式 适合 项目级 .codex/skills/ 当前仓库专用 用户级 skills 目录 个人跨项目复用 Plugin 打包给团队或市场分发 方式 方式 适合 适合 项目级 .codex/skills/ 项目级 .codex/skills/ 当前仓库专用 当前仓库专用 用户级 skills 目录 用户级 skills 目录 个人跨项目复用 个人跨项目复用 Plugin Plugin 打包给团队或市场分发 打包给团队或市场分发 ⠀ 团队 Skill 要避免写个人路径、个人 token、个人偏好。 ⠀ 共享前验收： ⠀ 项 标准 触发 点名和自然语言都能稳定触发 输出 结果格式稳定，方便 Review 权限 不默认要求危险权限 平台 Windows / macOS 路径写法不冲突 资源 references 和 scripts 都能按相对路径找到 维护 有 owner，知道谁负责更新 项 项 标准 标准 触发 触发 点名和自然语言都能稳定触发 点名和自然语言都能稳定触发 输出 输出 结果格式稳定，方便 Review 结果格式稳定，方便 Review 权限 权限 不默认要求危险权限 不默认要求危险权限 平台 平台 Windows / macOS 路径写法不冲突 Windows / macOS 路径写法不冲突 资源 资源 references 和 scripts 都能按相对路径找到 references 和 scripts 都能按相对路径找到 维护 维护 有 owner，知道谁负责更新 有 owner，知道谁负责更新 ⠀ 9. Skill 与插件 ⠀ Plugin 可以携带 Skills，但 Skill 不等于 Plugin。 ⠀ 能力 关系 Skill 一个可复用工作流 Plugin 一个能力包，可以包含多个 Skills、MCP、Apps、配置 能力 能力 关系 关系 Skill Skill 一个可复用工作流 一个可复用工作流 Plugin Plugin 一个能力包，可以包含多个 Skills、MCP、Apps、配置 一个能力包，可以包含多个 Skills、MCP、Apps、配置 ⠀ 当你只需要一个团队审查流程，用 Skill。需要打包 GitHub 连接器、MCP、多个 Skills、配置时，才考虑 Plugin。 ⠀ 10. 常见反模式 ⠀ 反模式 问题 “做高质量代码” 不可验证 在 Skill 里写密钥 安全风险 把工具 API 伪装成 Skill 应该用 MCP 把长期周期任务写成 Skill 应该用 Automation 调用 Skill 一个 Skill 解决所有事 边界过大，难维护 反模式 反模式 问题 问题 “做高质量代码” “做高质量代码” 不可验证 不可验证 在 Skill 里写密钥 在 Skill 里写密钥 安全风险 安全风险 把工具 API 伪装成 Skill 把工具 API 伪装成 Skill 应该用 MCP 应该用 MCP 把长期周期任务写成 Skill 把长期周期任务写成 Skill 应该用 Automation 调用 Skill 应该用 Automation 调用 Skill 一个 Skill 解决所有事 一个 Skill 解决所有事 边界过大，难维护 边界过大，难维护 ⠀ 常见问题 ⠀ Q1：Skills 是 slash commands 吗？ ⠀ 不完全是。Skill 可以被点名触发，也可能显示成命令入口，但本质是可复用工作流。 ⠀ Q2：Codex App 会自动加载所有 Skills 吗？ ⠀ 取决于当前会话、项目、用户目录和插件。以 App 当前可见列表为准。 ⠀ Q3：Skill 能运行脚本吗？ ⠀ 可以引用脚本资源，但是否执行取决于权限和当前环境。脚本要最小权限、可审计。 📝 总结与检查清单 ⠀ 完成本课后，请确认以下所有项： ⠀ 理解Skill是可复用工作流，不是快捷命令 知道什么时候该把prompt升级成Skill（重复3次+、团队统一） 能写出规范的SKILL.md（目标明确、步骤可执行、输出稳定） 理解Skill与Command、Automation、MCP、Plugin的分工 知道项目级、用户级、插件级Skill的放置位置 共享前做过触发、输出、权限、平台、资源、维护六维验收 ⠀ 如果以上全部勾选，恭喜你掌握Codex Skills！ 附录 ⠀ A. 能力分工速查 ⠀ 需求 首选 当前线程快速动作 Command 固定SOP/复用流程 Skill 定时或后台重复执行 Automation 外部工具连接 MCP / Connector 打包分发一组能力 Plugin 需求 需求 首选 首选 当前线程快速动作 当前线程快速动作 Command Command 固定SOP/复用流程 固定SOP/复用流程 Skill Skill 定时或后台重复执行 定时或后台重复执行 Automation Automation 外部工具连接 外部工具连接 MCP / Connector MCP / Connector 打包分发一组能力 打包分发一组能力 Plugin Plugin ⠀ B. Skill文件结构 ⠀ ⠀ C. 推荐学习资源 ⠀ • Codex Skills 官方文档：https://developers.openai.com/codex/skills • 本系列上一篇：CX 05 MCP 外部工具 • 本系列下一篇：CX 07 Plugins 连接器 课程制作：老金 最后更新：2026年5月30日 许可：本课程采用CC BY NC SA 4.0许可 下一步 ⠀ 下一篇：CX 07 Plugins / Connectors：App 能力扩展与账号连接。 主要来源：OpenAI Codex Skills 官方文档、Codex App Features、Plugins 文档。 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：2 3小时 • 难度等级：⭐⭐ 入门级 • 更新日期：2026年5月30日 • 信息来源：OpenAI Codex Skills 官方文档、Codex App Features、Plugins 文档 • 前置要求：已完成 CX 01 安装、CX 02 桌面工作流、CX 03 Commands 📚 本课学习目标 ⠀ 完成本课学习后，你将能够： ⠀ 1. 理解Skill的本质：掌握Skill是可复用工作流，不是快捷命令 2. 判断什么时候升级成Skill：一个流程重复三次以上、团队多人需要时就该沉淀 3. 编写规范的Skill：写出目标明确、触发清晰、步骤可执行、输出稳定的SKILL.md 4. 管理Skill资源：合理组织references/和scripts/，不藏危险脚本 5. 区分Skills与其他能力：清楚Command、Skill、Automation、MCP、Plugin各自的分工 6. 团队共享Skill：通过项目级.codex/skills/或Plugin打包分发 7. 验收Skill质量：触发、输出、权限、平台、资源、维护六维验收 8. 避免Skill反模式：不写不可验证的口号、不写密钥、不伪装工具API 🗺️ 学习路径导航（先看这里！） ⠀ 💡 根据你的情况选择学习路径：不用全看！ 💡 根据你的情况选择学习路径：不用全看！ ⠀ 路径A：快速上手（⏱️ 15分钟） ⠀ 适合人群：想快速写一个团队复用的Skill ⠀ 只看这些章节： ⠀ 路径B：完整学习（⏱️ 2 3小时） ⠀ 适合人群：想系统掌握Skill开发、共享和治理 ⠀ 学习顺序：从头到尾所有章节 1. Skill 是什么 ⠀ Skill 是一组可复用指令、资源和可选脚本。它不是单纯“快捷命令”，而是一套工作流。 ⠀ 适合： ⠀ • 代码审查流程。 • 文档核对流程。 • 发布检查。 • 写作规范。 • 团队固定 SOP。 ⠀ 不适合： ⠀ • 只执行一次的临时任务。 • 需要实时外部 API 的工具连接。 • 需要定时运行的周期任务。 ⠀ 2. App 中怎么调用 Skill ⠀ 常见方式： ⠀ ⠀ 或自然语言触发： ⠀ ⠀ App 也可能通过插件提供 Skills。可用 Skills 取决于当前 App、插件、项目和用户目录。 ⠀ 调用前先确认三件事： ⠀ 1. 当前 App 是否能看到这个 Skill。 2. 这个 Skill 是用户级、项目级，还是插件带来的。 3. 它会不会读取额外资源、运行脚本或调用工具。 ⠀ 如果点名 $skill name 没有触发，先检查名称、路径、插件是否安装，以及 App 当前会话是否已加载。 ⠀ 3. Skill 的文件结构 ⠀ 最小结构： ⠀ ⠀ 放在哪里要分清： ⠀ 位置 适合 项目级 .codex/skills/ 当前仓库专用 SOP 用户级 skills 目录 个人跨项目复用 插件内 Skill 团队或市场分发的能力包 位置 位置 适合 适合 项目级 .codex/skills/ 项目级 .codex/skills/ 当前仓库专用 SOP 当前仓库专用 SOP 用户级 skills 目录 用户级 skills 目录 个人跨项目复用 个人跨项目复用 插件内 Skill 插件内 Skill 团队或市场分发的能力包 团队或市场分发的能力包 ⠀ 项目级 Skill 更适合教程，因为读者打开仓库就能看到规则；用户级 Skill 适合个人工作流，不应该写进团队仓库。 ⠀ 示例： ⠀ ⠀ 4. 好 Skill 的标准 ⠀ 标准 说明 目标明确 一句话说清它解决什么问题 触发清晰 用户点名或描述能稳定触发 步骤可执行 不写空泛原则 输出稳定 有明确交付格式 资源最小 只带必要参考文件和脚本 安全边界明确 写清哪些动作不能做 标准 标准 说明 说明 目标明确 目标明确 一句话说清它解决什么问题 一句话说清它解决什么问题 触发清晰 触发清晰 用户点名或描述能稳定触发 用户点名或描述能稳定触发 步骤可执行 步骤可执行 不写空泛原则 不写空泛原则 输出稳定 输出稳定 有明确交付格式 有明确交付格式 资源最小 资源最小 只带必要参考文件和脚本 只带必要参考文件和脚本 安全边界明确 安全边界明确 写清哪些动作不能做 写清哪些动作不能做 ⠀ 5. 什么时候从 prompt 升级成 Skill ⠀ 满足任一条件就考虑 Skill： ⠀