技能創作者指南 是做什麼的？
此技能提供建立有效技能的指導。
關於技能
技能是模組化、自包含的資料夾，透過提供專業知識、工作流程和工具來擴展 Codex 的能力。把它們想像成特定領域或任務的「入門指南」——它們將 Codex 從通用代理轉變為配備了任何模型都無法完全擁有的程序性知識的專業代理。
技能提供的內容
- 專業工作流程 - 針對特定領域的多步驟程序
- 工具整合 - 使用特定檔案格式或 API 的說明
- 領域專業知識 - 公司特定知識、架構、業務邏輯
- 捆綁資源 - 用於複雜和重複性任務的腳本、參考文件和資產
核心原則
簡潔是關鍵
上下文視窗是公共資源。技能與 Codex 所需的一切（系統提示詞、對話歷史、其他技能的中繼資料以及實際使用者請求）共享上下文視窗。
預設假設：Codex 已經非常聰明。 只加入 Codex 尚未擁有的上下文。質疑每一項資訊：「Codex 真的需要這個解釋嗎？」以及「這個段落值得它的 Token 成本嗎？」
簡潔的範例優於冗長的解釋。
設定適當的自由度
將特定性程度與任務的脆弱性和可變性相匹配：
高自由度（基於文字指令）：當多種方法都可行、決策取決於上下文或啟發式方法指導方法時使用。
中等自由度（偽代碼或帶參數的腳本）：當存在首選模式、允許一些變化或配置影響行為時使用。
低自由度（特定腳本，少數參數）：當操作脆弱且容易出錯、一致性至關重要或必須遵循特定順序時使用。
將 Codex 想像成探索一條路徑：一座有懸崖的狹窄橋樑需要特定的護欄（低自由度），而一片開闊的場地則允許許多路線（高自由度）。
保護驗證完整性
您可以在迭代過程中，使用子代理來驗證某個技能是否能在實際任務上運作，或者一個可疑的問題是否真實存在。當您希望在修改後對技能的行為、輸出或失敗模式進行獨立檢查時，這最為有用。僅在可以啟動新的子代理時才執行此操作。
使用子代理進行驗證時，將其視為一個評估表面。目標是了解該技能是否具有泛化能力，而不是另一個代理能否從洩漏的上下文中重建答案。
偏好使用原始工件，例如範例提示詞、輸出、差異對比、日誌或追蹤。提供執行驗證所需的最小任務局部上下文。避免傳遞預期答案、可疑錯誤、預期修復或您先前的結論，除非驗證明確要求這樣做。
技能的組成
每個技能包含一個強制性的 SKILL.md 檔案和可選的捆綁資源：
skill-name/
├── SKILL.md (必要)
│ ├── YAML 前置元數據 (必要)
│ │ ├── name: (必要)
│ │ └── description: (必要)
│ └── Markdown 說明 (必要)
├── agents/ (推薦)
│ └── openai.yaml - 用於技能列表和晶片的使用者介面元數據
└── 捆綁資源 (可選)
├── scripts/ - 可執行程式碼 (Python/Bash 等)
├── references/ - 旨在按需載入到上下文中的文件
└── assets/ - 輸出中使用的檔案 (範本、圖示、字型等)
SKILL.md (必要)
每個 SKILL.md 包含：
- 前置元數據 (YAML)：包含
name和description欄位。這些是 Codex 用於判斷何時使用該技能的唯一欄位，因此清楚且全面地描述技能是什麼以及何時應使用它非常重要。 - 主體 (Markdown)：使用該技能的說明和指導。僅在技能觸發後（如果有的話）才載入。
代理元數據 (推薦)
- 面向使用者的技能列表和晶片元數據
- 在生成值之前，先閱讀
references/openai_yaml.md並遵循其描述和限制 - 通過閱讀技能，建立面向人類的
display_name、short_description和default_prompt - 通過將值作為
--interface key=value傳遞給scripts/generate_openai_yaml.py或scripts/init_skill.py來確定性地生成 - 更新時：驗證
agents/openai.yaml是否仍與 SKILL.md 匹配；如果過時則重新生成 - 僅在明確提供的情況下，才包含其他可選的介面欄位（圖示、品牌顏色）
- 有關欄位定義和範例，請參閱
references/openai_yaml.md
捆綁資源 (可選)
腳本 (scripts/)
用於需要確定性可靠性或重複重寫的任務的可執行程式碼（Python/Bash 等）。
- 何時包含：當相同的程式碼被重複重寫或需要確定性可靠性時
- 範例：用於 PDF 旋轉任務的
scripts/rotate_pdf.py - 優點：節省 Token、確定性高、可在不載入到上下文中的情況下執行
- 注意：對於修補或環境特定的調整，Codex 可能仍需要讀取腳本
參考文件 (references/)
旨在按需載入到上下文中，以告知 Codex 的流程和思考的文件和參考資料。
- 何時包含：用於 Codex 在工作時應參考的文件
- 範例：
references/finance.md用於財務架構、references/mnda.md用於公司 NDA 範本、references/policies.md用於公司政策、references/api_docs.md用於 API 規格 - 使用案例：資料庫架構、API 文件、領域知識、公司政策、詳細工作流程指南
- 優點：保持 SKILL.md 精簡，僅在 Codex 認為需要時才載入
- 最佳實踐：如果檔案很大（>10k 字），請在 SKILL.md 中包含 grep 搜尋模式
- 避免重複：資訊應位於 SKILL.md 或參考文件中，而不是同時存在。除非資訊對技能至關重要，否則應將詳細資訊放在參考文件中——這使 SKILL.md 保持精簡，同時使資訊易於發現而不佔用上下文視窗。僅在 SKILL.md 中保留必要的程序性說明和工作流程指導；將詳細的參考資料、架構和範例移至參考文件中。
資產 (assets/)
不打算載入到上下文中，而是在 Codex 產生的輸出中使用的檔案。
- 何時包含：當技能需要在最終輸出中使用的檔案時
- 範例：
assets/logo.png用於品牌資產、assets/slides.pptx用於 PowerPoint 範本、assets/frontend-template/用於 HTML/React 樣板、assets/font.ttf用於排版 - 使用案例：範本、圖片、圖示、樣板程式碼、字型、會被複製或修改的範例文件
- 優點：將輸出資源與文件分離，使 Codex 能夠在不將其載入到上下文中的情況下使用檔案
技能中不應包含的內容
技能應僅包含直接支援其功能的必要檔案。請勿建立不相關的文件或輔助檔案，包括：
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 等等
技能應僅包含 AI 代理完成當前工作所需的資訊。它不應包含關於建立過程、設定和測試程序、面向使用者的文件等的輔助上下文。建立額外的文件只會增加混亂。
漸進式揭露設計原則
技能使用三級載入系統來有效管理上下文：
- 元數據（name + description） - 始終在上下文中（約 100 字）
- SKILL.md 主體 - 技能觸發時載入（<5k 字）
- 捆綁資源 - 按 Codex 需要載入（無限制，因為腳本可以在不讀入上下文視窗的情況下執行）
漸進式揭露模式
將 SKILL.md 主體保持在必要內容，並少於 500 行，以最大限度地減少上下文膨脹。接近此限制時，將內容拆分到單獨的檔案中。將內容拆分到其他檔案時，務必在 SKILL.md 中引用它們，並清楚說明何時讀取它們，以確保技能的讀者知道它們的存在以及何時使用它們。
關鍵原則： 當技能支援多種變體、框架或選項時，僅在 SKILL.md 中保留核心工作流程和選擇指導。將變體特定的詳細資訊（模式、範例、配置）移至單獨的參考文件中。
模式 1：帶有參考文件的高階指南
# PDF 處理
## 快速入門
使用 pdfplumber 提取文字：
[程式碼範例]
## 進階功能
- **填寫表單**：完整指南請參閱 [FORMS.md](FORMS.md)
- **API 參考**：所有方法請參閱 [REFERENCE.md](REFERENCE.md)
- **範例**：常見模式請參閱 [EXAMPLES.md](EXAMPLES.md)
僅在需要時，Codex 才會載入 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
模式 2：領域特定的組織
對於具有多個領域的技能，按領域組織內容以避免載入不相關的上下文：
bigquery-skill/
├── SKILL.md (概覽和導覽)
└── reference/
├── finance.md (收入、計費指標)
├── sales.md (機會、管道)
├── product.md (API 使用、功能)
└── marketing.md (行銷活動、歸因)
當使用者詢問銷售指標時，Codex 僅讀取 sales.md。
類似地，對於支援多個框架或變體的技能，按變體組織：
cloud-deploy/
├── SKILL.md (工作流程 + 提供者選擇)
└── references/
├── aws.md (AWS 部署模式)
├── gcp.md (GCP 部署模式)
└── azure.md (Azure 部署模式)
當使用者選擇 AWS 時，Codex 僅讀取 aws.md。
模式 3：條件式詳細資訊
顯示基本內容，連結到進階內容：
# DOCX 處理
## 建立文件
對新文件使用 docx-js。請參閱 [DOCX-JS.md](DOCX-JS.md)。
## 編輯文件
對於簡單編輯，直接修改 XML。
**對於追蹤修訂**：請參閱 [REDLINING.md](REDLINING.md)
**對於 OOXML 詳細資訊**：請參閱 [OOXML.md](OOXML.md)
僅在使用者需要那些功能時，Codex 才會讀取 REDLINING.md 或 OOXML.md。
重要指南：
- 避免深度巢狀引用 - 保持從 SKILL.md 一層深度的引用。所有參考文件應直接從 SKILL.md 連結。
- 結構化較長的參考文件 - 對於超過 100 行的檔案，請在頂部包含目錄，以便 Codex 在預覽時能看到完整範圍。
技能建立流程
技能建立包含以下步驟：
- 使用具體範例理解技能
- 規劃可重複使用的技能內容（腳本、參考文件、資產）
- 初始化技能（執行 init_skill.py）
- 編輯技能（實作資源並撰寫 SKILL.md）
- 驗證技能（執行 quick_validate.py）
- 根據實際使用情況進行迭代，並對複雜技能進行前瞻性測試
依序遵循這些步驟，只有當有明確理由認為不相關時才跳過。
技能命名
- 僅使用小寫字母、數字和連字號；將使用者提供的標題標準化為連字號形式（例如，「Plan Mode」->
plan-mode）。 - 生成名稱時，產生一個少於 64 個字元的名稱（字母、數字、連字號）。
- 偏好簡短、以動詞開頭的短語來描述動作。
- 當能提高清晰度或觸發效果時，按工具命名空間（例如，
gh-address-comments、linear-address-issue）。 - 資料夾名稱必須與技能名稱完全相同。
步驟 1：使用具體範例理解技能
僅當技能的用法模式已經清楚理解時才跳過此步驟。即使在使用現有技能時，這仍然很有價值。
為了建立有效的技能，請清楚理解技能將如何被使用的具體範例。這種理解可以來自使用者提供的直接範例，或透過使用者回饋驗證過的生成範例。
例如，在建構影像編輯器技能時，相關問題包括：
- "影像編輯器技能應支援什麼功能？編輯、旋轉，還有其他的嗎？"
- "你能提供一些這個技能將如何被使用的例子嗎？"
- "我可以想像使用者會要求像『從這張圖片中移除紅眼』或『旋轉這張圖片』之類的事情。你還能想像這個技能有哪些其他使用方式嗎？"
- "使用者說什麼話應該觸發這個技能？"
- "我應該在哪裡建立這個技能？如果您沒有偏好的話，我會將其放在
$CODEX_HOME/skills（或當CODEX_HOME未設定時放在~/.codex/skills），這樣 Codex 就能自動發現它。"
為了避免讓使用者不知所措，請避免在一則訊息中問太多問題。從最重要的問題開始，並根據需要進行後續提問以提高效率。
當對技能應支援的功能有清晰的理解時，即可結束此步驟。
步驟 2：規劃可重複使用的技能內容
為了將具體範例轉化為有效的技能，請透過以下方式分析每個範例：
- 考慮如何從頭開始執行該範例
- 識別哪些腳本、參考文件和資產在重複執行這些工作流程時會有所幫助
範例：在建構一個用於處理「幫我旋轉這個 PDF」等查詢的 pdf-editor 技能時，分析顯示：
- 旋轉 PDF 需要每次重寫相同的程式碼
- 在技能中存放一個
scripts/rotate_pdf.py腳本會很有幫助
範例：在設計一個用於「幫我建立一個待辦事項應用程式」或「幫我建立一個儀表板來追蹤我的步數」等查詢的 frontend-webapp-builder 技能時，分析顯示：
- 編寫前端 Web 應用程式每次都需要相同的 HTML/React 樣板
- 在技能中存放一個包含樣板 HTML/React 專案檔案的
assets/hello-world/範本會很有幫助
範例：在建構一個用於處理「H
…
[因翻譯需求已截斷]