如何寫出好的 Skill？拆解 skill-creator 背後的設計
整理版優先睇
寫好AI Skill嘅核心：用最少token，喺正確層級畀最精準嘅約束，等AI喺邊界內自由發揮
呢篇文係關於點樣寫出好嘅AI Skill，基於Codex團隊嘅skill-creator工具嘅設計思路。作者係唔講名嘅AI Agent開發者，佢哋面對嘅問題係：點樣喺有限嘅上下文入面，畀AI最有效嘅指令？成篇文嘅結論係：Skill嘅設計應該以簡潔為根本，透過三級信息分層（元數據、操作手冊、工具箱）同自由度光譜（文字指令、腳本）嚟平衡靈活性同可靠性，最後跟住六步創建流程落地。
第一段：文章先解釋咩係Skill——一個文件夾，入面有SKILL.md、scripts、references、assets等，令AI多咗一項專長。SKILL.md嘅frontmatter係唯一觸發點，body係激活後先加載嘅指令。作者用一個「代碼審查」嘅反面教材話畀大家聽：好多人寫Skill嗰陣，以為係寫畀人睇，但其實係寫畀AI睇。所以描述要精確、要具體，唔好寫「保持專業、建設性語氣」呢類模糊嘢。
第二段：然後文章引入skill-creator嘅框架，分三層。第一層係根本約束——簡潔：上下文係公共資源，每句話都要值得佢佔用嘅token。唔應該放嘅檔案包括README、CHANGELOG呢類人用文件；寫約束嗰陣，「唔做咩」比「做咩」更精確，例如用反模式清單代替正面描述。第二層係兩個設計維度：信息放邊度（L1元數據、L2 body、L3資源），同埋畀AI幾大自由度（脆弱操作用腳本鎖死，創造性任務用文字引導）。第三層係六步流程：理解→規劃→初始化→編輯…
- Skill嘅核心係用最少token喺正確層級畀AI最精準嘅約束，等佢喺邊界內自由發揮
- 寫Skill要認清對象係AI唔係人，描述要具體可操作，避免模糊嘅正面詞語
- 信息分為三級：frontmatter（過濾器）、SKILL.md body（操作手冊）、scripts/references/assets（工具箱），逐層按需加載
- 自由度要根據任務脆弱程度決定：脆弱操作（如格式校驗）用腳本鎖死，靈活任務（如寫作）用文字引導
- 六步創建流程——理解、規劃、初始化、編輯、校驗、迭代——確保Skill嘅質量同一致性
內容結構
---name: code-reviewdescription: 代碼審查技能---# Code Review Skill## 背景本技能基於團隊多年的代碼審查經驗總結而成，旨在提升代碼質量和團隊協作效率。## 審查原則- 保持專業、建設性的語氣- 關注代碼質量而非個人風格- 平衡嚴格性和靈活性## 使用方式當用戶提交代碼時，對代碼進行全面審查，給出改進建議。注意保持友好和鼓勵的態度。## 版本記錄- v1.0: 初始版本- v1.1: 增加了對 Python 的支持咩係Skill？核心結構同設計對象
Skill係一個文件夾，入面裝住指令文檔、參考資料同可執行腳本。AI攞到佢，就多咗一項專長。SKILL.md係唯一必需嘅文件，frontmatter嘅description係唯一觸發點，AI靠佢決定呢個技能關唔關事。body係激活後先加載嘅操作指令。
- SKILL.md：必需，frontmatter有name同description，body係操作指令
- scripts/：可執行代碼，例如rotate_pdf.py，AI直接執行，零token成本
- references/：參考文檔，例如database schema，需要時先加載
- assets/：輸出用嘅資源，例如模板、圖片，AI直接複製唔使讀
- agents/openai.yaml：UI顯示用嘅元數據，唔影響AI行為
好多第一次寫Skill嘅人，以為係寫畀同事睇，但其實讀者係AI
根本約束：簡潔——每個token都要值得
上下文窗口係公共資源，技能、系統提示、對話歷史都爭位。所以第一原則係：每一句話都要值得佢佔用嘅token。預設假設係AI本身已經好聰明，你只需要補充佢唔知嘅嘢。
- 唔好放README、CHANGELOG呢類人用文件，AI用唔著
- 寫約束嗰陣，「唔做咩」比「做咩」更精確——用反模式清單取代正面描述
- 用簡潔嘅代碼示例代替冗長解釋，例如一個10行嘅script勝過三段文字
- 統一用祈使語氣（imperative/infinitive），減少歧義
「做咩」描述無限大可行域，「唔做咩」喺可行域上畫邊界
信息分層：L1過濾、L2操作、L3工具箱
呢個三級架構係信息熵管理系統。L1（frontmatter）始終喺上下文，約100詞，負責過濾。L2（SKILL.md body）觸發後加載，控制喺5k詞以內。L3（scripts/references/assets）按需加載，scripts執行唔讀入，零成本。
- 1 L1：name + description，係唯一觸發機制。description要講埋「咩時候用」，唔好放body
- 2 L2：body係操作手冊，寫畀另一個Codex實例睇嘅指令，唔好放觸發條件
- 3 L3：scripts執行唔讀入，references按需讀，assets直接複製
三種實戰模式：高層指南加參考文件、按領域組織多變體技能、條件性細節（基礎功能直接展示，進階功能按需連結）。避坑：避免深層嵌套引用，所有references從SKILL.md直接連結；長文件要加目錄。
scripts係最高效嘅資源——執行而唔讀入，token成本係零
自由度光譜：脆弱任務用腳本，靈活任務用文字
任務越脆弱（一錯就出事），自由度越低，用腳本鎖死；任務越靈活（多種做法都啱），自由度越高，用文字引導。喺skill-creator度，三個腳本就係低自由度嘅具體實現。
- 1 init_skill.py（398行）：初始化目錄結構，生成帶TODO嘅SKILL.md模板，自動調用generate_openai_yaml.py
- 2 generate_openai_yaml.py（226行）：格式保障，將hyphen-case轉Title Case，自動生成25-64字符嘅short_description
- 3 quick_validate.py（102行）：輸出保障，校驗frontmatter格式、名稱規範、長度約束
判斷標準：做錯後果越嚴重 → 越低自由度；正確做法越多 → 越高自由度。例子：旋轉PDF每次結果要一致，用腳本；寫技術博客十個人十種風格，用文字引導。
- 腳本適用：每次結果要一樣、涉及精確格式/長度、命名規範轉換、校驗規則
- 文字指令適用：需要理解上下文、有多種合理做法、需要創造性判斷
兩個常見錯誤：畀脆弱任務太多自由度（short_description超長度），畀創造性任務太多約束（好似填詞遊戲）
落地：六步創建流程，將原則變行動
skill-creator嘅六步流程係將前面所有原則變成可執行步驟：理解→規劃→初始化→編輯→校驗→迭代。唔好跳過任何一步，尤其係初始化一定要用腳本。
- 1 Step 1 理解：用具體例子建立共識，問用戶「會點樣觸發呢個技能？」
- 2 Step 2 規劃：分析每個例子，反覆用嘅嘢封裝成scripts/references/assets
- 3 Step 3 初始化：always用init_skill.py，唔好手動
- 4 Step 4 編輯：先做可複用資源，再更新SKILL.md，用祈使語氣
- 5 Step 5 校驗：quick_validate.py檢查格式同命名
- 6 Step 6 迭代：真實使用後發現問題，更新再測試
命名規範：只用小寫字母、數字同連字符，名稱≤64字符，優先用動詞開頭。技能文件夾名要同技能名完全一致。
好的Skill唔係一次寫成，係經過迭代打磨出嚟
咩係 Skill？點樣寫好 skill？跟住 skill-creator 嘅設計思路，揾到答案。
一、咩係 Skill？
1.1 定義
Skill 係一個文件夾，入面裝住指令文件、參考資料、可執行腳本呢啲資源。AI 攞到佢，就可以勝任一件原本唔識做嘅特定工作。
例如一個 pdf-editor 技能文件夾入面，可能有一份「點樣處理 PDF」嘅操作指令、一個旋轉 PDF 嘅 Python 腳本、一份 API 參考文件——AI 唔需要由外面再揾任何嘢，呢個文件夾入面齊曬。
呢個概念唔限於某一個產品。無論係 Codex、Claude 定係其他 AI Agent，skill 嘅本質都一樣。你可以理解佢做 AI 嘅一個能力插件——插上去，AI 就多咗一項專長；拔走，AI 仲係原本嗰個通用助手。
1.2 最小形態
一個 skill 最少只需要一個文件：
SKILL.md 嘅結構好簡單——上半部分話畀 AI 知「幾時用我」，下半部分話畀 AI 知「具體點樣做」：
上半部分叫 frontmatter（--- 之間嘅 YAML），包含 name 和 description 兩個欄位。AI 每次對話開始都會掃描所有已安裝技能嘅 frontmatter，靠 description 判斷「呢個技能同而家嘅請求有冇關」——呢個係技能唯一嘅觸發點。
下半部分叫 body（Markdown 正文），係技能被激活之後先加載嘅操作指令。如果技能冇觸發到，AI 永遠唔會讀到呢度。
1.3 完整結構
當一個技能變複雜嘅時候，單靠一個 SKILL.md 就唔夠。
例如你要做一個「PDF 處理」技能：SKILL.md 寫咗處理流程，但旋轉 PDF 嘅代碼每次都一樣，每次叫 AI 重寫又曬時間又可能出錯——不如直接放一個寫好嘅 Python 腳本。再好似「前端項目生成器」技能：每次都要一套 HTML/React 嘅樣板文件，不如直接放一個模板目錄叫 AI 拷貝出去改。
所以完整嘅 skill 目錄可以包含呢啲嘢：
逐個說明：
• SKILL.md — 唯一必需嘅文件，前面已經介紹過 • scripts/ — 寫好嘅程式，AI 唔需要讀明佢，直接 call shell 執行就得。例如 scripts/rotate_pdf.py，AI 只要跑python rotate_pdf.py input.pdf 90就可以旋轉 PDF，唔使每次都重新寫旋轉邏輯。適合啲結果一定要精確、唔可以畀 AI 自由發揮的操作• references/ — AI 喺工作期間需要查閲嘅參考資料。例如一個「BigQuery 查詢」技能，AI 要知道公司有邊啲表、每個表有咩字段，呢啲資訊放喺 references/schema.md裏面，AI 有需要先讀取。同 scripts 嘅分別係：references 係畀 AI 讀嘅，scripts 係畀 AI 執行的• assets/ — 唔係畀 AI 睇，係直接用喺最終產出嘅文件。例如一個「前端項目生成器」技能， assets/frontend-template/入面放住一套 HTML/React 樣板代碼，AI 直接成個模板拷貝出去，喺上面改。再好似assets/logo.png係公司 logo，AI 生成網頁嗰陣直接引用。AI 唔需要「讀明」一張 logo 圖片，只需要知佢喺邊、幾時放落去• agents/openai.yaml — 技能嘅「名片」。好多 AI 產品會喺界面上展示一個技能列表，畀用戶揀或者搜尋。呢個文件入面存嘅係列表顯示嘅名稱、簡介、圖標等資訊。佢唔影響 AI 嘅行為，純粹係畀產品界面用
二、你係幫人寫指令，定係幫 AI 寫指令？
知道 skill 係咩，下一步就係寫一個。但大多數人第一次寫出嚟嘅 skill 都有同一個問題。
睇一個例子。假設要做一個「代碼審查」技能，你可能會咁樣寫：
---
name: code-review
description: 代碼審查技能
---
# Code Review Skill
## 背景
本技能基於團隊多年的代碼審查經驗總結而成，旨在提升代碼質量和團隊協作效率。
## 審查原則
- 保持專業、建設性的語氣
- 關注代碼質量而非個人風格
- 平衡嚴格性和靈活性
## 使用方式
當用戶提交代碼時，對代碼進行全面審查，給出改進建議。注意保持友好和鼓勵的態度。
## 版本記錄
- v1.0: 初始版本
- v1.1: 增加了對 Python 的支持如果呢份係一份畀人睇嘅團隊文件，佢寫得唔錯——有背景、有原則、有使用方式，甚至仲有版本記錄。
但 skill 嘅讀者係 AI。用呢個角度重新審視：
• 「基於團隊多年經驗總結」 — AI 唔關心呢個技能係點樣嚟，佢只需要知道而家應該點樣做 • 「保持專業、建設性嘅語氣」 — 人類讀完可以 get 到一個大概感覺，但 AI 會將「專業」同「建設性」展開成無數種組合，每次輸出都唔一樣 • 「平衡嚴格性同靈活性」 — 人類經驗豐富嘅審查者知道幾時嚴格幾時靈活，但 AI 冇呢個直覺，呢句說話等於冇講 • 「全面審查，畀出改進建議」 — 呢個係對人類審查者嘅期望，但 AI 需要嘅係：先檢查咩？再檢查咩？咩問題一定要指出？咩問題可以忽略？ • 「版本記錄」 — AI 每次被喚醒都係全新，v1.0 定 v1.1 對佢冇意義 • description 只寫咗「代碼審查技能」 — AI 靠 description 判斷係咪觸發，「代碼審查技能」五個字太模糊：用戶話「幫我睇下呢段代碼」要觸發嗎？「呢個函數性能點樣」要觸發嗎？
每一條單獨睇都冇問題，但佢哋都係寫畀人睇嘅。問題唔係寫得唔夠多，而係寫錯咗對象。
咁正確嘅寫法係點樣？我哋睇一個現成嘅答案——codex 嘅 skill-creator。佢係一個「創建 skill 嘅 skill」，佢自己嘅 SKILL.md 就係一份關於「點樣幫 AI 寫指令」嘅最佳實踐。
三、skill-creator 嘅整體框架
打開 skill-creator 嘅 SKILL.md（約 370 行），喺深入任何細節之前，我哋先建立對佢嘅整體認知。
skill-creator 要解決嘅問題只有一個：點樣喺有限嘅上下文窗口裏面，畀 AI 最有效嘅指令？
圍繞呢個問題，佢畀出一套完整嘅設計體系，可以用三個層次嚟理解。
第一層：根本約束——簡潔
AI 嘅上下文窗口係有限嘅，而且係共享嘅（系統提示、對話歷史、所有已安裝技能嘅元數據都喺入面）。你個 skill 佔得愈多，留畀其他用途嘅就愈少。所以 skill-creator 嘅第一原則就係：每一句說話都要值得佢佔用嘅 token。
第二層：兩個設計維度
喺「簡潔」呢個約束之下，寫 skill 時會面對兩個核心決策：
維度一：資訊擺喺邊度？
唔係所有資訊都需要一開始就加載。skill-creator 設計咗一個三級分層架構，令唔同嘅資訊喺唔同嘅時機進入上下文：
• L1（元數據）：永遠喺上下文中，約 100 詞——AI 靠佢判斷要唔要激活呢個技能 • L2（SKILL.md body）：觸發後先加載，控制在 5k 詞以內——操作指令 • L3（scripts/references/assets）：按需要使用，冇上限——其中 scripts 執行而唔讀入，零 token 成本
呢個解決咗「點樣用最少嘅 token 承載最多嘅資訊」。
維度二：畀 AI 幾大自由度？
唔係所有任務都適合畀 AI 自由發揮。
舉個例：叫 AI 寫一篇技術博客，十個人寫出十種風格都得——你只需要畀方向，具體點寫叫 AI 自己決定。呢個就係高自由度。
但叫 AI 生成一個 YAML 設定檔就唔同。例如 skill-creator 要生成嘅 openai.yaml，入面有個 short_description 字段，要求 25-64 個字符、首字母大寫、唔可以有引號。AI 寫成 65 個字符？唔得，產品界面會截斷。寫成 24 個字符？唔得，校驗唔通過。漏咗首字母大寫？界面顯示唔一致。呢類任務差一個字符就出問題，你唔可以畀 AI 自由發揮，必須用腳本鎖死格式——呢個就係低自由度。呢類任務叫「脆弱操作」：唔係話佢複雜，而係話佢做啱得一種方式，做錯有一百種方式。
呢個解決咗「點樣喺 AI 嘅靈活性同輸出嘅可靠性之間取得平衡」。
第三層：落地流程
有咗原則同架構，skill-creator 最後畀出一個六步創建流程，將設計思想變成可執行嘅操作步驟：
理解→規劃→初始化→編輯→校驗→迭代。其中腳本代碼貫穿流程，形成確定性嘅保障：
框架總覽
三個層次嘅關係：
接落嚟嘅每一章都會喺呢個框架入面展開。
四、根本約束：簡潔
框架位置：第一層
4.1 核心約束
AI 嘅上下文窗口就好似一張工作枱——佢同一時間可以攤開嘅資料係有限嘅。而呢張工作枱上面已經放咗唔少嘢：系統自己嘅規則、用戶之前講過嘅說話、所有已安裝技能嘅簡介。你個 skill 一旦被激活，佢嘅內容都要攤上去。工作枱得咁大，你佔得愈多，留畀其他嘢嘅空間就愈少。
所以 skill-creator 將呢一點寫成第一條原則：
The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
既然工作枱空間有限，咁寫 skill 嗰陣點樣判斷一段內容應唔應該放落去？skill-creator 畀咗一個前提假設：AI 本身已經好聰明，你只需要補充佢唔知嘅嘢。
Default assumption: Codex is already very smart. Only add context Codex doesn't already have.
基於呢個假設，每寫一段內容之前問自己兩個問題：
• 「AI 係咪已經知道呢個？」 — 例如「Python 嘅 for loop 點樣寫」，AI 梗係知，唔使教 • 「呢段內容值唔值得佔用工作枱上面嘅空間？」 — 一段 200 字嘅解釋，可唔可以用一個 10 行嘅代碼示例代替？
實操推論：用簡潔嘅示例代替冗長嘅解釋。一個好嘅代碼示例好過三段文字描述。
4.2 咩嘢唔應該放入 Skill？
Skill-creator 明確列出咗禁止清單：
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files.
唔應該有嘅文件：
• README.md • INSTALLATION_GUIDE.md • QUICK_REFERENCE.md • CHANGELOG.md
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
原因好簡單：skill 嘅讀者係 AI，唔係人類開發者。AI 唔需要安裝指南、更新日誌、快速參考呢啲「人類輔助文件」。每一個多餘嘅文件都係噪音。
4.3 寫約束嗰陣，「唔做咩」比「做咩」更精確
簡潔唔止係「少寫」，仲包括「寫啱」。睇一個例子。
當 skill-creator 創建 laotou-thought-style（一種寫作風格技能）時，佢沒有寫：
請用温暖、剋制、有洞察力的語氣寫作。呢種正面描述睇落清晰，但對 AI 嚟講，「温暖」嘅程度、「剋制」同「有洞察力」之間嘅平衡——全部係模糊空間。
佢做嘅係寫咗一份反模式清單（references/anti-patterns.md）：
每一條都係具體、可檢測、有明確修正方案嘅。
背後嘅原理：
"做什麼" → 描述一個無限大的可行域 → AI 在裏面隨機遊走
"不做什麼" → 在可行域上畫邊界 → AI 的行為空間被收窄到你想要的範圍skill-creator 自身都跟咗呢個原則——佢嘅 SKILL.md 用咗好多篇幅講「咩唔應該寫」（What to Not Include in a Skill），而唔係泛泛咁話「寫好內容」。
當你寫完 SKILL.md，做一次「反轉測試」：每一條正面指導，可唔可以改寫成「唔好做 X」嘅形式？如果可以，改寫後通常更精確。
4.4 統一使用祈使語氣
skill-creator 要求 SKILL.md 嘅正文統一使用祈使語氣/不定式（Always use imperative/infinitive form）。呢個唔係美學偏好，而係為咗減少歧義——祈使句天然就係指令。
五、設計維度一：資訊擺喺邊度？
框架位置：第二層 — 維度一
喺第三章嘅框架總覽入面，我哋已經睇到三級分層架構嘅全貌。呢一章展開講佢嘅細節。
5.1 三級漸進式加載
skill-creator 原文對三個層級嘅定義：
1. Metadata (name + description) - Always in context (~100 words) 2. SKILL.md body - When skill triggers (<5k words) 3. Bundled resources - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
| L1 | 始終 | ||
| L2 | |||
| L3 |
呢個本質上係一個資訊熵管理系統：
• L1 係過濾器 — 從幾十個已安裝技能中篩選出當前需要嗰個。description 唔精確 → 誤觸發或漏觸發 • L2 係操作手冊 — 觸發後話畀 AI 知應該點樣做。太長 → 注意力被稀釋。body 控制在 500 行以內 • L3 係工具箱 — 只需要嗰陣先打開。其中 scripts/ 最高效——執行而唔讀入，零 token 成本
5.2 Frontmatter：觸發機制嘅全部來源
Frontmatter 只有兩個必需字段：name 和 description。但 description 嘅寫法好重要：
This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
skill-creator 自己嘅 description 係咁樣寫：
description: Guide for creating effective skills. This skill should be used when
users want to create a new skill (or update an existing skill) that extends
Codex's capabilities with specialized knowledge, workflows, or tool integrations.佢唔止話「做咩」（creating effective skills），仲話「幾時用」（when users want to create a new skill or update an existing skill）。
關鍵規則：
• 將所有「when to use」資訊放喺 description 度，唔好放喺 body 度。body 係觸發後先加載，嗰陣 Codex 已經決定用，講「幾時用」嘅資訊已經遲咗 • 唔好喺 frontmatter 放 name和description以外嘅字段（license、allowed-tools、metadata除外）
一個好嘅 description 示例（docx 技能）：
"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
5.3 四種捆綁資源嘅本質區別
理解呢四種資源嘅區別，係理解成個 skill 系統嘅關鍵：
Scripts（scripts/）
可執行代碼（Python/Bash 等），用於需要確定性可靠性或反覆重寫嘅任務。
• 幾時需要：同樣嘅代碼每次都要重新寫，或者需要確定性嘅可靠輸出 • 舉例： scripts/rotate_pdf.py用於 PDF 旋轉任務• 核心優勢：token 高效、確定性、可以執行而唔讀入上下文窗口 • 注意：腳本有時仍然需要畀 Codex 讀取，用於修補或環境適配
References（references/）
文件同參考材料，有需要嗰陣加載到上下文中，輔助 Codex 嘅思考過程。
• 幾時需要：Codex 工作嗰陣需要參考嘅詳細文件 • 舉例： references/finance.md（財務 schema）、references/api_docs.md（API 規範）、references/policies.md（公司政策）• 用途：數據庫 schema、API 文件、領域知識、公司政策、詳細工作流指南 • 核心優勢：保持 SKILL.md 精煉，只喺 Codex 判斷需要嗰陣先加載 • 最佳實踐：如果文件好大（>10k 詞），喺 SKILL.md 入麪包含 grep 搜尋模式 • 避免重複：資訊應該只存在於 SKILL.md 或 references 文件中，唔可以兩邊都有。詳細資訊優先放 references，SKILL.md 只保留核心流程指令同工作流指導
Assets（assets/）
唔係用嚟加載到上下文嘅文件，而係直接用喺 Codex 產出物入面嘅資源。
• 幾時需要：技能需要喺最終輸出中使用嘅文件 • 舉例： assets/logo.png（品牌素材）、assets/slides.pptx（PPT 模板）、assets/frontend-template/（HTML/React 樣板）、assets/font.ttf（字體）• 用途：模板、圖片、圖標、樣板代碼、字體、示例文件——呢啲會被複製或修改 • 核心優勢：將輸出資源同文件分離，Codex 可以用佢哋而唔使讀入上下文
Agents 元數據（agents/openai.yaml）（建議）
面向 UI 嘅元數據，唔畀 AI 讀，畀產品前端讀：
• 包含 display_name、short_description、default_prompt等字段• 透過腳本 generate_openai_yaml.py確定性生成，而唔係手寫• 更新 SKILL.md 之後要檢查 agents/openai.yaml係咪仲匹配，過期就重新生成• 詳細字段定義見 references/openai_yaml.md
5.4 漸進式披露嘅三種實戰模式
Skill-creator 畀出三種將內容拆分到 references 嘅具體模式：
Pattern 1：高層指南 + 參考文件
# PDF Processing
## Quick start
Extract text with pdfplumber:
[code example]
## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patternsCodex 只喺需要嗰陣先加載 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
Pattern 2：按領域組織
多領域/多變體技能，按領域拆分避免加載無關內容：
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)用戶問銷售指標嗰陣，Codex 只讀 sales.md。
同樣適用於多框架/多變體場景：
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)Pattern 3：條件性細節
基礎功能直接展示，高級功能按需要連結：
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)5.5 兩條重要嘅避坑指南
1. 避免深層嵌套引用 — 所有 reference 文件應該由 SKILL.md 直接連結，唔好 A → B → C 式嵌套 2. 長文件加目錄 — 超過 100 行嘅 reference 文件要喺頂部加 TOC，方便 Codex 預覽全貌
5.6 常見嘅層錯位
六、設計維度二：畀 AI 幾大自由度？
框架位置：第二層 — 維度二
知咗資訊應該擺喺邊度、應該點樣約束，下一個問題係：AI 做咩，腳本做咩？
AI 好擅長理解語義、生成文本、做創造性工作。但佢唔擅長精確格式控制、長度約束、命名規範——呢啲「脆弱操作」。
6.1 三個自由度檔位
Skill-creator 用一個自由度光譜嚟處理呢啲不均勻性（見第三章框架圖）：
Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
高自由度（文字指令）：多種方法都可行嗰陣，決策依賴上下文，用啓發式引導。
中自由度（偽代碼/帶參數嘅腳本）：有最佳實踐但容許變通，設定影響行為。
低自由度（具體腳本，少量參數）：操作脆弱容易出錯，一致性好重要，必須跟特定序列。
核心邏輯：
任務越脆弱（容易出錯） → 自由度越低 → 用腳本鎖死
任務越靈活（多種方案都對） → 自由度越高 → 用文字引導6.2 skill-creator 自身嘅自由度分配
| 低 | init_skill.py | |
| 低 | generate_openai_yaml.py | |
| 低 | quick_validate.py |
6.3 兩個方向嘅錯誤
錯誤 1：畀脆弱任務太多自由度
# 錯誤
請生成一個 openai.yaml 文件，包含 display_name 和 short_description。
# 後果：short_description 可能超過 64 字符限制，大小寫可能不一致Skill-creator 嘅做法：用 generate_openai_yaml.py 腳本鎖死格式。AI 只提供參數值，腳本保證輸出合規。
錯誤 2：畀創造性任務太多約束
# 錯誤
第一段必須以"昨天"開頭，第二段必須包含"本質上"，最後一段以"慢慢來"結尾。
# 後果：生成的文本像填詞遊戲Skill-creator 嘅做法：畀結構比例（場景層 ≤30%，原理層 30-40%），但唔鎖定具體用詞。
6.4 判斷標準
兩個問題：
1. 做錯咗後果有幾嚴重？ — 越嚴重 → 越低自由度 2. 有幾多種「正確」嘅做法？ — 越多 → 越高自由度
6.5 低自由度嘅實現：skill-creator 嘅三個腳本
理解咗自由度光譜，就可以理解 skill-creator 點解有三個腳本——佢哋就係「低自由度」嘅具體實現（腳本之間嘅互動關係見第三章框架圖）。
init_skill.py（輸入保障，398 行）
初始化新技能目錄嘅腳手架工具，類似 create-react-app 之於 React 項目：
scripts/init_skill.py <skill-name> --path <output-directory> \
[--resources scripts,references,assets] [--examples] \
[--interface key=value]核心功能：
• 創建技能目錄 • 生成帶 TODO 佔位符嘅 SKILL.md 模板（TODO 係畀 Codex 睇嘅「填空題」） • 調用 generate_openai_yaml.py生成agents/openai.yaml（通過--interface key=value傳入 AI 生成嘅 display_name、short_description、default_prompt）• 可選創建 scripts/、references/、assets/子目錄• 可選添加示例文件（ --examples）• 內置 normalize_skill_name()自動將任意用戶輸入標準化為 hyphen-case
使用示例：
scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examplesgenerate_openai_yaml.py（格式保障，226 行）
專門負責生成同更新 agents/openai.yaml：
• 從 SKILL.md 嘅 frontmatter 讀取技能名 • 自動將 hyphen-case 轉為 Title Case（ my-cool-skill→My Cool Skill）• 內置縮寫詞典（GH、MCP、API 等保持大寫）同品牌詞典（openai → OpenAI） • 自動生成 25-64 字符嘅 short_description• 支持 --interface key=value覆蓋任意字段
scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=valuequick_validate.py（輸出保障，102 行）
技能創建後嘅「質檢」：
scripts/quick_validate.py <path/to/skill-folder>校驗內容：
• SKILL.md 係咪存在 • YAML frontmatter 格式係咪合法 • name：係咪 hyphen-case，≤ 64 字符，冇連續/首尾連字符• description：係咪存在，冇尖括號，≤ 1024 字符• 只允許 name、description、license、allowed-tools、metadata呢 5 個 frontmatter 鍵
6.6 質量保障鏈
三個腳本形成咗一條工作流鏈路，夾住中間嘅創造性步驟：
init_skill.py（輸入保障）
命名標準化 + 目錄結構創建 + 模板生成
→ 確保起點正確
↓
AI 創造性編寫（高自由度）
→ SKILL.md 內容、references、自定義 scripts
↓
quick_validate.py（輸出保障）
frontmatter 格式 + 命名規範 + 長度約束校驗
→ 確保終點合規腳本係「執行而唔讀入」嘅——零 token 成本。你可以將任意複雜嘅確定性邏輯封裝入腳本，而唔使擔心佢佔用上下文。呢個就係點解 skill-creator 將命名轉換（縮寫詞典、品牌詞典）、長度約束（25-64 字符）、格式校驗呢啲碎濕濕但脆弱嘅操作全部交畀腳本代碼。
6.7 咩應該封裝成腳本？
每次執行結果必須一樣 → 腳本
涉及精確格式/長度約束 → 腳本
涉及命名規範轉換 → 腳本
需要校驗規則匹配 → 腳本
同樣的代碼每次都要重新寫 → 腳本
需要理解上下文 → 文字指令
有多種合理做法 → 文字指令
需要創造性判斷 → 文字指令腳本嘅定義係執行，雖然有時仍然要畀 Codex 讀取（用於修補或環境適配），但大多數時候佢哋係「執行而唔讀入」嘅。
七、落地：六步創建流程
框架位置：第三層
有咗前面嘅原則同架構，skill-creator 最後畀出一個六步創建流程，將設計思想變成可執行嘅操作步驟（見第三章框架圖）。
7.0 命名規範
喺開始之前，先確定命名：
• 只用細楷字母、數字同連字符；將用戶提供嘅名稱標準化為 hyphen-case（如 "Plan Mode" → plan-mode）• 名稱 ≤ 64 字符 • 優先揀簡短、以動詞開頭嘅短語嚟描述動作 • 需要嗰陣用工具名做命名空間（如 gh-address-comments、linear-address-issue）• 技能文件夾名同技能名完全一致
7.1 Step 1：理解技能——用具體例子建立共識
Skip this step only when the skill's usage patterns are already clearly understood.
要創建一個有效嘅 skill，一定要先清楚理解具體嘅使用例子。呢啲理解可以嚟自用戶提供嘅例子，亦可以嚟自生成、經用戶驗證嘅例子。
以構建 image-editor 技能為例，可以問用戶：
• 「image-editor 技能應該支援咩功能？編輯、旋轉，仲有其他嗎？」 • 「可唔可以畀啲用呢個技能嘅例子？」 • 「我諗到用戶會講『去掉呢張相嘅紅眼』或『旋轉呢張圖片』。仲有其他用法嗎？」 • 「用戶會講咩嘢說話嚟觸發呢個技能？」
注意：唔好一次問太多問題。先問最重要嘅，然後跟住需要再追問。
完成標誌：對技能應該支援嘅功能有咗清晰嘅認識。
7.2 Step 2：規劃可重用嘅技能內容
對每個具體例子做兩個分析：
1. 如果由零開始做呢件事，需要啲咩？ 2. 當中邊啲會反覆使用？
反覆用嘅嘢 → 封裝成 scripts/references/assets。
skill-creator 畀咗三個典型分析案例：
案例 1：pdf-editor 技能（用戶問「幫我旋轉呢個 PDF」）
• 旋轉 PDF 每次都要重寫同樣嘅代碼 • → 封裝為 scripts/rotate_pdf.py
案例 2：frontend-webapp-builder 技能（用戶問「幫我做一個 todo app」或「做一個步數追蹤儀錶板」）
• 寫前端 webapp 每次都需要同樣嘅 HTML/React 樣板代碼 • → 封裝為 assets/hello-world/模板目錄
案例 3：big-query 技能（用戶問「今日有幾多用戶登入咗？」）
• 查 BigQuery 每次都要重新發現表嘅 schema 同關係 • → 封裝為 references/schema.md
完成標誌：列出咗所有要包含嘅可重用資源清單（scripts、references、assets）。
7.3 Step 3：初始化技能
When creating a new skill from scratch, always run the
init_skill.pyscript.
呢度用嘅係「always」——唔係「建議」，係「一定要」。原因：
• 腳本生成嘅目錄結構保證符合規範 • 模板中嘅 TODO 提醒確保唔漏咗必需字段 • agents/openai.yaml嘅格式約束（字段長度、引號規則）靠手寫容易出錯
這是低自由度原則嘅直接應用：初始化係一個脆弱操作，用腳本消除出錯可能。
初始化後：
• 定製 SKILL.md 並根據需要添加資源 • 如果用咗 --examples，替換或刪除佔位符文件
7.4 Step 4：編輯技能
呢個係最核心嘅步驟，分兩階段：
階段一：先實現可重用資源
由 Step 2 規劃嘅資源開始：實現 scripts/、references/、assets/ 文件。
注意：
• 呢一步可能需要用戶輸入（例如 brand-guidelines技能需要用戶提供品牌素材）• 新加嘅腳本必須透過實際運行嚟測試，確保冇 bug 且輸出符合預期 • 如果有好多類似嘅腳本，只需測試代表性樣本嚟建立信心 • 如果用咗 --examples，刪除唔需要嘅佔位符文件。淨係創建真正需要嘅資源目錄
階段二：更新 SKILL.md
Frontmatter 寫法：
---
name: skill-name
description: >-
描述技能做什麼 + 具體什麼時候用。
把所有 "when to use" 信息放這裏，不要放在 body 裏。
---Body 寫法：
寫畀另一個 Codex 實例嘅操作指令。包含對 Codex 有幫助但唔顯而易見嘅資訊：程序性知識、領域細節、可重用資源嘅用法。
統一使用祈使語氣/不定式。
7.5 Step 5：校驗技能
scripts/quick_validate.py <path/to/skill-folder>校驗 YAML frontmatter 格式、必需字段、命名規則。唔通過就修復後重新運行。
7.6 Step 6：迭代
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
迭代工作流：
1. 喺真實任務上用技能 2. 發現吃力或低效嘅地方 3. 揾出 SKILL.md 或捆綁資源應該點樣更新 4. 執行變更並重新測試
好嘅 skill 唔係一次寫成嘅。skill-creator 創建嘅 laotou-thought-style 技能，喺第一次生成之後就迭代咗 openai.yaml 的 short_description 和 default_prompt——由泛泛嘅描述變做更精確嘅操作指令。
八、總結
返翻最初嘅問題：點樣寫出好嘅 skill？
回顧成個框架：
首先明確Skill 係幫 AI 寫指令，而唔係幫人，Skill 本質係：用最少嘅 token，喺正確嘅層級，畀 AI 最精準嘅約束，等佢喺邊界內自由發揮。
什麼是 Skill？怎麼寫好skill？沿着 skill-creator 的設計思路，找到答案。
一、什麼是 Skill？
1.1 定義
Skill 是一個文件夾，裏面裝着指令文檔、參考資料、可執行腳本等資源。AI 拿到它，就能勝任一項原本不會的特定工作。
比如一個 pdf-editor 技能文件夾裏，可能有一份"怎麼處理 PDF"的操作指令、一個旋轉 PDF 的 Python 腳本、一份 API 參考文檔——AI 不需要從外部再找任何東西，這個文件夾裏全有了。
這個概念不限於某一個產品。無論是 Codex、Claude 還是其他 AI Agent，skill 的本質都一樣。你可以把它理解為 AI 的一個能力插件——插上去，AI 就多了一項專長；拔掉，AI 還是原來那個通用助手。
1.2 最小形態
一個 skill 最少只需要一個文件：
SKILL.md 的結構很簡單——上半部分告訴 AI"什麼時候用我"，下半部分告訴 AI"具體怎麼做"：
上半部分叫 frontmatter（--- 之間的 YAML），包含 name 和 description 兩個字段。AI 在每次對話開始時都會掃描所有已安裝技能的 frontmatter，靠 description 來判斷"這個技能和當前請求相關嗎"——這是技能的唯一觸發點。
下半部分叫 body（Markdown 正文），是技能被激活之後才加載的操作指令。如果技能沒被觸發，AI 永遠不會讀到這裏。
1.3 完整結構
當一個技能變複雜時，單靠一個 SKILL.md 就不夠了。
比如你要做一個"PDF 處理"技能：SKILL.md 裏寫了處理流程，但旋轉 PDF 的代碼每次都一樣，每次讓 AI 重寫既浪費時間又可能出錯——不如直接放一個寫好的 Python 腳本。再比如"前端項目生成器"技能：每次都要一套 HTML/React 的樣板文件，不如直接放一個模板目錄讓 AI 拷貝出來改。
所以完整的 skill 目錄可以包含這些東西：
逐個說明：
• SKILL.md — 唯一必需的文件，前面已經介紹過 • scripts/ — 寫好的程序，AI 不需要讀懂它，直接調用 shell 執行就行。比如 scripts/rotate_pdf.py，AI 只要跑python rotate_pdf.py input.pdf 90就能旋轉 PDF，不用每次重新寫旋轉邏輯。適合那些結果必須精確、不能讓 AI 自由發揮的操作• references/ — AI 在工作過程中需要查閲的參考資料。比如一個"BigQuery 查詢"技能，AI 要知道公司有哪些表、每個表有什麼字段，這些信息放在 references/schema.md裏，AI 需要時再讀取。和 scripts 的區別是：references 是給 AI 讀的，scripts 是給 AI 執行的• assets/ — 不是給 AI 看的，而是直接用在最終產出裏的文件。比如一個"前端項目生成器"技能， assets/frontend-template/裏放着一套 HTML/React 樣板代碼，AI 直接把這套模板拷貝出來，在上面修改。再比如assets/logo.png是公司 logo，AI 生成網頁時直接引用它。AI 不需要"讀懂"一張 logo 圖片，只需要知道它在哪、什麼時候放進去• agents/openai.yaml — 技能的"名片"。很多 AI 產品會在界面上展示一個技能列表，讓用戶選擇或搜索。這個文件裏存的就是列表中顯示的名稱、簡介、圖標等信息。它不影響 AI 的行為，純粹是給產品界面用的
二、你是在給人寫指令，還是在給 AI 寫指令？
知道了 skill 是什麼，下一步就是寫一個。但大多數人第一次寫出來的 skill 都有同一個問題。
看一個例子。假設要做一個"代碼審查"技能，你可能會這樣寫：
---
name: code-review
description: 代碼審查技能
---
# Code Review Skill
## 背景
本技能基於團隊多年的代碼審查經驗總結而成，旨在提升代碼質量和團隊協作效率。
## 審查原則
- 保持專業、建設性的語氣
- 關注代碼質量而非個人風格
- 平衡嚴格性和靈活性
## 使用方式
當用戶提交代碼時，對代碼進行全面審查，給出改進建議。注意保持友好和鼓勵的態度。
## 版本記錄
- v1.0: 初始版本
- v1.1: 增加了對 Python 的支持如果這是一份給人看的團隊文檔，它寫得不錯——有背景、有原則、有使用方式，甚至還有版本記錄。
但 skill 的讀者是 AI。用這個視角重新審視：
• "基於團隊多年經驗總結" — AI 不關心這個技能是怎麼來的，它只需要知道現在該怎麼做 • "保持專業、建設性的語氣" — 人類讀了能 get 到一個大致的感覺，但 AI 會把"專業"和"建設性"展開成無數種組合，每次輸出都不一樣 • "平衡嚴格性和靈活性" — 人類經驗豐富的審查者知道什麼時候嚴格什麼時候靈活，但 AI 沒有這個直覺，這句話等於沒說 • "全面審查，給出改進建議" — 這是對人類審查者的期望，但 AI 需要的是：先檢查什麼？再檢查什麼？什麼問題必須指出？什麼問題可以忽略？ • "版本記錄" — AI 每次被喚醒都是全新的，v1.0 還是 v1.1 對它沒有意義 • description 只寫了"代碼審查技能" — AI 靠 description 判斷是否觸發，"代碼審查技能"五個字太模糊：用戶說"幫我看看這段代碼"要觸發嗎？"這個函數性能怎麼樣"要觸發嗎？
每一條單獨看都沒啥問題，但它們都是寫給人看的。問題不在於寫得不夠多，而在於寫錯了對象。
那正確的寫法是什麼樣的？我們來看一個現成的答案——codex的skill-creator。它是一個"創建 skill 的 skill"，它自己的 SKILL.md 就是一份關於"如何給 AI 寫指令"的最佳實踐。
三、skill-creator 的整體框架
打開 skill-creator 的 SKILL.md（約 370 行），在深入任何細節之前，我們先建立對它的整體認知。
skill-creator 要解決的問題只有一個：怎麼在有限的上下文窗口裏，給 AI 最有效的指令？
圍繞這個問題，它給出了一套完整的設計體系，可以用三個層次來理解。
第一層：根本約束——簡潔
AI 的上下文窗口是有限的，而且是共享的（系統提示、對話歷史、所有已安裝技能的元數據都在裏面）。你的 skill 佔得越多，留給其他用途的就越少。所以 skill-creator 的第一原則就是：每一句話都要值得它佔用的 token。
第二層：兩個設計維度
在"簡潔"這個約束下，寫 skill 時面臨兩個核心決策：
維度一：信息放在哪裏？
不是所有信息都需要一開始就加載。skill-creator 設計了一個三級分層架構，讓不同的信息在不同的時機進入上下文：
• L1（元數據）：始終在上下文中，約 100 詞——AI 靠它判斷要不要激活這個技能 • L2（SKILL.md body）：觸發後才加載，控制在 5k 詞以內——操作指令 • L3（scripts/references/assets）：按需使用，無上限——其中 scripts 執行而不讀入，零 token 成本
這解決了"怎麼用最少的 token 承載最多的信息"。
維度二：給 AI 多大自由度？
不是所有任務都適合讓 AI 自由發揮。
舉個例子：讓 AI 寫一篇技術博客，十個人寫出十種風格都可以——你只需要給方向，具體怎麼寫讓 AI 自己決定。這就是高自由度。
但讓 AI 生成一個 YAML 配置文件就不一樣了。比如 skill-creator 要生成的 openai.yaml，裏面有個 short_description 字段，要求 25-64 個字符、首字母大寫、不能有引號。AI 寫成 65 個字符？不行，產品界面會截斷。寫成 24 個字符？不行，校驗不通過。漏了首字母大寫？界面顯示不一致。這種任務差一個字符就出問題，你不能讓 AI 自由發揮，必須用腳本來鎖死格式——這就是低自由度。這類任務叫"脆弱操作"：不是說它複雜，而是說它做對只有一種方式，做錯有一百種方式。
這解決了"怎麼在 AI 的靈活性和輸出的可靠性之間取得平衡"。
第三層：落地流程
有了原則和架構，skill-creator 最後給出了一個六步創建流程，把設計思想變成可執行的操作步驟：
理解→規劃→初始化→編輯→校驗→迭代。其中腳本代碼貫穿流程，形成確定性的保障：
框架總覽
三個層次的關係：
接下來的每一章都在這個框架內展開。
四、根本約束：簡潔
框架位置：第一層
4.1 核心約束
AI 的上下文窗口就像一張工作台——它同一時間能攤開的資料是有限的。而這張工作台上已經放着不少東西了：系統自己的規則、用戶之前說過的話、所有已安裝技能的簡介。你的 skill 一旦被激活，它的內容也要攤上去。工作台就這麼大，你佔得越多，留給其他東西的空間就越少。
所以 skill-creator 把這一點寫成了第一條原則：
The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
既然工作台空間有限，那寫 skill 時怎麼判斷一段內容該不該放進去？skill-creator 給了一個前提假設：AI 本身已經很聰明瞭，你只需要補充它不知道的東西。
Default assumption: Codex is already very smart. Only add context Codex doesn't already have.
基於這個假設，每寫一段內容之前問自己兩個問題：
• "AI 是不是已經知道這個了？" — 比如"Python 的 for 循環怎麼寫"，AI 當然知道，不用教 • "這段內容值不值得佔用工作台上的空間？" — 一段 200 字的解釋，能不能用一個 10 行的代碼示例替代？
實操推論：用簡潔的示例代替冗長的解釋。一個好的代碼示例勝過三段文字描述。
4.2 什麼不該放進 Skill？
Skill-creator 明確列出了禁止清單：
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files.
不該有的文件：
• README.md • INSTALLATION_GUIDE.md • QUICK_REFERENCE.md • CHANGELOG.md
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
原因很簡單：skill 的讀者是 AI，不是人類開發者。AI 不需要安裝指南、更新日誌、快速參考這些"人類輔助文檔"。每一個多餘的文件都是噪音。
4.3 寫約束時，"不做什麼"比"做什麼"更精確
簡潔不只是"少寫"，還包括"寫對"。看一個例子。
當 skill-creator 創建 laotou-thought-style（一種寫作風格技能）時，它沒有寫：
請用温暖、剋制、有洞察力的語氣寫作。這種正面描述看起來清晰，但對 AI 來說，"温暖"的程度、"剋制"和"有洞察力"之間的平衡——全是模糊空間。
它做的是寫了一份反模式清單（references/anti-patterns.md）：
每一條都是具體的、可檢測的、有明確修正方案的。
背後的原理：
"做什麼" → 描述一個無限大的可行域 → AI 在裏面隨機遊走
"不做什麼" → 在可行域上畫邊界 → AI 的行為空間被收窄到你想要的範圍skill-creator 自身也遵循了這個原則——它的 SKILL.md 用了很大篇幅說"什麼不該寫"（What to Not Include in a Skill），而不是泛泛地說"寫好內容"。
當你寫完 SKILL.md，做一次"反轉測試"：每一條正面指導，能不能改寫成"不要做X"的形式？如果可以，改寫後通常更精確。
4.4 統一使用祈使語氣
skill-creator 要求 SKILL.md 的正文統一使用祈使語氣/不定式（Always use imperative/infinitive form）。這不是美學偏好，而是為了減少歧義——祈使句天然就是指令。
五、設計維度一：信息放在哪裏？
框架位置：第二層 — 維度一
在第三章的框架總覽中，我們已經看到了三級分層架構的全貌。這一章展開講它的細節。
5.1 三級漸進式加載
skill-creator 原文對三個層級的定義：
1. Metadata (name + description) - Always in context (~100 words) 2. SKILL.md body - When skill triggers (<5k words) 3. Bundled resources - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
| L1 | 始終 | ||
| L2 | |||
| L3 |
這本質上是一個信息熵管理系統：
• L1 是過濾器 — 從幾十個已安裝技能中篩選出當前需要的那一個。description 不精確 → 誤觸發或漏觸發 • L2 是操作手冊 — 觸發後告訴 AI 該怎麼做。太長 → 注意力被稀釋。body 控制在 500 行以內 • L3 是工具箱 — 只在需要時打開。其中 scripts/ 最高效——執行而不讀入，零 token 成本
5.2 Frontmatter：觸發機制的全部來源
Frontmatter 只有兩個必需字段：name 和 description。但 description 的寫法至關重要：
This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
skill-creator 自己的 description 是這樣寫的：
description: Guide for creating effective skills. This skill should be used when
users want to create a new skill (or update an existing skill) that extends
Codex's capabilities with specialized knowledge, workflows, or tool integrations.它不只說"做什麼"（creating effective skills），還說"什麼時候用"（when users want to create a new skill or update an existing skill）。
關鍵規則：
• 把所有"when to use"信息放在 description 裏，不要放在 body 裏。body 是觸發後才加載的，那時候 Codex 已經決定用了，"什麼時候用"的信息已經遲了 • 不要在 frontmatter 中放 name和description以外的字段（license、allowed-tools、metadata除外）
一個好的 description 示例（docx 技能）：
"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
5.3 四種捆綁資源的本質區別
理解這四種資源的區別，是理解整個 skill 系統的關鍵：
Scripts（scripts/）
可執行代碼（Python/Bash 等），用於需要確定性可靠性或反覆重寫的任務。
• 什麼時候需要：同樣的代碼每次都要重新寫，或者需要確定性的可靠輸出 • 舉例： scripts/rotate_pdf.py用於 PDF 旋轉任務• 核心優勢：token 高效、確定性、可以執行而不讀入上下文窗口 • 注意：腳本有時仍需要被 Codex 讀取，用於修補或環境適配
References（references/）
文檔和參考材料，在需要時加載到上下文中，輔助 Codex 的思考過程。
• 什麼時候需要：Codex 在工作時需要參考的詳細文檔 • 舉例： references/finance.md（財務 schema）、references/api_docs.md（API 規範）、references/policies.md（公司政策）• 用途：數據庫 schema、API 文檔、領域知識、公司政策、詳細工作流指南 • 核心優勢：保持 SKILL.md 精煉，只在 Codex 判斷需要時才加載 • 最佳實踐：如果文件很大（>10k 詞），在 SKILL.md 中包含 grep 搜索模式 • 避免重複：信息應該只存在於 SKILL.md 或 references 文件中，不能兩邊都有。詳細信息優先放 references，SKILL.md 只保留核心流程指令和工作流指導
Assets（assets/）
不是用來加載到上下文中的文件，而是直接用在 Codex 產出物中的資源。
• 什麼時候需要：技能需要在最終輸出中使用的文件 • 舉例： assets/logo.png（品牌素材）、assets/slides.pptx（PPT 模板）、assets/frontend-template/（HTML/React 樣板）、assets/font.ttf（字體）• 用途：模板、圖片、圖標、樣板代碼、字體、示例文檔——這些會被複制或修改 • 核心優勢：將輸出資源與文檔分離，Codex 可以使用它們而無需讀入上下文
Agents 元數據（agents/openai.yaml）（推薦）
面向 UI 的元數據，不給 AI 讀，給產品前端讀：
• 包含 display_name、short_description、default_prompt等字段• 通過腳本 generate_openai_yaml.py確定性生成，而不是手寫• 更新 SKILL.md 後要檢查 agents/openai.yaml是否還匹配，過期了就重新生成• 詳細字段定義見 references/openai_yaml.md
5.4 漸進式披露的三種實戰模式
Skill-creator 給出了三種把內容拆分到 references 的具體模式：
Pattern 1：高層指南 + 參考文件
# PDF Processing
## Quick start
Extract text with pdfplumber:
[code example]
## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patternsCodex 只在需要時才加載 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
Pattern 2：按領域組織
多領域/多變體技能，按領域拆分避免加載無關內容：
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)用戶問銷售指標時，Codex 只讀 sales.md。
同樣適用於多框架/多變體場景：
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)Pattern 3：條件性細節
基礎功能直接展示，高級功能按需連結：
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)5.5 兩條重要的避坑指南
1. 避免深層嵌套引用 — 所有 reference 文件應該從 SKILL.md 直接連結，不要 A → B → C 式嵌套 2. 長文件加目錄 — 超過 100 行的 reference 文件要在頂部加 TOC，方便 Codex 預覽全貌
5.6 常見的層錯位
六、設計維度二：給 AI 多大自由度？
框架位置：第二層 — 維度二
知道了信息該放在哪裏、該怎麼約束，下一個問題是：AI 做什麼，腳本做什麼？
AI 非常擅長理解語義、生成文本、做創造性工作。但它不擅長精確格式控制、長度約束、命名規範——這些"脆弱操作"。
6.1 三個自由度檔位
Skill-creator 用一個自由度光譜來處理這種不均勻性（見第三章框架圖）：
Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
高自由度（文字指令）：多種方法都可行時，決策依賴上下文，用啓發式引導。
中自由度（偽代碼/帶參數的腳本）：有最佳實踐但允許變通，配置影響行為。
低自由度（具體腳本，少量參數）：操作脆弱容易出錯，一致性至關重要，必須遵循特定序列。
核心邏輯：
任務越脆弱（容易出錯） → 自由度越低 → 用腳本鎖死
任務越靈活（多種方案都對） → 自由度越高 → 用文字引導6.2 skill-creator 自身的自由度分配
| 低 | init_skill.py | |
| 低 | generate_openai_yaml.py | |
| 低 | quick_validate.py |
6.3 兩個方向的錯誤
錯誤 1：給脆弱任務太多自由度
# 錯誤
請生成一個 openai.yaml 文件，包含 display_name 和 short_description。
# 後果：short_description 可能超過 64 字符限制，大小寫可能不一致Skill-creator 的做法：用 generate_openai_yaml.py 腳本鎖死格式。AI 只提供參數值，腳本保證輸出合規。
錯誤 2：給創造性任務太多約束
# 錯誤
第一段必須以"昨天"開頭，第二段必須包含"本質上"，最後一段以"慢慢來"結尾。
# 後果：生成的文本像填詞遊戲Skill-creator 的做法：給結構比例（場景層 ≤30%，原理層 30-40%），但不鎖定具體用詞。
6.4 判斷標準
兩個問題：
1. 做錯了後果多嚴重？ — 越嚴重 → 越低自由度 2. 有多少種"正確"的做法？ — 越多 → 越高自由度
6.5 低自由度的實現：skill-creator 的三個腳本
理解了自由度光譜，就能理解 skill-creator 為什麼有三個腳本——它們就是"低自由度"的具體實現（腳本間的交互關係見第三章框架圖）。
init_skill.py（輸入保障，398 行）
初始化新技能目錄的腳手架工具，類似 create-react-app 之於 React 項目：
scripts/init_skill.py <skill-name> --path <output-directory> \
[--resources scripts,references,assets] [--examples] \
[--interface key=value]核心功能：
• 創建技能目錄 • 生成帶 TODO 佔位符的 SKILL.md 模板（TODO 是給 Codex 看的"填空題"） • 調用 generate_openai_yaml.py生成agents/openai.yaml（通過--interface key=value傳入 AI 生成的 display_name、short_description、default_prompt）• 可選創建 scripts/、references/、assets/子目錄• 可選添加示例文件（ --examples）• 內置 normalize_skill_name()自動把任意用戶輸入標準化為 hyphen-case
使用示例：
scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examplesgenerate_openai_yaml.py（格式保障，226 行）
專門負責生成和更新 agents/openai.yaml：
• 從 SKILL.md 的 frontmatter 讀取技能名 • 自動將 hyphen-case 轉為 Title Case（ my-cool-skill→My Cool Skill）• 內置縮寫詞典（GH、MCP、API 等保持大寫）和品牌詞典（openai → OpenAI） • 自動生成 25-64 字符的 short_description• 支持 --interface key=value覆蓋任意字段
scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=valuequick_validate.py（輸出保障，102 行）
技能創建後的"質檢"：
scripts/quick_validate.py <path/to/skill-folder>校驗內容：
• SKILL.md 是否存在 • YAML frontmatter 格式是否合法 • name：是否為 hyphen-case，≤ 64 字符，無連續/首尾連字符• description：是否存在，無尖括號，≤ 1024 字符• 只允許 name、description、license、allowed-tools、metadata這 5 個 frontmatter 鍵
6.6 質量保障鏈
三個腳本形成了一條工作流鏈路，夾住中間的創造性步驟：
init_skill.py（輸入保障）
命名標準化 + 目錄結構創建 + 模板生成
→ 確保起點正確
↓
AI 創造性編寫（高自由度）
→ SKILL.md 內容、references、自定義 scripts
↓
quick_validate.py（輸出保障）
frontmatter 格式 + 命名規範 + 長度約束校驗
→ 確保終點合規腳本是"執行而不讀入"的——零 token 成本。你可以把任意複雜的確定性邏輯封裝進腳本，而不用擔心它佔用上下文。這就是為什麼 skill-creator 把命名轉換（縮寫詞典、品牌詞典）、長度約束（25-64 字符）、格式校驗這些細碎但脆弱的操作全部交給了腳本代碼。
6.7 什麼該封裝成腳本？
每次執行結果必須一樣 → 腳本
涉及精確格式/長度約束 → 腳本
涉及命名規範轉換 → 腳本
需要校驗規則匹配 → 腳本
同樣的代碼每次都要重新寫 → 腳本
需要理解上下文 → 文字指令
有多種合理做法 → 文字指令
需要創造性判斷 → 文字指令腳本的定義是執行，雖然有時仍需要被 Codex 讀取（用於修補或環境適配），但大多數時候它們是"執行而不讀入"的。
七、落地：六步創建流程
框架位置：第三層
有了前面的原則和架構，skill-creator 最後給出了一個六步創建流程，把設計思想變成可執行的操作步驟（見第三章框架圖）。
7.0 命名規範
在開始之前，先確定命名：
• 只用小寫字母、數字和連字符；把用戶提供的名稱標準化為 hyphen-case（如 "Plan Mode" → plan-mode）• 名稱 ≤ 64 字符 • 優先用簡短的、動詞開頭的短語來描述動作 • 需要時用工具名做命名空間（如 gh-address-comments、linear-address-issue）• 技能文件夾名與技能名完全一致
7.1 Step 1：理解技能——用具體例子建立共識
Skip this step only when the skill's usage patterns are already clearly understood.
要創建一個有效的 skill，必須先清楚理解具體的使用例子。這些理解可以來自用戶提供的例子，也可以來自生成的、經用戶驗證的例子。
以構建 image-editor 技能為例，可以問用戶：
• "image-editor 技能應該支持什麼功能？編輯、旋轉，還有其他嗎？" • "能給一些使用這個技能的例子嗎？" • "我能想到用戶會說'去掉這張照片的紅眼'或'旋轉這張圖片'。還有其他使用方式嗎？" • "用戶會說什麼話來觸發這個技能？"
注意：不要一次問太多問題。先問最重要的，然後根據需要跟進。
完成標誌：對技能應該支持的功能有了清晰的認識。
7.2 Step 2：規劃可複用的技能內容
對每個具體例子做兩個分析：
1. 如果從零開始做這件事，需要什麼？ 2. 其中哪些會被反覆使用？
反覆使用的東西 → 封裝成 scripts/references/assets。
skill-creator 給了三個典型分析案例：
案例 1：pdf-editor 技能（用戶問"幫我旋轉這個 PDF"）
• 旋轉 PDF 每次都要重寫同樣的代碼 • → 封裝為 scripts/rotate_pdf.py
案例 2：frontend-webapp-builder 技能（用戶問"幫我做一個 todo app"或"做一個步數追蹤儀表盤"）
• 寫前端 webapp 每次都需要同樣的 HTML/React 樣板代碼 • → 封裝為 assets/hello-world/模板目錄
案例 3：big-query 技能（用戶問"今天有多少用戶登錄了？"）
• 查詢 BigQuery 每次都要重新發現表的 schema 和關係 • → 封裝為 references/schema.md
完成標誌：列出了所有要包含的可複用資源清單（scripts、references、assets）。
7.3 Step 3：初始化技能
When creating a new skill from scratch, always run the
init_skill.pyscript.
這裏用的是"always"——不是"建議"，是"總是"。原因：
• 腳本生成的目錄結構保證符合規範 • 模板中的 TODO 提醒確保不遺漏必需字段 • agents/openai.yaml的格式約束（字段長度、引號規則）靠手寫容易出錯
這是低自由度原則的直接應用：初始化是一個脆弱操作，用腳本消除出錯可能。
初始化後：
• 定製 SKILL.md 並根據需要添加資源 • 如果用了 --examples，替換或刪除佔位符文件
7.4 Step 4：編輯技能
這是最核心的步驟，分兩階段：
階段一：先實現可複用資源
從 Step 2 規劃的資源開始：實現 scripts/、references/、assets/ 文件。
注意：
• 這一步可能需要用戶輸入（比如 brand-guidelines技能需要用戶提供品牌素材）• 新增的腳本必須通過實際運行來測試，確保無 bug 且輸出符合預期 • 如果有很多類似的腳本，只需測試代表性樣本來建立信心 • 如果用了 --examples，刪除不需要的佔位符文件。只創建真正需要的資源目錄
階段二：更新 SKILL.md
Frontmatter 寫法：
---
name: skill-name
description: >-
描述技能做什麼 + 具體什麼時候用。
把所有 "when to use" 信息放這裏，不要放在 body 裏。
---Body 寫法：
寫給另一個 Codex 實例的操作指令。包含對 Codex 有幫助但不顯而易見的信息：程序性知識、領域細節、可複用資源的使用方式。
統一使用祈使語氣/不定式。
7.5 Step 5：校驗技能
scripts/quick_validate.py <path/to/skill-folder>校驗 YAML frontmatter 格式、必需字段、命名規則。不通過就修復後重新運行。
7.6 Step 6：迭代
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
迭代工作流：
1. 在真實任務上使用技能 2. 發現吃力或低效的地方 3. 找出 SKILL.md 或捆綁資源該如何更新 4. 實施變更並重新測試
好的 skill 不是一次寫成的。skill-creator 創建的 laotou-thought-style 技能，在第一次生成後就迭代了 openai.yaml 的 short_description 和 default_prompt——從泛泛的描述變為更精確的操作指令。
八、總結
回到最初的問題：怎麼寫出好的 skill？
回顧整個框架：首先明確Skill是給 AI 寫指令，而不是給人，Skill本質是：用最少的 token，在正確的層級，給 AI 最精準的約束，讓它在邊界內自由發揮。