---
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="/zh-Hant/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)
