如何在团队中分发 Codex Skill 并管理触发条件与权限

团队已有一项检查每周报告的 skill，但只有作者的电脑能看到。队友各自复制的版本逐渐产生差异。把 skill 放在代码仓库中，Codex 就能为同一团队加载它，前提是位置正确、说明明确，并在队友的电脑上测试。预留约一小时。你需要仓库、已能运行的 skill、审阅人和试用者。

准备工作

**工具：**本地 Codex、团队 Git 仓库以及 OpenAI 的 Build skills 指南。本文假定 skill 已有 SKILL.md。如果尚未创建，请先看为具体流程创建 Codex skill 的方法。这里讨论分发与管理，而非重新编写工作流程。

**参与者：**skill 负责人、仓库审阅人、试用者；如需插件、MCP 或公司权限，还应有管理员。指定每次发布的负责人。

**输入：**skill 文件夹，以及两条测试请求，一条应该触发 skill，一条不应该。不要把凭据或客户数据提交到仓库。

分步操作

1. 移动文件前，先选好共享范围

团队需要在一个仓库、多个仓库，还是多个产品里使用它？根据 OpenAI Learn，Codex 从仓库、个人、管理员和系统内置位置加载 skill。小团队共用一个仓库时，可从仓库内的 .agents/skills 开始，用 Git 审阅变更。

如果整个仓库都需要，就把 skill 放在仓库根目录对应的位置。如果只服务某个子区域，就放在该区域的上级目录。Codex 会从当前工作目录一路向上到仓库根目录扫描 .agents/skills。因此要在队友实际工作的目录测试。

~/.agents/skills 属于个人，不会随 Git 自动分发给队友。/etc/codex/skills 属于受管理的环境。如果要跨多个仓库分发，或同时附带连接，可参考 OpenAI 的插件分发指南。插件有自己的安装路径。

2. 检查 metadata，让 Codex 找到正确的 skill

SKILL.md 必须有 name 和 description。**Description 影响隐式调用：**Codex 先看名称和描述，选中后才读取完整指令。初始列表可能缩短描述，所以开头就要写明主要工作和边界。

检查周报的 skill 只应在核对数字与来源时使用，而不应服务所有办公室任务。metadata 示例：

---
name: weekly-status-check
description: Verify dates, owners, figures, and source links in a weekly status report. Use for report review; do not use for drafting emails or publishing updates.
---

如果团队只想让用户明确点名调用，可以在可选的 agents/openai.yaml 中设置策略。OpenAI 说明 allow_implicit_invocation 默认为 true；改成 false 会停止隐式选择，但仍允许在 Codex 中明确使用 $skill。

interface:
  display_name: "Weekly Status Check"
  short_description: "Review figures and sources before sharing a weekly report"
policy:
  allow_implicit_invocation: false

这只是可选 metadata，并非数据访问权限。该文件还可声明所依赖的 MCP 工具，但声明不会自动登录外部账号。

3. 把 skill 放进仓库，像业务变更一样审阅

把目录放在 .agents/skills/weekly-status-check/。审阅 SKILL.md、参考资料、脚本和资源。脚本实际做的事可能比简短描述更多，共享前要检查影响。

拉取请求应说明谁会使用、何时应触发，以及测试结果。这是建议的团队流程，不是 Codex 强制的安装步骤。把广泛适用的团队规则留在 AGENTS.md；skill 只写一项工作的步骤。

4. 在队友电脑上测试，而不只在作者电脑上测试

让队友更新仓库，在预期工作目录打开 Codex，检查 skill 列表。在 CLI 或 IDE 扩展中，可使用 /skills 或输入 $ 来调用；在支持的 ChatGPT 界面中，可用 @ 选择。新变更若未出现，按 OpenAI 指南重启 Codex。

运行两种情况：周报请求应该选择 skill，写邮件请求不应该。再明确调用 $weekly-status-check，检查 Codex 是否读到步骤、参考资料和工具。如果隐式匹配不准确，修改描述并重试。Codex 不会合并同名 skill；两项都可能显示在选择器中。检查个人和仓库副本是否重名，避免误用旧版。

若测试需要修改文件或联网，另行检查 Codex 权限。Skill 指令不会扩大运行时权限。设计不接触生产数据的试验时，可参考如何限定 Codex 的安全修改范围。

