Agent Skills代理技能是 Codex 的任务扩展机制通过将指令、资源和可选脚本打包为标准化技能包让 Codex 能够可靠地执行特定工作流。Agent Skills代理技能核心为一个文件夹文件夹内必须包含SKILL.md文件。该文件至少需填写名称、描述等元数据同时附带指引告诉智能代理如何完成特定任务。技能包还可集成脚本、参考资料、模板及其他各类资源。my-skill/ ├── SKILL.md # 必备文件元数据 执行指引 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 ├── assets/ # 可选模板、各类资源文件 └── ... # 其他额外文件与目录术语说明AI agentsAI智能代理行业通用译法Agent Skills代理技能专属概念保留固定称谓metadata元数据workflows业务流程/执行流程什么是 Agent SkillsSkills 是可复用工作流的编写格式。每个 Skill 本质上是一个包含 SKILL.md 文件的目录Codex 读取其中的指令并按步骤执行。你可以把 Skill 理解为给 Codex 写的标准操作流程——定义清楚做什么、什么时候做、怎么做Codex 就能在合适的时机自动激活它或者在你明确调用时执行它。Skills 是编写格式Plugins插件是分发格式。先用 Skills 设计工作流本身需要分发给其他开发者时再打包为 Plugin。Skills 在 Codex CLI、IDE 扩展和 Codex App 中均可使用。可以在插件中查看或创建 SkillsCodex 自带 Skill Creator点击上图中的 Creat skill 就会跳转到创建 Skill 的窗口我们可以直接告诉它做什么 Skill查看已安装 Skills技能工作原理Codex 采用 渐进式信息披露Progressive Disclosure 机制来管理上下文窗口避免一次性加载所有技能内容挤占提示词空间。渐进式加载流程Codex 启动时只会加载每个技能的名称、描述和文件路径作为初始列表。只有当 Codex 决定使用某个技能时才会加载完整的 SKILL.md 指令内容。为了不挤占提示词空间初始技能列表的字符数被限制在模型上下文窗口的 约 2%或上下文窗口未知时的 8,000 个字符。如果安装了过多技能Codex 会先缩短描述文字如果仍然超出限制部分技能可能不会出现在初始列表中Codex 会显示警告。这个预算限制仅针对初始技能列表。Codex 选中某个技能后仍然会读取该技能的完整 SKILL.md 文件。两种触发方式Codex 支持两种技能激活方式显式调用在提示词中直接引用技能。在 CLI 或 IDE 中使用 /skills 命令或输入 $ 符号来指定一个技能。显式调用时Codex 不需要做任何匹配判断直接加载完整 SKILL.md 并执行。隐式匹配当你发出的任务描述与某个技能的 description 字段匹配时Codex 会自动选择该技能。隐式匹配的准确性完全取决于 description 字段的编写质量。编写 description 时要前置核心用例和触发关键词这样即使描述被缩短Codex 仍然能正确匹配。技能目录结构一个 Skill 是一个包含 SKILL.md 文件的目录可以包含可选的脚本、参考文档、资源文件和元数据配置。my-skill/ ├── SKILL.md # 必备项使用指引 元数据 ├── scripts/ # 可选可执行代码 ├── references/ # 可选参考文档 ├── assets/ # 可选模板、各类资源 └── agents/ └── openai.yaml各文件/目录的职责如下文件/目录是否必填说明SKILL.md必填技能的核心指令文件必须包含 name 和 description 字段scripts/可选存放可执行代码用于需要确定性行为或调用外部工具的场景references/可选存放额外的参考文档供 Codex 在执行技能时查阅assets/可选存放模板、图片等静态资源文件agents/openai.yaml可选配置 UI 元数据、调用策略和工具依赖声明快速开始创建你的第一个技能推荐使用内置的技能创建器来快速生成技能框架。使用 skill-creator 创建在 Codex 中输入以下命令即可启动交互式创建流程实例# 启动技能创建器$skill-creator创建器会依次询问以下问题步骤问题说明1这个技能做什么定义技能要完成的任务2什么时候触发决定是显式调用还是隐式匹配触发3纯指令还是包含脚本默认推荐纯指令模式简洁且易维护手动创建你也可以手动创建技能目录和 SKILL.md 文件实例---name: my-skilldescription: 说明这个技能应该在什么时候触发、什么时候不触发。---Codex 将遵循以下技能指令执行任务。Codex 会自动检测技能文件的变更。如果更新后技能没有立即生效请重启 Codex。配置说明技能存储位置Codex 会从仓库级别、用户级别、管理员级别和系统级别四个范围读取技能。对于仓库级别Codex 会从当前工作目录向上一直扫描到仓库根目录查找 .agents/skills 目录。如果两个技能具有相同的 nameCodex 不会合并它们两者都会出现在技能选择器中。作用范围存储路径适用场景REPO$CWD/.agents/skills当前工作目录下的技能适用于特定模块或微服务的团队共享技能REPO$CWD/../.agents/skills上级目录中的技能适用于嵌套目录结构中的共享区域REPO$REPO_ROOT/.agents/skills仓库根目录的技能适用于整个仓库所有子目录共享的基础技能USER$HOME/.agents/skills用户的个人技能集适用于该用户在任何仓库中都能使用的技能ADMIN/etc/codex/skills机器或容器级别的共享技能适用于 SDK 脚本、自动化和管理员默认技能SYSTEM由 OpenAI 内置打包面向广泛受众的内置技能如 skill-creator 和 plan 技能所有用户启动 Codex 即可使用Codex 支持技能目录的符号链接扫描时会跟随符号链接目标。以上路径适用于本地开发和发现。如需将技能分发给单个仓库之外的用户或将其与应用集成一起打包请使用 Plugins 机制。启用与禁用技能在 ~/.codex/config.toml 中使用 [[skills.config]] 配置项可以在不删除文件的情况下禁用技能实例# 文件路径~/.codex/config.toml[[skills.config]]path /path/to/skill/SKILL.mdenabled false修改配置文件后需要重启 Codex 才能生效。可选元数据配置在 agents/openai.yaml 中可以为技能配置 UI 元数据、调用策略和工具依赖声明实例# 文件路径agents/openai.yaml# 界面配置控制技能在 Codex App 中的显示方式interface:display_name: 面向用户的显示名称short_description: 面向用户的简短描述icon_small: ./assets/small-logo.svgicon_large: ./assets/large-logo.pngbrand_color: #3B82F6default_prompt: 与技能一起使用的可选外围提示词# 策略配置控制技能的调用行为policy:allow_implicit_invocation: false # 设为 false 可禁用隐式匹配# 依赖配置声明技能所需的工具dependencies:tools:- type: mcpvalue: openaiDeveloperDocs # MCP 服务器名称description: OpenAI Docs MCP servertransport: streamable_http # 传输协议url: https://developers.openai.com/mcp # MCP 服务地址allow_implicit_invocation 的默认值为 true。设为 false 后Codex 不会根据用户提示词隐式调用该技能但显式的 $skill 调用仍然有效。配置项类型默认值说明interface.display_name字符串空在 Codex App 中显示的名称interface.short_description字符串空在 Codex App 中显示的简短描述interface.icon_small路径空小图标路径SVG 格式interface.icon_large路径空大图标路径PNG 格式interface.brand_color颜色值空品牌色用于界面展示interface.default_prompt字符串空使用该技能时的默认外围提示词policy.allow_implicit_invocation布尔值true是否允许 Codex 隐式匹配并调用该技能dependencies.tools数组空声明技能依赖的 MCP 工具每项需指定 type、value、description 等技能分发与安装通过 Plugins 分发技能直接的技能文件夹适用于本地编写和仓库范围的工作流。如果需要分发可复用的技能、将多个技能打包在一起、或将技能与应用集成一起发布应该打包为 Plugin。一个 Plugin 可以包含一个或多个技能还可以选择性打包应用映射、MCP 服务器配置和展示资源。安装精选技能使用 $skill-installer 可以安装内置技能之外的精选技能到本地 Codex 环境中。例如安装 $linear 技能实例# 安装 linear 技能到本地 Codex$skill-installer linear你也可以通过 skill-installer 从其他仓库下载技能。Codex 会自动检测新安装的技能如果没有立即出现重启 Codex 即可。skill-installer 适用于本地设置和实验。如需将你自己的技能进行可复用分发请优先使用 Plugins 机制。最佳实践原则说明适用场景一个技能只做一件事保持每个技能职责单一避免技能承担过多不相关任务所有技能都应遵循指令优先于脚本能用指令描述的流程就不要写脚本除非需要确定性行为或调用外部工具大部分场景推荐纯指令模式指令使用祈使句式用祈使句编写步骤明确每个步骤的输入和输出编写 SKILL.md 指令时测试 description 的匹配效果用实际提示词测试是否能正确触发技能确保 description 的精准度编写完技能后前置核心触发词将关键使用场景和触发词放在 description 前面确保缩短后仍能匹配description 可能被截断时常见问题技能更新后没有生效Codex 会自动检测技能文件的变更。如果更新后技能没有出现在列表中重启 Codex 即可。两个技能重名会怎样Codex 不会合并同名技能两者都会出现在技能选择器中。建议在不同的作用范围中避免使用相同的技能名称以免造成混淆。隐式匹配不准确怎么办首先检查 description 是否清楚地描述了该技能的使用场景和边界。将核心触发词前置避免关键信息出现在描述的后半部分。如果不需要隐式匹配可以在 agents/openai.yaml 中将 allow_implicit_invocation 设为 false。什么时候用 Skills什么时候用 PluginsSkills 是编写格式适合本地开发和仓库内的团队共享。当你需要将技能分发给其他开发者、打包多个技能、或与应用集成一起发布时使用 Plugins 格式。初始技能列表被截断怎么处理精简每个技能的 description使其简短且精准。确保最核心的触发词出现在 description 的最前面这样即使被缩短也能正确匹配。对于当前任务不常用的技能可以考虑暂时禁用。