Codex Skills | 建立、組織與複用工作流程 | 擴充與自動化

使用智能體技能可以給 Codex 注入任務級能力。一個技能會把指令、參考資料和可選指令碼打包在一起，讓 Codex 可以更穩定地遵循某個工作流程。Codex 的技能建立在開放智能體技能標準之上。

技能是可複用工作流程的創作格式。外掛則用於把可複用技能與連接器分發到網頁版 ChatGPT Work，以及桌面 App 中的 ChatGPT Work 與 Codex；Codex CLI 也可以安裝外掛。如果你想設計工作流程本身，請從技能開始；當你希望讓工作區中的其他人安裝時，再把它打包成外掛。

ChatGPT 桌面 App、Codex CLI 和 IDE 擴充套件都支援技能。

在 ChatGPT 桌面 App 中，開啟側邊欄裡的 Skills（技能），即可檢視和探索各個專案中建立的技能。

Codex 使用“按需展開”來管理上下文：啟動時只讀取每個技能的 name、description 和檔案路徑；只有在 Codex 決定實際使用這個技能時，才會把完整 SKILL.md 指令載入進上下文。

Codex 會在上下文裡放入一份初始技能列表，以便為任務選擇合適的技能。為了避免擠佔提示詞的其它部分，這份列表最多使用模型上下文視窗的 2%；如果上下文視窗未知，則上限為 8,000 個字元。如果安裝了很多技能，Codex 會先縮短技能描述。對於較大的技能集合，Codex 可能會從初始列表中省略部分技能並顯示警告。

這個預算只適用於初始技能列表。Codex 選中某個技能後，仍會讀取該技能完整的 SKILL.md 指令。

一個技能就是一個目錄，裡面至少要有 SKILL.md，還可以按需新增指令碼和參考資料。SKILL.md 必須宣告 name 和 description。

my-skill/
├── SKILL.md          # 必需：指令与元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：文档参考
├── assets/           # 可选：模板与资源
└── agents/
    └── openai.yaml   # 可选：展示信息与依赖声明

Codex 如何使用技能

Codex 有兩種觸發技能的方式：

顯式呼叫：例如在 CLI / 應用中使用 /skills 選擇，或者在提示詞中寫 $skill-name
隱式呼叫：Codex 根據 description 判斷是否適合使用某個技能

因為隱式匹配依賴 description，所以技能描述要簡潔，並寫清楚觸發範圍和邊界。把關鍵用例和觸發詞放在前面，這樣即使描述被縮短，Codex 仍能匹配到合適的技能。

建立技能

如果你已經清楚工作流程，而且“演示”比“描述”更容易，可以使用 Record & Replay。Codex 會錄製工作流程、檢查步驟，並根據演示起草可複用技能。

如果你想用文字描述技能，請使用內建建立器：

$skill-creator

建立器會詢問這個技能做什麼、在什麼場景下觸發，以及它是“純指令”還是“帶指令碼”型。預設推薦先做純指令技能。

你也可以手動建立，只要建立一個目錄並放入 SKILL.md：

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Codex 會自動檢測技能變更；如果更新後沒有生效，重啟 Codex 即可。

技能的儲存位置

Codex 會從儲存庫、使用者、管理員和系統四類位置讀取技能。對於儲存庫級技能，Codex 會從當前工作目錄開始，一路向上掃描到儲存庫根目錄中的 .agents/skills。如果兩個技能使用了同一個 name，Codex 不會合並它們，它們會分別出現在可選技能列表中。

技能範圍	位置	推薦用途
REPO	`$CWD/.agents/skills`	當前工作目錄對應的小範圍技能，例如某個微服務或模組專屬技能。
REPO	`$CWD/../.agents/skills`	當你在 Git 儲存庫的子目錄中啟動 Codex 時，可讓父目錄中的共享技能自動生效。
REPO	`$REPO_ROOT/.agents/skills`	儲存庫級共享技能，適合面向整個儲存庫的團隊規範或工作流程。
USER	`$HOME/.agents/skills`	使用者自己的全域技能，適用於任意儲存庫。
ADMIN	`/etc/codex/skills`	機器或容器級共享技能，常用於預設運維指令碼、SDK 自動化或管理員統一下發的技能。
SYSTEM	OpenAI 隨 Codex 內建	面向廣泛使用者的通用技能，例如 `skill-creator` 和規劃相關技能。

Codex 支援通過符號連結組織技能目錄；掃描時會跟隨連結目標繼續讀取。

這些路徑主要用於本機創作和本機發現。如果你要把技能作為可複用產物分發到儲存庫之外，或者希望和連接器一起打包，應該使用外掛。

用外掛分發技能

直接在 skills/ 目錄下維護技能，最適合本機開發和儲存庫範圍工作流程。

如果你希望：

分發一個可複用技能
把多個技能組合在一起釋出
把技能和連接器一起交付

那麼更適合把它們打包成外掛。

外掛可以包含一個或多個技能，也可以同時攜帶應用對映、MCP server 設定和展示資源。

在本機安裝精選技能

如果你想在本機 Codex 環境中安裝內建之外的精選技能，可以使用 $skill-installer。例如安裝 $linear 技能：

$skill-installer linear

你也可以讓安裝器從其他儲存庫下載技能。Codex 會自動發現新安裝的技能；如果沒有立即出現，可以重啟 Codex。

這個流程更適合本機試驗和個人使用。對於你自己希望複用和分發的技能，優先考慮外掛。

啟用或停用技能

你可以通過 ~/.codex/config.toml 中的 [[skills.config]] 條目，在不刪除技能的前提下將其停用：

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

修改 ~/.codex/config.toml 後，需要重啟 Codex。

可選後設資料

如果你希望在 ChatGPT 桌面 App 中設定介面後設資料、設定呼叫策略，並宣告工具依賴，以獲得更順暢的技能使用體驗，可以在技能目錄中加入 agents/openai.yaml：

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

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

其中 allow_implicit_invocation 預設為 true。如果把它設為 false，Codex 就不會根據使用者提示詞自動隱式觸發這個技能，但顯式使用 $skill-name 仍然有效。

最佳實踐

讓每個技能聚焦在一項明確工作上。
除非你確實需要確定性行為或外部工具，否則優先使用指令而不是指令碼。
步驟儘量寫成祈使句，並明確輸入與輸出。
用真實提示詞去測試 description，確認它會在正確場景觸發，也會在不該觸發時保持沉默。

更多範例可參考 GitHub CI 修復、PDF、Linear、openai/skills 和智能體技能規範。需要以可安裝形式分發時，優先使用 plugins。

來源：</zh-TW/docs/build-skills> 更新時間：2026-07-15（UTC）

最近搜尋

建議搜尋

文件導覽

建置技能