技能目录的设计初衷与架构定位
OpenAI Skills Catalog 的核心目标是解决 AI Agent 能力复用的问题。在传统的 AI 应用开发中，每个团队或项目往往需要重复编写相似的功能模块 —— 代码审查、数据分析、文档生成等。Skills Catalog 通过标准化的技能包格式，将这些通用能力封装为可发现、可复用、可分发的独立单元。
从架构视角来看，Skills Catalog 扮演着 Codex 运行时能力注册中心的角色。它定义了技能如何声明、如何组织、如何被发现以及如何被加载的完整生命周期规范。这种设计将能力的定义与能力的执行解耦，使得技能的开发者可以专注于功能实现，而使用者则可以通过简单的引用即可获得完整的能力支持。Skills Catalog 本身在 GitHub 上已获得 4.8k 星标，说明社区对其架构设计的认可。
技能清单的 Schema 设计
技能的核心描述文件是 SKILL.md，它采用 YAML 前置元数据配合 Markdown 说明文档的结构。这种格式选择具有明确的工程考量：YAML 提供了良好的可读性和结构表达能力，而 Markdown 则适合承载复杂的使用说明和示例代码。OpenAI 官方文档明确指出，这种设计是为了将指令、资源和可选脚本打包成可复用的工作流单元。
YAML 前置元数据中包含两个必需字段。name 字段用于标识技能的全局唯一名称，长度限制在 100 个字符以内，且必须为非空字符串。description 字段则承担着技能描述和匹配检索的功能，长度上限为 500 个字符，Codex 在进行隐式技能匹配时会参考该字段的内容。一个典型的技能元数据块如下所示：
---
name: draft-commit-message
description: Draft a conventional commit message when the user asks for help writing a commit message.
---
值得注意的是，Codex 在运行时仅将 name 和 description 两个字段注入上下文环境。这意味着即使 SKILL.md 中包含其他 YAML 字段，除非技能被显式调用，否则这些额外信息不会影响 Agent 的行为。这种设计有效控制了上下文膨胀，同时保持了技能描述的简洁性。官方文档特别强调，Codex 会忽略额外的 YAML 键，只有 name 和 description 会在运行时被注入到上下文，除非技能被显式调用。
目录结构的规范化约束
Skills Catalog 为技能包定义了严格的目录结构规范，这种约束确保了不同来源的技能能够以一致的方式被 Codex 解析和加载。根目录必须包含 SKILL.md 文件作为技能的入口描述点。在此基础上，技能可以包含多个可选子目录，每个子目录承担特定的功能职责。这种标准化的目录布局是实现技能可发现性和可复用性的基础设施。
scripts 目录用于存放可执行的脚本文件，支持 Python、Shell、JavaScript 等多种语言。根据 GitHub 仓库的语言统计，Python 占 90.1%、Shell 占 5.0%、JavaScript 占 1.9%，这表明 Python 是技能开发的主导语言。这些脚本通常用于实现确定性的辅助功能，如代码格式化、数据转换等与主流程逻辑相对独立的任务。references 目录用于放置文档、示例代码等参考资料，这些资源可在 SKILL.md 中被引用，帮助 Agent 理解技能的使用场景和最佳实践。
assets 目录用于存放模板、Schema 定义等静态资源文件，这些文件通常在脚本执行过程中被动态加载和使用。agents 目录是一个特殊的可选组件，它通过 openai.yaml 文件定义技能与 OpenAI 其他产品（如 Agent SDK）的集成配置。这种设计使得同一个技能包可以同时服务于 Codex 和其他 OpenAI 产品生态，实现了跨平台的能力复用。每个技能包还可以包含独立的 LICENSE.txt 文件，声明该技能的具体使用许可协议，这种做法为社区贡献的技能提供了清晰的版权保护机制。
技能分类与分发策略
Skills Catalog 采用了三级分类体系来管理不同成熟度和来源的技能，这种分类直接影响着技能的安装方式和分发渠道。.system 目录下的技能被视为系统级能力，会随着 Codex 的安装自动部署，用户无需任何手动操作即可使用。这类技能通常经过严格的审核流程，代表了 OpenAI 官方推荐的核心功能集。
.curated 目录包含经过社区贡献、OpenAI 审核的精选技能。这些技能可以通过 Codex 内置的 $skill-installer 命令进行安装。安装时只需指定技能名称，系统会自动从 skills/.curated 目录中定位并部署对应的技能包。官方文档给出的安装示例为 $skill-installer gh-address-comments，这种简洁的命令形式降低了用户的使用门槛。curated 技能的许可证信息可以在技能目录内的 LICENSE.txt 文件中找到。
.experimental 目录则用于存放实验性或新提交的技能，这些技能可能尚未经过完整的质量审核流程。安装这类技能需要指定完整的目录路径或 GitHub URL，例如 $skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan。这种设计既保证了核心技能库的稳定性，又为社区创新提供了试验田。GitHub 仓库目前已有 62 次提交和 16 位贡献者，展现出活跃的维护状态。
运行时加载机制与路径解析
Codex 的技能加载系统采用了多路径搜索策略，以支持不同来源和安装方式的技能。从技术实现角度来看，运行时主要从三个位置检索可用技能：项目级别的 .agents/skills/ 目录、用户级别的～/.codex/skills/ 目录，以及系统级别的 skills 目录（对应 GitHub 仓库中的 .system 目录）。这种多层次的路径设计满足了不同场景下的技能管理需求。
当用户安装新技能后，需要重启 Codex 以便系统重新扫描并加载新增的技能包。这一重启机制确保了技能索引的更新被正确反映到运行时的可用技能列表中。从性能角度考虑，技能扫描过程应当在启动阶段完成，而非在每次技能调用时实时遍历文件系统。OpenAI 官方文档建议在安装技能后重启 Codex 以应用新的技能。
技能的调用机制支持显式和隐式两种模式。显式调用通过 $skill-name 语法直接引用特定技能，这种方式适用于用户明确知道所需技能名称的场景。隐式调用则依赖于 Codex 的智能匹配能力，系统会根据当前任务的描述内容，在可用技能库中进行语义检索，选取最相关的技能自动加载。根据 OpenAI 官方文档，技能的调用方式包括通过 $skill-name 直接调用，或者通过描述隐式匹配触发。这种双模式设计既满足了精确控制的需求，又提供了灵活便捷的默认行为。
工程实践中的关键参数
在构建和使用技能包时，开发者需要关注几个关键的工程参数。技能名称的 100 字符限制要求开发者在保持描述性的同时兼顾简洁性，过长的名称不仅影响可读性，也可能在匹配过程中产生意外的分词结果。描述字段的 500 字符限制则鼓励开发者提供精炼的功能概述，这个限制对于语义检索的准确性至关重要。
从资源组织角度来看，建议将脚本文件与说明文档分离，脚本专注于确定性的计算任务，说明文档则提供充分的使用指导和示例。assets 目录中的模板文件应当设计为可参数化的形式，以便在不同的调用上下文中复用。references 目录中的文档应当保持与 SKILL.md 内容的一致性，避免出现描述与实现脱节的情况。
对于需要跨平台使用的技能，应当充分利用 agents 目录的配置能力，确保技能在不同 OpenAI 产品中的一致行为。同时，开发者应当在 LICENSE.txt 中明确声明许可协议，这对于社区分发和商业应用都具有重要的法律意义。OpenAI 官方提供的创建技能文档（https://developers.openai.com/codex/skills/create-skill/）详细说明了这些参数和约束条件。
Skills Catalog 的设计体现了可复用、可发现、可扩展的工程原则。通过标准化的 Schema 定义和严格的目录结构约束，它为 AI Agent 的能力建设提供了一个清晰而灵活的框架。无论是使用现有技能还是开发新的技能包，理解这些底层设计原理都将有助于更好地发挥 Codex 的能力潜力。
资料来源：
- OpenAI Skills Catalog GitHub 仓库：https://github.com/openai/skills
- OpenAI 技能创建文档：https://developers.openai.com/codex/skills/create-skill/