5. 判断何时改用插件或其他管理路径

当大家都拉取同一仓库并在正确目录启动 Codex，仓库 skill 很合适。若涉及多个仓库、MCP 连接或可安装资源，插件可能更适合。OpenAI 的 Skill controls区分仓库 skill、ChatGPT 工作区 skill、插件内 skill。在这些路径间移动文件，不会自动转移所有权、角色、插件安装状态或连接权限。

插件可用于网页、桌面和移动端的 ChatGPT Chat 与 Work，也可用于桌面应用内的 Codex 和 Codex CLI 的插件浏览器。OpenAI 指出插件不在 IDE 扩展中使用。独立的 skill 文件夹可用于桌面应用、Codex CLI 和 IDE 扩展。因此应根据队友真正使用的界面选分发路径，并在那里测试。

插件若连接外部系统，管理员必须分别管理插件与连接权限。安装插件不会自动授予 connector 或 MCP server 的访问权。“已共享 skill”不等于“大家都能读取同一份公司数据”。来源系统仍控制自己的账号和资源。

6. 分发后安排复查

记录负责人、仓库或插件版本、两条测试请求和复查日期。流程有变化时，只改权威版本，再让队友重跑测试。Skill 若不再安全或有用，可通过经过审阅的仓库变更移除。个人也能在 ~/.codex/config.toml 的 [[skills.config]] 中禁用本地 skill，然后重启 Codex。这个个人设置不是整个公司的统一停用开关。

结果示例

四人团队把 weekly-status-check 放在仓库根目录的 .agents/skills 下。负责人缩小 description 的范围，审阅人查看 SKILL.md 和参考文件。队友在仓库中打开 Codex，看见该 skill，用示例报告调用 $weekly-status-check，得到需要核实的日期、数字和来源清单。写邮件请求不会触发它。这是验收标准示例，并不是在你的仓库中实际运行的结果。

第二个团队要在另一个仓库复用时，负责人考虑插件。迁移前，写清支持的界面、需要的 MCP 工具以及谁可以使用连接。复制 skill 文件夹不会带走数据访问权。

改善分发效果的技巧

• 一项 skill 对应一项明确工作。 名称和描述越精准，越容易正确触发。广泛规则放在别处。
• 同时测试隐式和显式调用。 出现在列表中，并不证明自然语言请求能正确触发。
• 用 Git 管理变更。 与 SKILL.md 一起审阅参考资料和脚本，在拉取请求或团队文档中保存测试请求。
• 记录启动目录。 如果队友在仓库相应目录范围之外启动 Codex，目录范围的 skill 可能不出现。
• 分开 skill 分发与数据授权。 分别测试获准用户和无权用户的 MCP 与来源账号权限。

需要了解的限制

Metadata 不是安全边界。 allow_implicit_invocation: false 只改变选择方式，用户仍可明确调用。文件、网络、插件和外部数据权限都要独立控制。

Skill 列表可能缩短。 安装很多 skill 时，Codex 可能缩短描述，甚至从初始列表略去部分条目并给出警告。这不代表选中后的完整 SKILL.md 被截断。描述保持简洁，必要时试用明确调用。

文件夹与插件覆盖范围不同。 仓库文件夹不会自动在 ChatGPT 网页或移动端可用。插件有自己的支持界面，也不会出现在 IDE 扩展中。全公司推广前，检查产品和权限。

常见问题

把 skill 放进 ~/.agents/skills 会共享给队友吗？ 不会。这是个人位置。同仓库团队应放在仓库的 .agents/skills，并分发仓库变更。

Skill 已在仓库里，却没在 Codex 中出现，怎么办？ 确认 Codex 打开的目录和分支，检查 skill 结构；若变更仍未被识别，重启 Codex。

Codex 会把两个同名 skill 合并成新版吗？ 不会。两者都可能显示。应改名或清理旧版，避免误用。

关闭隐式调用会阻止用户运行 skill 吗？ 不会。allow_implicit_invocation: false 仍允许在 Codex 中用 $skill 明确调用。

安装含 skill 的插件会自动获得 MCP 和公司数据权限吗？ 不会。插件、连接、来源账号各有独立控制，管理员要分别配置和测试。

OpenAI Learn 官方来源：Build skills、Skill controls和 CLI customization。访问日期：2026 年 10 月 5 日。