Codex Skills、插件与 MCP 入门:把重复工作变成可复用流程
当你已经多次对 Codex 重复说明同一套流程,例如“先读需求、生成测试、运行构建、检查 diff、写发布说明”,可以把这套做法整理成 Skill。Skill 的核心不是一段更长的提示词,而是一个带有 SKILL.md 的工作流目录,里面可以放说明、模板、脚本和参考资料。
Codex Skill 是什么?
一个 Skill 通常包含:
SKILL.md:名称、触发描述和具体步骤。scripts/:需要重复执行的脚本。references/:较长的规范、接口说明或样例。assets/:模板、配置样例和其他资源。
官方文档强调,Codex 会先读取 Skill 的名称和描述,再在任务匹配时加载完整的 SKILL.md。因此名称和描述应该清楚写出“做什么、什么时候使用”,不要把所有背景一次性塞进描述。
广告|AI 工作流体验入口
如果你想先用中文整理代码规范、提示词模板或项目文档,再把成熟流程做成 Codex Skill,可以查看以下第三方 AI 平台。它们与 OpenAI 官方插件和 Codex Skill 体系没有直接关联,敏感代码和内部规则请先脱敏。
Skill 放在哪里?
Codex 支持按范围组织 Skills。仓库内的项目 Skill 通常放在:
.agents/skills/<skill-name>/SKILL.md个人长期使用的 Skill 可以放在用户级 Codex 目录;具体目录和加载范围以当前客户端文档为准。仓库级 Skill 适合团队共享,个人 Skill 适合不应该提交到仓库的偏好和辅助流程。
一个最小 Skill 示例:
---
name: release-notes
description: 根据当前 Git diff 生成中文发布说明,并列出验证命令。用于准备版本发布或 PR 描述。
---
1. 读取当前 Git diff 和相关提交信息。
2. 区分用户可见变化、修复、风险和未完成事项。
3. 不推测 diff 中没有出现的功能。
4. 输出标题、摘要、验证结果和发布前检查项。Skill 应该只负责一个相对明确的工作,不要从“写发布说明”扩展成“管理整个软件生命周期”。范围越小,触发和验证越稳定。
如何创建和使用 Skill?
可以在 Codex 中使用 $skill-creator 让它先生成一个草稿,再人工检查目录、触发描述、脚本和验收标准。使用前确认:
- Skill 是否解决了一个真实、重复出现的问题。
- 输入和输出是否清楚。
- 规则是否与仓库
AGENTS.md冲突。 - 脚本是否只访问必要文件,是否会修改外部系统。
- 是否有一个可以重复运行的示例任务。
在 CLI 或 IDE 中,可以通过 /skills 查看可用技能,或在提示词里用 $skill-name 明确调用。修改 Skill 后,如果当前客户端没有立即显示新内容,按官方说明重启或刷新技能列表。
Skill、插件和 MCP 有什么区别?
| 能力 | 主要作用 | 适合解决的问题 |
|---|---|---|
| Skill | 固化步骤、约束和输出格式 | 每次都要按同一流程完成的工作 |
| 插件 | 分发一个或多个 Skill,也可以包含连接器 | 团队或社区共享一套工作流 |
| MCP | 提供外部系统的工具和数据连接 | 读取工单、文档、数据库或其他服务 |
三者可以组合:Skill 规定“先查什么、怎么判断、输出什么”,MCP 提供真实数据和动作,插件负责把它们打包给其他人使用。不要用 Skill 模拟一个需要实时权限控制的外部系统,也不要把密钥直接写进 Skill 文件。
用 config.toml 管理 Skill
Codex 的个人配置通常在 ~/.codex/config.toml,项目级配置可以放在仓库的 .codex/config.toml。官方配置文档说明,CLI 和 IDE 扩展会共享这些配置层;项目配置只应在你信任仓库内容时启用。
如果需要临时停用某个 Skill,可以在 ~/.codex/config.toml 中使用:
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false修改后按官方说明重启 Codex,让配置重新加载。
配置文件可以管理默认模型、审批策略、沙盒和 MCP,但不要把 API Key、个人令牌或生产凭据写进 Git 仓库。需要共享时,提交不含秘密的配置样例,并在部署环境中注入凭据。
一个适合团队的 Skill 工作流
第一步:从重复返工中选题
记录团队经常重复纠正的问题,例如测试漏跑、发布说明缺字段、代码审查遗漏权限边界。
第二步:写出最小 SKILL.md
只保留触发条件、输入、步骤、输出和停止条件。把长篇规范放进 references/,把确定性检查放进脚本。
第三步:用真实任务试跑
至少用一个正常样例和一个边界样例测试。观察 Skill 是否误触发、是否读取了不必要的文件、是否输出了无法验证的结论。
第四步:加入项目验证
如果 Skill 会修改代码,明确要求运行相关测试、lint、构建或安全检查,并让最终输出包含实际命令和结果。
第五步:定期复盘
当 Codex 连续犯同一种错误时,先判断是提示词、AGENTS.md、Skill 还是项目脚本的问题,再只修改最接近问题的那一层。
安全注意事项
- Skill 和插件里的脚本同样需要代码审查。
- 外部 MCP 服务器可能访问项目以外的数据,先确认权限和网络范围。
- 不要把生产密钥、客户资料和内部访问令牌写进 Markdown、TOML 或示例文件。
- 网络、发布、删除、迁移和写入外部系统的动作应保留审批。
- 对团队共享的 Skill 固定版本,并记录变更原因。
常见问题
Skill 和 AGENTS.md 应该怎么分工?
AGENTS.md 适合整个仓库长期遵守的项目规则;Skill 适合一个可触发、可复用的具体流程,例如生成发布说明或执行日志排查。两者都应该短、准确、可验证。
Skill 需要写很多示例吗?
不需要。先提供一个正常样例和一个边界条件,确认触发与输出稳定后再扩展。过多示例会让真正的规则变得不清楚。
MCP 是否等同于联网搜索?
不是。MCP 是连接外部工具和数据的协议,具体能访问什么取决于服务器、认证和权限配置。联网搜索只是可能的一类工具能力。
为什么 Codex 没有自动选择我的 Skill?
先检查 SKILL.md 是否存在、名称和描述是否清晰、目录是否在当前客户端扫描范围内,再用 /skills 查看是否已加载。把触发条件写成用户真实会说的话,比写抽象口号更容易匹配。