Codex Skills

最后校验：2026-05-30

OpenAI Codex 支持 agentskills.io 风格的 SKILL.md，但在发现路径、显式触发、sidecar 元数据、API 使用方式上有自己的扩展。写跨平台 Skill 时，建议把通用能力放在 SKILL.md，把 Codex 专属内容放在 agents/openai.yaml。

与开放规范的关系

Codex 读取的核心仍是：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中 SKILL.md 的 frontmatter 至少包含：

---
name: my-skill
description: Use when ...
---

name 和 description 是 Codex 判断是否使用 Skill 的关键。正文只有在 Skill 被触发后才会加载。

安装与发现路径

Codex 推荐使用 .agents/skills/，而不是 .codex/skills/。

常见位置：

Scope	位置	适用场景
项目级	<project>/.agents/skills/	随仓库共享的团队 Skill
子目录级	<project>/<module>/.agents/skills/	monorepo 中只对某个模块生效
用户级	$HOME/.agents/skills/	个人跨项目复用
系统级	/etc/codex/skills/	机器或容器级预装

在 monorepo 中，可以把全局 Skill 放在仓库根，把局部 Skill 放在子模块目录。Codex 从当前工作目录向上发现可用 Skill。

触发方式

Codex 支持两种触发方式。

方式	说明	适用场景
隐式触发	Codex 根据 description 判断是否加载	希望自然语言自动命中
显式触发	通过 /skills 或 $<skill> 指定	知道要用哪个 Skill，或调试触发问题

示例：

$pdf-form-filler 帮我提取这份合同里的金额条款

显式触发适合：

• 新 Skill 调试期
• description 还不稳定
• 多个 Skill 语义接近
• 需要强制指定某个工作流

agents/openai.yaml

Codex 的平台特有配置不写进 SKILL.md frontmatter，而是放在：

my-skill/
└── agents/
    └── openai.yaml

常见结构：

interface:
  display_name: "PDF 表单填写器"
  short_description: "处理 PDF 文件抽取、表单填写、合并"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional prompt prefix when invoked"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://example.com/mcp"

interface.*

用于 Codex App 或相关界面展示：

• display_name
• short_description
• icon_small
• icon_large
• brand_color
• default_prompt

这些字段不影响开放规范下的 Skill 能否运行，但能改善 Codex 生态内的展示和安装体验。

policy.allow_implicit_invocation

用于控制是否允许 Codex 自动触发：

policy:
  allow_implicit_invocation: false

设置为 false 后，只能通过 $<skill> 或 /skills 显式调用。

这和 Claude Code 的 disable-model-invocation: true 不是同一个字段，也不在同一个文件里。

跨平台手动触发配置通常要同时写：

# SKILL.md
---
name: dangerous-operation
description: Use when ...
disable-model-invocation: true
---

# agents/openai.yaml
policy:
  allow_implicit_invocation: false

dependencies.tools

用于声明 Skill 依赖的工具，例如 MCP server。这样安装或使用时更容易知道它需要哪些外部能力。

写作建议：

• 工具依赖只写 Codex 专属 sidecar。
• SKILL.md 正文仍应说明何时使用该工具。
• 多 MCP 环境中，正文里使用全限定工具名。

Codex Skill 与 Plugin

Codex 生态中可能同时看到 Skill 和 Plugin。

概念	定位	内容
Skill	创作格式	一个可复用工作手册，核心是 SKILL.md
Plugin	分发单位	可以打包多个 Skill、MCP 配置、UI 元数据或 app 集成

如果只是团队内部复用工作流，Skill 目录通常足够。

如果要面向 Codex 市场或更完整的 app 集成分发，才需要考虑 Plugin。

OpenAI API 中的 Skills

OpenAI API 也支持在 shell environment 中引用 Skill。典型用法是把 Skill 上传后，在 Responses API 的 shell 工具环境里通过 skill_reference 使用。

概念示例：

response = client.responses.create(
    model="gpt-5.2",
    tools=[{
        "type": "shell",
        "environment": {
            "type": "container_auto",
            "skills": [
                {"type": "skill_reference", "skill_id": "<skill_id>"},
            ],
        },
    }],
    input="使用配置的 skill 分析 CSV 并输出报告"
)

API 模式需要额外关注：

• 上传方式：目录 multipart 或 zip
• 版本引用：latest 或指定版本
• 文件数量与包大小限制
• shell 环境类型：托管容器或本地 shell
• Skill 指令在提示中的优先级

这些限制可能随 OpenAI API 更新而变化，生产使用前应查看最新 OpenAI 文档。

跨平台写作建议

目标	建议
最大兼容	SKILL.md 只使用 agentskills.io 通用字段
Codex 展示体验	增加 agents/openai.yaml
禁止隐式触发	Claude 与 Codex 两边字段都写
依赖 MCP	Codex 依赖写 sidecar，正文写使用条件
团队共享	优先放项目级 .agents/skills/
个人复用	放 $HOME/.agents/skills/

最小 Codex 兼容目录

my-skill/
├── SKILL.md
└── agents/
    └── openai.yaml

其中 agents/openai.yaml 可选；没有它时，Codex 仍可根据 SKILL.md 使用 Skill。

常见坑

• [ ] 把 Codex Skill 放到 .codex/skills/ 而不是 .agents/skills/
• [ ] 只写 disable-model-invocation，忘了 policy.allow_implicit_invocation
• [ ] 把 agents/openai.yaml 字段误写进 SKILL.md frontmatter
• [ ] description 写了执行步骤，导致正文不被认真读取
• [ ] MCP 依赖只在 sidecar 声明，正文没说何时使用
• [ ] 面向 API 使用时没有检查上传限制和版本引用

下一步

• 通用字段看 SKILL.md。
• 放置层级看 四级生态。
• 发布前质量验证看 评估 Skill。