OpenAI Agent Skills 架构速览
一句话定位
openai/skills 是一个开源的 AI 代理技能标准与目录。它定义了一套规范，允许 AI 代理（如 OpenAI Codex）通过识别特定格式的文件夹（包含指令、脚本和资源）来扩展其实操能力，实现“写一次，随处使用（Write once, use everywhere）”。
技术栈
- 核心规范：Markdown (SKILL.md) 与 YAML Frontmatter
- 逻辑实现：Python / Shell / Node.js（取决于具体技能的脚本）
- 分发方式：GitHub 仓库 / 目录同步
- 运行环境：AI 代理宿主环境（如 Codex）
目录结构
.
├── skills/
│ ├── .system/ # 系统核心技能（如 skill-installer, skill-creator）
│ │ └── skill-installer/
│ │ ├── SKILL.md # 技能的核心接口与逻辑定义
│ │ ├── scripts/ # 辅助 Python 脚本
│ │ └── agents/ # 特定代理（如 OpenAI）的配置
│ └── .curated/ # 官方精选的实用技能目录（共 40+ 个）
│ ├── frontend-skill/# 前端开发增强
│ ├── figma/ # Figma 插件交互
│ └── ...
├── README.md # 项目入门指南
└── contributing.md # 贡献规范入口点
- SKILL.md：每个技能的“心脏”。它通过 Frontmatter 定义技能名称和描述，正文部分则是给 AI 代理的高层指令。代理通过解析此文件来理解何时以及如何调用该技能。
- .system/skill-installer：项目的引导程序，负责将远程 GitHub 仓库中的其他技能安装到本地
$CODEX_HOME/skills目录。
核心数据流
用户：帮我安装 gh-fix-ci 技能
→ 代理读取 .system/skill-installer/SKILL.md
→ 执行 scripts/install-skill-from-github.py
→ [远程] 下载 openai/skills/skills/.curated/gh-fix-ci 文件夹
→ [本地] 写入 ~/.codex/skills/gh-fix-ci
→ 代理重启/刷新技能目录
→ 代理通过 gh-fix-ci/SKILL.md 识别新能力整体架构
项目采用了一种 声明式扩展 的分层设计：
- 指令层 (Instruction Layer)：由
SKILL.md承载，告诉代理该做什么以及如何与用户交流。 - 工具层 (Tooling Layer)：位于
scripts/目录，通过 Python 等脚本执行高风险或复杂操作（如 API 调用、文件操作）。 - 适配层 (Adapter Layer)：位于
agents/目录，确保同一套技能可以适配不同的 AI 模型或宿主环境。
核心抽象
Skill：一个独立的文件夹单元。SKILL.md：定义接口与策略。scripts/：封装复杂行为，保持SKILL.md简洁。
skill-installer：管理技能生命周期的核心系统技能，支持从公共/私有 GitHub 仓库安装。skill-creator：辅助 AI 代理自我进化，通过模板生成新的技能文件夹。
关键文件速查
| 想了解什么 | 去哪里找 |
|---|---|
| 技能是如何定义的？ | skills/.system/skill-installer/SKILL.md（参考标准实现） |
| 有哪些可用的现成技能？ | skills/.curated/ 目录 |
| 技能如何与特定代理适配？ | 每个技能下的 agents/ 目录 |
| 如何安装新技能？ | skills/.system/skill-installer/scripts/ 下的安装脚本 |
核心依赖
| 库 | 用途 |
|---|---|
python3 | 编写跨平台的自动化脚本。 |
github-api | 用于列表展示和直接从 GitHub 下载技能内容。 |
值得关注的设计决策
- “写一次，随处使用”：通过将逻辑（脚本）与指令（Markdown）分离，使得技能不仅能被 OpenAI 的产品使用，也能被任何遵循该标准的代理框架集成。
- 基于文件系统的“发现机制”：代理通过扫描本地目录即可热更新能力，无需复杂的插件注册中心。
- 安全隔离：脚本运行在沙盒中，对于需要联网或文件访问的操作，在
SKILL.md中明确要求代理请求用户授权（Escalation）。
报告由 Antigravity 自动生成。