---
title: "用 Skills 复用能力"
description: "理解 agent skills 如何把 instructions、resources 和 scripts 打包成可复用的 Codex 工作流。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Skill 是可复用工作流的编写格式。它把任务说明、资源和可选脚本放进一个目录，让 Codex 在匹配任务时按同一套方法执行。

> [!TIP]
> 如果你反复复制同一段 prompt，或反复纠正 Codex 的同一类错误，它大概率应该变成 skill。

<Cards>
  <Card title="Skills" href="https://developers.openai.com/codex/skills">
    查看 Codex skills 的官方说明。
  </Card>
  <Card title="Create skills" href="https://developers.openai.com/codex/skills#create-a-skill">
    学习如何创建 `SKILL.md` 和配套资源。
  </Card>
  <Card title="Plugins" href="/docs/codex/official/03-extensions/69-build-plugins">
    当 skill 需要分发给别人安装时，再打包成 plugin。
  </Card>
</Cards>

## Skill 解决什么

```mermaid
flowchart LR
    Repeat["重复 prompt / 重复纠错"] --> Skill["Skill"]
    Skill --> Stable["稳定流程"]
    Skill --> Trigger["清楚触发"]
    Skill --> Verify["固定验证"]
```

适合：

- 文档美化。
- PR review。
- release note。
- 日志分诊。
- migration planning。
- 安全检查清单。
- 固定格式输出。

不适合：

- 一次性任务。
- 还没跑稳的流程。
- 需要大量临场判断的开放问题。
- 只是存放一堆资料的目录。

## 基本结构

```text
my-skill/
  SKILL.md
  scripts/
  references/
  assets/
```

`SKILL.md` 至少要说明：

- skill 名称。
- description：什么时候触发，什么时候不触发。
- 输入。
- 步骤。
- 输出。
- 验证方式。
- 风险边界。

脚本、模板和参考资料只在能提升可靠性时加入。不要为了显得复杂而加文件。

## Codex 如何选择 skill

Codex 通常先看到 skill 的 name、description 和路径。只有判断任务需要时，才加载完整 `SKILL.md`。

所以 description 必须准确：

- 开头写核心任务。
- 写出用户真实会说的触发词。
- 写清不适用场景。
- 避免泛泛写“提高效率”。

描述越泛，误触发越多。

## 创建流程

推荐顺序：

1. 先用普通 prompt 跑通一次。
2. 重复多次，记录稳定步骤和失败点。
3. 用 `$skill-creator` 或手动创建 skill。
4. 用真实任务测试触发。
5. 修改 description 和验证步骤。
6. 需要团队分发时，再做 plugin。

Skill 是流程沉淀，不是流程想象。先实践，再封装。

## 保存位置和分发

官方 skills 支持 CLI、IDE extension 和 Codex app。保存位置决定谁能看到它：

| 范围 | 位置 | 用途 |
| --- | --- | --- |
| Repo 当前目录 | `$CWD/.agents/skills` | 只服务当前工作目录。 |
| Repo 父目录 | `$CWD/../.agents/skills` | 子模块共享同一组技能。 |
| Repo 根目录 | `$REPO_ROOT/.agents/skills` | 仓库级团队工作流。 |
| User | `$HOME/.agents/skills` | 个人所有项目可用。 |
| Admin | `/etc/codex/skills` | 受管理机器统一提供。 |
| System | Codex 内置 | OpenAI 打包的通用技能。 |

Codex 支持 symlinked skill folders。对于大体积技能库，可以用软链接复用一份主库，避免复制多份。

如果要跨 repo、跨团队分发，或把 skill 与 MCP、app integration 一起打包，使用 plugin。

## 显式调用和隐式调用

Codex 使用 skill 有两种方式：

- 显式调用：在 CLI/IDE 中用 `/skills` 或 `$skill-name` 指定。
- 隐式调用：Codex 根据任务与 `description` 的匹配自动选择。

隐式调用依赖 `description`，所以描述要把触发词前置。例如：

```markdown
---
name: release-note-writer
description: Use when turning merged PRs or git commits into concise release notes. Do not use for general blog writing.
---
```

这个 description 同时说明“用来写 release notes”和“不用于普通博客”。比“帮助写作”这类泛描述可靠得多。

## Progressive disclosure

Skills 的关键机制是 progressive disclosure：Codex 启动时只把 skill name、description 和路径放进上下文；真正需要时才读取完整 `SKILL.md`。

这意味着：

- `SKILL.md` 可以放详细步骤，但 description 必须短而准。
- 长参考资料不要塞进 description，放到 `references/`。
- 大量 skills 会占初始上下文预算，描述会被压缩或省略，所以最重要的触发词要写在开头。
- 如果某个技能必须避免误触发，可以在 `agents/openai.yaml` 中关闭 implicit invocation，只允许显式调用。

## 质量检查

一个 skill 合格，应满足：

- 能被正确触发。
- 不会在错误任务中误触发。
- 步骤足够短而明确。
- 输出格式稳定。
- 验证方式可执行。
- 不包含密钥或私有路径。
- 修改后能在干净任务中复验。

Skill 的目标是让 Codex 少问重复问题、少犯重复错误、按稳定标准交付。

## 官方资料

- [Agent Skills](https://developers.openai.com/codex/skills)
- [Build plugins](https://developers.openai.com/codex/plugins/build)
- [Agent Skills specification](https://agentskills.io/specification)
