技能創作者
建立能為 Codex 提供有用、非顯而易見的指導，同時不約束無關工作的技能。
核心原則
假設 Codex 已有足夠能力。 僅包含會改變其決策或改善其工作的資訊。移除一般性建議、重複指示、推測性邊緣案例，以及無法實際釐清任務的範例。
保留使用者意圖與範圍。 技能應支援被請求的任務，而非取代使用者選擇的產品、擴大任務範圍、修改無關設定，或暗示允許進行額外的外部操作。不要將特定範例、過去的失敗或個人偏好轉變為通用需求。
完成任務的授權並不會擴大其範圍或執行權限。對於重試或外部變更工作流程，應根據風險定義一個相應的停止條件。
將具體性與風險匹配。 當多種方法都合理時，給模型選擇適當方法的空間。僅在正確性、安全性、權限或真正脆弱的工作流程需要時，才使用詳細步驟、確定性腳本或絕對性語言。
對於開放式工作，描述預期結果和相關決策標準。對於有偏好形狀的工作流程，提供有用的範例或可配置腳本。將固定序列和狹窄參數保留給那些偏離會造成具體問題的操作。保留非顯而易見的操作不變量，區分實際需求與可選建議或本地慣例，並避免重述已在其他地方強制的政策。
保持發現成本低廉且精確。 技能名稱和描述在技能載入前即可取得。描述實際能力及其適用時機，僅在可能導致錯誤路由時加入排除條件。避免詳盡的能力清單和會吸引無關請求的包羅萬象清單。
保持技能自包含；僅在請求的工作流程確實需要，且目標環境中可用時，才引用另一個技能或工具。專門的審查、強化或稽核工作流程應僅在請求或真正需要時應用，而非僅僅因為一般工作觸及相同主題。
漸進式揭露細節。 將共同目的、基本約束和有用的路由資訊放在 SKILL.md 中。將大量模式特定的指導、架構、範例或程序放在支援參考文件中，並僅讀取與目前任務相關的參考文件。一個簡單的自包含技能不需要路由器或額外檔案。
技能的結構
每個技能是一個包含必備 SKILL.md 檔案以及其實際工作流程所需的任何可選資源的資料夾：
skill-name/
|-- SKILL.md 必備技能指示
| |-- YAML 前言 必備名稱和描述
| `-- Markdown 內文 使用技能時載入的指示
|-- agents/ 可選的 UI 中繼資料和呼叫政策
| `-- openai.yaml
|-- scripts/ 可選的可執行輔助程式
|-- references/ 可選的按需載入文件
`-- assets/ 可選的用於產生輸出中的檔案
選擇符合實際任務的結構。有些技能簡短且自包含；有些則在不同操作模式間路由或將複雜機制委派給腳本。避免在沒有明確用途的情況下建立目錄、佔位符、範例或輔助文件。
SKILL.md
YAML 前言用於識別技能並決定何時應考慮使用它。包含必備的 name 和 description，並在適當時保留支援的可選欄位，例如現有的 metadata。
Markdown 內文僅在使用技能時載入。將目的、基本工作流程、真實約束和有用的連結放在那裡。當詳細程序和範例僅與特定模式相關時，將它們放在支援參考文件中。
技能資訊分三個階段揭露：
- 名稱和描述： 在技能選擇期間可用，因此保持簡潔且具區辨力。
- SKILL.md 內文： 當技能適用時載入，因此保持其指示與該任務相關。
- 支援資源： 僅在當前任務確實需要時才讀取或執行。
進入點應盡可能簡短，同時保留重要約束。一個大的上限不是目標：當這樣做能改善清晰度或上下文使用時，將條件性細節移到參考文件中，而不是等到檔案變得難以處理。
腳本
當相同邏輯會重複重寫，或確定性執行能顯著改善可靠性時，使用 scripts/ 存放可執行程式碼。
- 範例：
scripts/rotate_pdf.py用於一個否則需要重新建立相同程式碼的 PDF 操作。 - 適用於： 重複轉換、可靠的 API 操作、資料處理和其他具體自動化。
- 驗證： 執行新的或修改過的腳本以驗證其行為。腳本通常可以在不將其實作完整載入上下文的情況下執行，儘管代理在修補或改編它們時可能需要檢查。
參考文件
使用 references/ 存放僅在特定情境下需要的文件。
- 範例： 資料庫表格的
references/schema.md、領域規則的references/policies.md、API 的references/api_docs.md，或為不同交付物分別撰寫的寫作指南。 - 適用於： 架構、API 文件、公司政策、格式特定程序、詳細工作流程和大量範例。
- 路由： 從
SKILL.md或其他相關資源連結每個參考文件，並說明何時應讀取它。將資訊放在一個地方，而不是在進入點和參考文件之間重複。
保持參考文件專注於維護良好的、任務特定的資訊，這些資訊會改變代理的決策。避免複製的操作手冊、詳盡的目錄以及已可從權威來源取得的通用教學。在移除現有資源之前，檢查其呼叫者和目的。
對於大型參考文件，包含有用的搜尋詞或簡短的目錄章節，這有助於更容易找到需要的材料。
資產
使用 assets/ 存放屬於產生輸出中的檔案，而不是模型指示中的檔案。
- 範例：
assets/logo.png、assets/slides.pptx、assets/font.ttf或assets/frontend-template/。 - 適用於： 範本、圖片、字型、圖示、入門專案以及其他複製或改編到結果中的檔案。
- 上下文： 不要將資產作為指示載入，除非任務需要檢查它們。
UI 中繼資料和呼叫政策
agents/openai.yaml 可以提供 UI 面向的中繼資料，例如 display_name、short_description 和 default_prompt，以及呼叫政策。在建立或更新這些設定時，請閱讀 references/openai_yaml.md 並保持值與技能一致。
預設允許自動技能選擇。僅在使用者明確要求僅限明確呼叫的技能時才更改該預設值：
policy:
allow_implicit_invocation: false
這使得技能在作為 $skill-name 明確呼叫時可用，而不會自動將其新增到模型上下文中。在更新 agents/openai.yaml 時，保留無關的現有 UI、政策和依賴欄位。
初始化器會自動建立此檔案。對於新的或僅限介面的中繼資料，使用以下指令產生它：
scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
產生器會取代整個檔案。如果現有檔案包含 policy 或 dependencies，則直接在原地更新預期欄位，而不是重新產生。
僅在使用者提供或要求時才包含可選的介面欄位。
不應包含的內容
包含直接支援技能工作的檔案。避免新增 README.md、安裝指南、變更日誌、重複的快速參考或其他輔助文件，除非特定任務或打包需求要求這麼做。
實務中的漸進式揭露
對於具有多個重要模式的技能，將共享指導和模式選擇標準放在 SKILL.md 中。在相關位置連結每個支援參考文件。不要預設載入所有參考文件、在進入點重複參考文件內容，或在沒有有意義的路由內容時新增路由層。
例如，部署技能可以將提供者選擇放在 SKILL.md 中，並分離提供者細節：
cloud-deploy/
|-- SKILL.md
`-- references/
|-- aws.md
|-- gcp.md
`-- azure.md
當使用者選擇 AWS 時，讀取 references/aws.md；不要同時載入 GCP 和 Azure 指南。同樣的模式可以分離業務領域、交付物類型或其他真正不同的操作模式。
一個簡短的技能可以改為僅在進階操作需要時才路由到細節：
## 文件
直接處理一般編輯。
- 對於追蹤修訂，請閱讀 [references/redlining.md](references/redlining.md)。
- 對於文件內部結構，請閱讀 [references/ooxml.md](references/ooxml.md)。
這些範例說明了選項，而非必需的結構。選擇使技能更易於使用而不載入無關材料的組織方式。
建立或更新技能
根據請求調整工作。建立一個複雜的新技能可能涉及理解實際使用案例、選擇支援資源、初始化檔案、編寫指示和驗證結果。對現有技能進行狹窄更新可能只需要重點編輯和驗證。
僅當缺失的資訊很重要且無法合理推斷時，才提出釐清問題。尊重使用者指定的位置；否則在 $CODEX_HOME/skills 或當 CODEX_HOME 未設定時在 ~/.codex/skills 中建立可被發現的技能。
除非使用者明確要求僅限明確呼叫的技能，否則保持自動技能選擇啟用。當預期的呼叫模式確實不明確且對請求的工作流程很重要時，詢問使用者是否希望正常的自動發現或僅限明確呼叫；否則保留預設值。不要從敏感操作或必要批准中推斷出僅限明確呼叫：保持技能可被發現，並在實際變更之前立即要求授權。除非使用者要求更改，否則保留現有技能的呼叫政策。
對於新的或大幅修改的技能，考慮它應該處理的實際請求，以及哪些可重複使用的資源會改善這些任務：
- 重複的 PDF 轉換可能需要一個
scripts/rotate_pdf.py輔助程式。 - 應用程式建置工作流程可能受益於一個
assets/frontend-template/起始點。 - 資料分析技能可能需要一個
references/schema.md指南，以避免重新發現表格關係。
僅在這些資源的具體效益證明其合理性時才建立它們。如果使用者已經清楚地說明了任務，則直接進行，無需請求額外範例。
命名
- 使用小寫字母、數字和連字號。
- 保持名稱在 64 個字元以下，並偏好簡短、以行動為導向的名稱。
- 當這樣做能改善發現性時，按工具或領域命名空間。
- 以技能名稱命名技能資料夾。
初始化新技能
對於新技能，當它有助於一致地建立所需檔案時，使用內建的初始化器：
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
例如：
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references
僅請求技能所需的資源目錄。僅在具體的佔位符有幫助時才使用 --examples，並在完成前替換或移除它們。不要再次初始化現有的技能。
初始化器會建立技能目錄、一個簡潔的 SKILL.md 起始檔案和 agents/openai.yaml。僅在請求時才建立資源目錄和範例檔案。在需要時將產生的 UI 值作為 --interface key=value 傳遞。
編寫指示
前言的 description 應簡潔說明技能的功能及其適用時機。當類似請求不應啟動該技能時，包含有意義的邊界。
例如：
description: 在格式化、追蹤修訂或註解需要文件特定處理時，建立或編輯 Word 文件。
將詳細的工作流程、工具選擇、範例和操作模式放在內文或相關參考文件中，而不是在描述中一一列出。在適當時保留支援的可選前言，例如現有的 metadata。
僅編寫另一個 Codex 實例為良好執行任務所需的指示。說明預期結果、非顯而易見的上下文、真實約束以及相關的參考文件或工具。保留使用者的明確選擇和現有授權邊界。當任務不需要時，避免規定固定的結構、流程或步驟數量。
驗證與迭代
使用以下指令驗證完成的技能：
scripts/quick_validate.py <path/to/skill-folder>
驗證器會檢查前言、命名和未完成的架構佔位符；它不會證明技能做出了良好的決策。同時檢查描述是否仍具區辨力、指示是否保留使用者意圖、參考文件是否可被發現，以及任何新增的腳本是否實際運作。
當需要測試時，驗證可觀察的行為或有意義的不變量。避免僅匹配產生的措辭、標題或正則表達式模式的測試。
根據實際使用或已證實的失敗來改進技能。偏好針對性修正，而不是為邊緣案例積累通用規則。