#Agent Skills

Skills 把可重复工作流封装为 Agent 可发现、可执行的模块。Codex 的 Skills 基于 开放 Agent Skills 标准，同一份 SKILL.md 可在 Claude Code、Cursor、Gemini CLI 等工具间迁移。

#Skill 是什么？

一个 Skill 通常是一个目录：

my-skill/
├── SKILL.md          # 必需：元数据 + 指令正文
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：补充文档
└── agents/
    └── openai.yaml   # 可选：Codex App 展示与 MCP 依赖声明

#SKILL.md 最小示例

---
name: commit
description: 按语义分组暂存并提交。用户提到 commit、整理提交、推送前清理分支时使用。
---

1. 禁止 `git add .`；按 logical group 分批 stage。
2. 顺序建议：feat → test → docs → refactor → chore。
3. 每个 commit 信息简洁，范围与 diff 一致。
4. 提交前确认 `git status` 无意外文件。

#存放位置

#触发方式

#1. 显式调用

在 TUI 中：

$commit

或：

/skills

#2. 隐式调用

当用户任务与 description 语义匹配时，Codex 自动选用该 Skill。
写好 description 是关键——用触发场景词，而非空泛标题。

#3. 禁止隐式（可选）

在 agents/openai.yaml 中：

policy:
  allow_implicit_invocation: false

此时仅 $skill-name 可触发，适合高风险流程。

#渐进式披露

Codex 不会一次性加载所有 Skill 全文：

1. 启动时只见 name + description（元数据）
2. 选中后才读 SKILL.md 正文
3. 需要时才读 references 或执行 scripts/

因此可以在 monorepo 中维护较多 Skills，而不爆上下文。

#内置与 curated Skills

Codex 提供 $skill-installer 安装官方 curated skills，例如：

$skill-installer gh-address-comments

常见内置/官方类 Skill（以当前版本为准）：

• skill-creator — 交互式创建新 Skill
• plugin-creator — 打包 Plugin
• openai-docs — 检索 OpenAI 文档

#Plugin：Skills 的分发单元

Skill = 作者格式；Plugin = 可安装包，可包含：

• 多个 Skills
• MCP 服务器配置
• App UI 元数据

团队内推广流程时，优先 Plugin；个人调试时用目录级 Skill。

#与 MCP 组合

当 Skill 需要访问 GitHub、Linear、浏览器等：

1. 在 Skill 步骤中写明调用哪些 MCP 工具
2. 在 agents/openai.yaml 声明 dependencies.tools（type: mcp）
3. 启用 features.skill_mcp_dependency_install（默认开启）时，Codex 可提示安装缺失 MCP

示例依赖片段：

dependencies:
  tools:
    - type: mcp
      value: openaiDeveloperDocs
      description: OpenAI Docs MCP server
      transport: streamable_http
      url: https://developers.openai.com/mcp

#编写高质量 Skill 的原则

1. 单一职责：一个 Skill 解决一类任务（release、review、migrate）
2. 可验证步骤：每步有明确完成标准（「测试通过」「diff 仅含 .ts」）
3. 约束优先：先写禁止项（不要 force push、不要改 lockfile）
4. 脚本兜底：复杂校验放 scripts/validate.sh，减少模型自由发挥

#从 Claude Code 迁移

Skills 规范与 Claude Code 高度兼容，通常可直接复制 .agents/skills 或 skills/ 目录到 Codex，无需改 MCP 的 JSON→TOML 那种级别迁移（Skills 本身无此问题）。

#下一步

• MCP 集成：为 Skill 接外部系统
• 实战案例：用 Skill 固化发布流程