在 Agent 生态里，"技能"（skill）正在成为与提示词、MCP（Model Context Protocol）工具同级的基础设施：一个装着说明书、脚本和资源的文件夹，让编码代理在特定任务上稳定发挥。OpenAI 官方维护的 openai/skills 仓库 是这条路线上最受关注的样本，约 27.9k stars 的热度足以说明需求之真实。但翻开仓库首页，最醒目的公告却是"该仓库已弃用"，官方建议迁移到 openai/plugins 插件体系。一座藏书刚满的图书馆为什么宣布搬迁？本文先把仓库的结构与用法讲清楚，再顺着弃用公告分析从技能目录到插件体系的演进逻辑。
1、仓库概况
openai/skills 的自我定位是 "Skills Catalog for Codex"，即 OpenAI 编码代理 Codex 的官方技能目录，由 OpenAI 直接维护。规模上，它有约 27.9k stars、1.9k forks 和 114 次提交——对一个只有百余次提交的仓库来说，这个 star 密度相当罕见，侧面说明"技能"这个概念踩中了 Agent 开发者的真实痛点。
README 对技能的定义原文如下：
Agent Skills are folders of instructions, scripts, and resources that AI agents can discover and use to perform at specific tasks. Write once, use everywhere.
翻译过来：技能是由指令、脚本和资源组成的文件夹，AI 代理能够自动发现并在特定任务中使用它们——写一次，处处可用。仓库里每个技能是一个独立目录，各自携带 LICENSE.txt，授权粒度细到单个技能，二次利用前看清许可即可。
必须先交代仓库的当前状态：头部公告已明示弃用，去向是 openai/plugins 仓库与配套的插件构建指南。这不是烂尾，而是一次路线升级，第 6、7 节展开。
2、技能的运行机制
一个技能目录的标配是一份 SKILL.md 说明书，加上可选的脚本与资源文件。SKILL.md 用 Markdown 写清楚这个技能做什么、什么时候启用、具体步骤是什么；脚本则承载说明书讲不清的确定逻辑，比如调用外部服务、执行构建。
与往系统提示词里塞说明的传统做法相比，技能的加载方式不同：文件躺在磁盘上，代理接到任务后再按需发现和读取。这带来两个直接好处——不相关任务不占上下文窗口；技能内容可以比一条 prompt 长得多，装得下完整的工作流。
"Write once, use everywhere" 也不是空话。SKILL.md 背后有 Agent Skills 开放标准兜底，实现了该标准的代理读的是同一份技能文件。想自己动手的话，官方另有创建自定义技能的专门指南。
3、三层目录结构
仓库的 skills 目录按稳定度分三层，对应三种安装策略：
| 目录 | 定位 | 安装方式 |
|---|---|---|
skills/.system |
系统技能 | 随最新版 Codex 自动安装 |
skills/.curated |
精选技能 | 按名称安装 |
skills/.experimental |
实验技能 | 指定文件夹或 GitHub 目录 URL |
目录结构如下：
skills/
├── .system/ # 系统层：Codex 自动安装
├── .curated/ # 精选层：按名安装，39 个技能
└── .experimental/ # 实验层：按目录或 URL 安装
三层的设计意图很清晰：.system 是 Codex 开箱即得的基础能力，用户无感知；.curated 是官方背书的稳定技能，覆盖主流场景；.experimental 是孵化器，验证成熟后再晋升。对使用者来说，精选层默认可信，实验层自行评估。
4、代表性技能一览
.curated 目录现有 39 个技能，按用途大致分成几类：
| 类别 | 代表技能 | 说明 |
|---|---|---|
| 设计转代码 | figma 系列 8 个 |
设计稿对接、组件库生成 |
| 部署 | netlify-deploy 等 4 个 |
部署到 Netlify、Vercel 等平台 |
| GitHub 流程 | gh-address-comments、gh-fix-ci |
处理 PR 评论、修 CI 失败 |
| 安全审计 | security-* 系列 3 个 |
威胁建模、最佳实践审查 |
| 协作工具 | notion-* 系列 4 个、linear |
知识沉淀与需求流转 |
| 多媒体 | pdf、speech、transcribe |
文档、语音、转写处理 |
| 测试 | playwright 系列 2 个 |
浏览器自动化 |
几个细节值得注意。figma 一个产品衍生出 8 个细分技能，从设计系统规则到组件 code connect 都单独立项，说明官方在用"小而专"的粒度拆技能，而不是做一个大而全的万能助手。部署类技能把"提交之后"的最后一公里也纳入代理职责，四家主流平台齐平。安全类把威胁建模这种高门槛动作标准化，是目录里含金量最高的一档。另外还有 migrate-to-codex，帮用户从其他编码代理迁到 Codex——官方亲自做这个技能，用意不言自明。
5、安装与使用
安装动作统一由 Codex 内置的 $skill-installer 完成，三种姿势对应三层目录：
# 精选技能：按名安装
$skill-installer gh-address-comments
# 实验技能：指明来源文件夹
$skill-installer install the create-plan skill from the .experimental folder
# 实验技能：直接给 GitHub 目录 URL
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan
按名安装是精选层的特权，实验技能必须把来源说清楚。安装完成后有一条硬性要求：重启 Codex 才能加载新技能，README 原话是 "restart Codex to pick up new skills"。装了没生效，先怀疑没重启。更多日常用法可以查官方技能文档。
6、弃用公告与迁移去向
仓库首页的弃用公告原文如下：
This repository is deprecated. For current Codex skill and plugin examples, use the OpenAI Plugins repository.
去向已经明确：openai/plugins 仓库，目前约 7.3k stars、947 forks，定位是 "a curated collection of Codex plugin examples"。插件的组织方式与技能不同，一个最小插件的目录结构如下：
my-plugin/
├── .codex-plugin/
│ └── plugin.json # 插件清单，必备
├── skills/ # 技能目录，可选
├── .mcp.json # MCP 工具配置，可选
├── agents/ # 子代理定义，可选
├── commands/ # 自定义命令，可选
└── hooks.json # 钩子，可选
结构说明了一切：插件以 .codex-plugin/plugin.json 清单为入口，把技能、MCP 工具配置、子代理、命令、钩子（还有 .app.json、assets/ 等扩展位）打包成一个可整体安装的单元。仓库里的示例已经相当丰富——Figma、Notion、Expo、Netlify、Remotion、Google Slides、build-iOS 等都在列，市场配置放在 .agents/plugins/marketplace.json。构建细节看插件构建指南。
7、从技能到插件的演进
把两个仓库放在一起看，演进逻辑并不难理解。
技能解决的是知识注入问题：把领域经验写成文件，代理按需读取。它的优势是简单、开放、可移植——一份 SKILL.md 放在任何支持标准的代理旁边都能用。但一个真实的开发工作流需要的不止知识：要调工具、要派子代理、要注册命令和钩子，这些东西在纯技能目录里没有位置。
插件正是为此而生的打包层：它不推翻技能格式，而是把技能降维成自己的一种组件。官方指南专门保留了 "skill-only plugin" 的写法——只装技能、不带其他的极简插件——等于明说：作废的不是技能格式，而是"单一技能目录"这种分发形态。
对开发者来说，这个分层其实是个不错的结局：内容层跟着开放标准走，保持可移植；分发层跟着 Codex 的插件体系和市场走，拿到安装、更新、发现的完整链路。两头都不必绑死。
8、总结
openai/skills 用 39 个精选技能证明了"文件夹即能力"这个方向的吸引力，又用一纸弃用公告把它并入了 openai/plugins 的插件体系。技能没有死，它从主角变成了插件里的一个目录；SKILL.md 格式仍由开放标准承载，写一次处处可用的承诺依然成立。
对于已经装了这个仓库技能的用户，现有技能可以继续用，不必急着迁移；对于要写新技能的开发者，建议内容按 SKILL.md 标准写、分发按插件打包，顺着 Build plugins 指南走官方链路；对于观察 Agent 生态的人，这是"格式开放、分发收拢"的经典剧本，值得记下这一笔。
