AI Skill Builder
使用共用的 SKILL.md 格式與 Anthropic 的方法論來建構 Agent Skills：最小的可攜式核心在每個指定的目標中都能運作，再加上明確的執行時期適配器。可攜式性是一個經過測試的相容性聲明，而非格式風格。
references/sources.md 引用了 Claude Code、Codex 與 Qwen Code 的主機文件；此處未測試其他主機，因此請驗證您所針對的主機（步驟 1）。
此方法論刻意要求在 Markdown 主體內使用一致的語意化 XML 區域。這是一項減少複雜操作性指令歧義的品質政策，受到當前 Anthropic 提示指導方針的支持，並通過步驟 4 中的前瞻測試進行檢查。這並非可攜式 Agent Skills 規格的解析器要求、授權邊界，也非宣稱 XML 本身能防止提示注入。
主要方法論來源：「The Complete Guide to Building Skills for Claude」(Anthropic，2026 年 1 月)
- PDF：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- 擷取文字：
references/ai-skill-builder-guide.md
可攜式格式來源：https://agentskills.io/specification
快速開始
若要從頭建立技能，請遵循以下 4 階段流程。
若要改進現有技能，請閱讀 references/refining-skills.md。
若要驗證結構，請執行 scripts/audit-skill.sh。
呼叫方式： 要求 ai-skill-builder；主機可能以 /ai-skill-builder、$ai-skill-builder 或透過其技能選擇器提供此功能。
P0 需求
此方法論產生的每個技能都必須滿足全部十三項。在稽核與審查中請引用其 ID。
- SKILL-REQ001-discover-target-runtimes. 在編寫之前，先確認確切的產品、版本、呼叫模式、安裝根目錄、信任邊界與檔案系統語意。
- SKILL-REQ002-separate-standard-from-extensions. 將 Agent Skills 規格、執行時期擴充與專案慣例分開至不同的欄位。切勿將 Claude、Codex、Copilot、Gemini 或框架特定的欄位描述為通用。
- SKILL-REQ003-use-valid-portable-core. 將必要的
SKILL.md放在一個目錄中，該目錄的名稱需與其可攜式name相符；包含一個具體的description，說明該技能的功能與使用時機。僅在必要時使用標準的選擇性欄位。 - SKILL-REQ004-use-semantic-xml-regions. 將每個主要操作性區域包裹在 Markdown 主體內一致且具描述性的 XML 標籤中，例如
<purpose>、<requirements>、<workflow>、<examples>、<output_contract>。將 Markdown 保留在這些區域內，並將字面原始碼置於圍欄程式碼區塊中。此強制性方法論規則旨在達成最高品質的指令分離；並非 Agent Skills 解析器要求或安全性邊界。scripts/audit-skill.sh在遇到無區域、標籤不平衡或巢狀錯誤、或區域外出現##標題時，會判定失敗。 - SKILL-REQ005-design-progressive-disclosure. 保持啟用描述精確，主要工作流程簡潔。將真正條件式的細節移至集中且直接連結的參考文件中；將可重複使用的自動化程式碼保留在腳本中，並將輸出材料保留在 assets 中。
- SKILL-REQ006-preserve-operational-context. 每個參考文件或腳本都必須說明其使用時機、接受的輸入、回傳或更改的內容，以及失敗如何回報。避免過深的參考鏈。
- SKILL-REQ007-make-invocation-correct. 測試自動啟用與明確呼叫。當執行時期支援參數時，測試空參數、位置參數、命名參數、帶引號參數、Unicode 參數、無效參數與大量輸入。不要假設另一個執行時期實作相同的替換語法。
- SKILL-REQ008-minimize-tool-authority. 將技能與捆綁的腳本視為可執行的相依套件。請求最低必要的權限，驗證輸入，在實際可行時保留核准提示，且切勿將提示分隔符描述為提示注入防禦措施。
- SKILL-REQ009-validate-every-harness. 在各支援的 harness 中驗證發現、載入、參考文件、腳本、引數、符號連結、重複解析、更新與移除。通過一個解析器的測試並不能證明跨執行時期的相容性。
- SKILL-REQ010-preserve-user-state. 安裝與解除安裝必須擁有確切產生的路徑、保留手動編輯、支援多個設定的技能根目錄，並僅移除安裝程式擁有的連結或檔案。
- SKILL-REQ011-measure-context-and-runtime-cost. 記錄發現元資料大小、載入的指令大小、條件式參考成本、腳本時間/記憶體/IO 以及重複載入。除非目標執行時期將其視為規範性指標，否則應將行數與 token 目標視為啟發式標準。
- SKILL-REQ012-forward-test-real-tasks. 使用實際的正向、負向、模糊與對抗性提示。檢查任務成果，而不僅是技能是否出現在清單中。
- SKILL-REQ013-separate-authoring-from-execution. 分類任務是更改技能、使用技能產出成品或結果，或是根據證據評估技能。除非明確的編寫決策接受並將其一般化，否則執行時期輸入、產生的輸出、範例與 dogfood 觀察結果不應成為技能指令。
區域名稱應跟隨任務而非統一分類：工作流程使用 <workflow>，參考技能可能使用 <decision_guide>，多模式技能使用 <routing>，嚴格的結果合約使用 <output_contract>，內聯參考材料使用 <reference>，指向捆綁檔案與來源的指標使用 <resources>。標籤必須一致、具描述性、平衡，且巢狀深度不超過任務所需。標準 vs 擴充矩陣、聲明確效與每個主機的驗證收據位於 references/portability-and-claim-audit.md。
運作方式
來自 Anthropic 指南的四階段方法論。每個階段都有一個完成的定義：進入下一階段前必須滿足的條件。
| 階段 | 活動 | 完成的定義 |
|---|---|---|
| 1：規劃與設計 | 定義目標主機、使用案例、類別、成功標準 | 標準是可衡量的，且類別已選定 |
| 2：實作 | 建立資料夾、撰寫 SKILL.md、加入資源 | audit-skill.sh 報告無失敗 |
| 3：測試 | 觸發測試、功能測試、效能測試、相容性測試、前瞻測試 | 每個命名的主機都通過測試並有驗證收據；記錄基準線 |
| 4：發布 | 打包、撰寫文件、發布 | 從乾淨的根目錄驗證安裝成功 |
階段 1 涵蓋以下步驟 1-2；階段 2-4 對應步驟 3-5。
每個階段需要多長時間取決於由誰或什麼來執行，因此此技能不提供實際時間估計，您建立的技能也不應提供。
技能建立工作流程
步驟 1：探索需求
首先研究該領域—使用主機的網路工具來驗證當前的實務做法，然後再撰寫指令。過時的指導比沒有指導更糟：Agent 會自信地遵循它。
保留所有來源：記錄每個諮詢過的 URL，並註明它確認了什麼。未標明來源的指導無法驗證或更新。
關於研究策略、來源品質標準以及所需的「來源」章節格式：references/research.md
- 分類請求：編寫（更改技能）、執行（使用技能產出結果）或評估（根據證據判斷技能）。在使用任務內容作為設計輸入之前，先命名成品與變更邊界（SKILL-REQ013）。
- 識別問題與目標使用者
- 識別每個目標主機與版本、其發現根目錄、呼叫形式與重新載入行為。將未知標示為未知，而非猜測。在建立平行套件之前，先檢查現有的技能根目錄與專案指導方針。
- 定義 2-3 個具體使用案例
- 設定可衡量的成功標準（節省時間、減少錯誤、提升品質）
- 選擇技能類別：
| 類別 | 輸入 → 輸出 | 範例 |
|---|---|---|
| 1：文件與資產建立 | 資料/規格 → 文件、程式碼、報告 | API 測試產生器、會議記錄摘要器 |
| 2：工作流程自動化 | 任務參數 → 完成的多步驟流程 | 部署管道、程式碼審查工作流程 |
| 3：MCP 增強 | MCP 工具輸出 → 更聰明的編排 | 智慧檔案搜尋、BigQuery 助手 |
關於深入的類別指導：references/categories.md
關於互動式探索問題：references/discovery.md
步驟 2：設計結構
使用漸進式揭露設計——3 個載入層級：
| 層級 | 何時載入 | 目標長度 | 內容 |
|---|---|---|---|
| 1：中繼資料 | 始終載入（約 100 字） | name + description | 觸發條件 |
| 2：SKILL.md 主體 | 技能觸發時 | 低於 5,000 字（理想低於 2,000 字） | 核心工作流程 + 指標 |
| 3：references/ 檔案 | 根據需要 | 無限制 | 深入細節、架構、範例 |
關於漸進式揭露的撰寫技巧與成功指標：references/best-practices.md
步驟 3：實作
關鍵規則：
- ✅ 檔案必須命名為
SKILL.md（非 README.md） - ✅ 資料夾名稱必須使用kebab-case——無空格、無大寫（
my-skill而非My Skill） - ✅ YAML frontmatter 必須包含
name與description；在metadata下放置版本 - ✅ Description 必須包含特定的觸發詞句——使用者的說法來啟用技能
- ✅ Description 必須少於 1024 個字元（硬性限制——超過的描述會被截斷）
- ✅ frontmatter 欄位中不得有 XML 角括號（
<或>）——這是 Anthropic 技能指南中的主機限制，而非 YAML 規則；主體不受影響 - ✅ 主體：每個主要區段都必須放置在使用獨立行且平衡且具描述性的 XML 區域內（
<purpose>、<requirements>、<workflow>、<examples>、<output_contract>），Markdown 在內部，字面原始碼在圍欄程式碼區塊中（SKILL-REQ004）。H1 標題可留在外部。 - ❌ 技能資料夾內不得有 README.md——所有文件都放在 SKILL.md 或 references/ 中（例外：位於 GitHub 儲存庫根目錄的 README.md，在技能資料夾之外，則沒問題。）
- ❌ 資料夾名稱中不得有空格或底線（
my_skill→my-skill）
Frontmatter：必要欄位：
---
name: your-skill-name # 僅限 kebab-case；無空格、大寫或底線
description: 功能說明。當使用者要求「特定詞句」、「另一個詞句」時使用。
# 必須包含：功能說明 + 使用時機（觸發條件）
# 少於 1024 個字元。無 XML 角括號。
# 請勿以「claude」或「anthropic」開頭（保留命名空間）。
---
關於每個選擇性欄位（license、compatibility、allowed-tools、metadata）及主機可攜性備註：references/best-practices.md
定位語言（例如「測試產生速度提升 87%」）應放在儲存庫的 README 中，絕對不能放在 description 中。請參閱 references/best-practices.md。
資料夾結構（附註解的 Claude Code 獨立範例：references/best-practices.md 中的「Folder Structure Patterns」章節）：
| 目錄 | 載入至上下文？ | 用途 |
|---|---|---|
references/ | 是，根據需要 | 架構、API 文件、政策、工作流程指南 |
references/examples/ | 根據需要 | 使用者複製並改編的工作範例程式碼 |
scripts/ | 否（直接執行） | 驗證器、產生器、工具程式 |
assets/ | 否（用於輸出） | 技能貼入輸出中的圖片、字型、HTML 範本 |
注意：外掛技能（位於 plugin-name/skills/）可能會將 examples/ 放在頂層——這是外掛開發慣例。對於獨立的 ~/.claude/skills/ 技能，請將範例放在 references/ 內。
若要產生新的技能：bash scripts/scaffold-skill.sh my-skill-name（設定 SKILLS_DIR 以指向另一個主機的根目錄）
若要從範本開始：複製 references/examples/SKILL-template.md
步驟 4：測試
五種測試方法（依序執行）：
- 觸發測試——驗證 Agent 是否在預期的詞句上啟用，且不在不相關的要求上啟用
- 功能測試——驗證技能的核心工作流程是否為已知輸入產生正確輸出
- 效能測試——測量相較於基準線的改進（節省時間、減少錯誤、一致性）
- 相容性測試——在每個命名的主機與版本上驗證發現、明確呼叫、參考載入、腳本執行以及重複/名稱解析。為每個主機啟動一個乾淨的工作階段，在存在主機自己的驗證器時執行該驗證器（Codex 附帶
skill-creator/scripts/quick_validate.py），測試安裝程式重新執行、多個根目錄、符號連結目標、修改過的使用者檔案以及解除安裝，並為每個主機記錄驗證收據（references/portability-and-claim-audit.md）。 - 前瞻測試——實際的正向、負向、模糊與對抗性提示；判斷任務成果，而不僅是技能是否出現在清單中，並檢查它是否不會過度觸發鄰近的任務（SKILL-REQ012）
偵錯觸發問題：
詢問 Agent：「您何時會使用 [技能名稱] 技能？」
Agent 應回覆其 description。根據缺少或過於模糊的內容進行調整。
修正觸發不足：加入更具體的觸發詞句與相關技術術語。
修正過度觸發：在 description 中加入負面觸發詞：
description: 處理 PDF 法律文件以進行合約審閱。用於「審閱此合約」、「分析法律文件」、「擷取合約條款」。請勿用於一般 PDF 檢視、圖片擷取或非法務文件（請改用 doc-converter 技能）。
關於涵蓋所有四種失敗模式的完整診斷與修正指南：references/troubleshooting.md
若要驗證結構：
bash scripts/audit-skill.sh /path/to/YOUR-SKILL
...
[此處截斷以利翻譯]