Skip to content

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 通常放在:

text
.agents/skills/<skill-name>/SKILL.md

个人长期使用的 Skill 可以放在用户级 Codex 目录;具体目录和加载范围以当前客户端文档为准。仓库级 Skill 适合团队共享,个人 Skill 适合不应该提交到仓库的偏好和辅助流程。

一个最小 Skill 示例:

markdown
---
name: release-notes
description: 根据当前 Git diff 生成中文发布说明,并列出验证命令。用于准备版本发布或 PR 描述。
---

1. 读取当前 Git diff 和相关提交信息。
2. 区分用户可见变化、修复、风险和未完成事项。
3. 不推测 diff 中没有出现的功能。
4. 输出标题、摘要、验证结果和发布前检查项。

Skill 应该只负责一个相对明确的工作,不要从“写发布说明”扩展成“管理整个软件生命周期”。范围越小,触发和验证越稳定。

如何创建和使用 Skill? ​

可以在 Codex 中使用 $skill-creator 让它先生成一个草稿,再人工检查目录、触发描述、脚本和验收标准。使用前确认:

  1. Skill 是否解决了一个真实、重复出现的问题。
  2. 输入和输出是否清楚。
  3. 规则是否与仓库 AGENTS.md 冲突。
  4. 脚本是否只访问必要文件,是否会修改外部系统。
  5. 是否有一个可以重复运行的示例任务。

在 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 中使用:

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 查看是否已加载。把触发条件写成用户真实会说的话,比写抽象口号更容易匹配。

继续阅读:Codex 提示词与 AGENTS.md 教程、Codex 配置参考 和 官方 Skills 文档。

非 Google 官方网站。内容用于中文用户了解 Gemini 模型与可用入口。