Codex 把 skill 看成 workflow authoring format：一份 SKILL.md 加上脚本、参考资料和资源，让 Codex 在某类任务里稳定复用步骤。它的关键取舍是：skill 负责写工作流，plugin 负责安装与分发。

这和“把所有东西都塞进 SKILL.md”正好相反。Codex 支持本地、项目、用户、管理员和系统级 skill，但真正可分发的包通常是 plugin。plugin 可以包含多个 skills，也可以包含 MCP 配置、app mappings、展示资源和其他安装 metadata。

Codex 要回答的是：团队 workflow 怎样随仓库、用户环境和 Codex app/CLI/IDE 一起工作，而不把文件格式变成完整 package manager。

.agents/skills 是这个设计里最有意思的一点。它不是 .codex/skills，而是更通用的 repo-level agent 目录。这说明 Codex 在鼓励团队把“这个仓库怎么 review、怎么发版、怎么跑 eval”沉淀成跨 agent 的项目资产。

Codex 同时要管理上下文预算。它会让模型先看到 skill 的轻量列表，再在选中后读取完整内容。这意味着 description 不只是简介，而是压缩后的路由索引；太泛的描述会浪费上下文，太长的描述又可能被截断。

Codex 的使用面比单一终端更宽：CLI、IDE extension、Codex app、后台工作树、插件生态都可能加载 skill。如果把安装、UI、MCP、依赖和工作流全部写进 SKILL.md，文件格式会迅速膨胀。

所以 Codex 做了分层：SKILL.md 写 agent 应该如何执行任务；plugin 和 agents/openai.yaml 一类 metadata 写如何在 Codex 产品中发现、展示、依赖和分发。

• .agents/skills 之外的 Codex-specific 安装假设。
• agents/openai.yaml 中的 UI metadata、依赖、隐式调用策略。
• Codex sandbox、approval、worktree、plugin 可用性。
• 对 Codex app / CLI / IDE extension 的界面假设。
• “plugin 已安装，所以 skill 一定可用”的隐含前提。

Codex adapter 应该写这个 skill 放在 repo、用户级还是 plugin 中；是否允许隐式调用；依赖哪些 Codex 插件或 MCP；脚本是否需要 sandbox 放行；最终产出怎样在 Codex app/CLI/IDE 中呈现。portable core 仍只写任务流程。

• OpenAI Codex: Agent Skills
• Agent Skills specification

继续阅读