原文：Han Lee – Claude Agent Skills: A First Principles Deep Dive
在大型語言模型（LLM）的快速演進中，Anthropic 的 Claude 系列以強調安全性與可控性著稱。而在 Claude 的整個架構中，「Agent Skills 系統」是最值得技術人員深入研究的一環。它並非傳統意義上的外掛（plugin）或工具呼叫，而是一種以提示（prompt）為核心的元工具機制，能讓模型在不同任務中切換「思考模式」，達到專業化與模組化的效果。
本文將從第一性原理出發，完整解析 Claude 的 Agent Skills 架構與運作邏輯，並以實際案例（如 skill-creator 與 internal-comms）說明技能的建立、載入、與決策過程。
什麼是 Claude Agent Skills
Skills 是什麼？
它不是函式呼叫、不是伺服器、也不是可執行程式。Skill 是一個結構化的提示模板，在被呼叫時會把 領域專屬的指示 注入到對話上下文中，並可同時改變執行上下文（如：開啟哪些工具權限、切換模型）。
Skill 的存放位置
Skill 以資料夾為單位，內含 SKILL.md（核心提示）、以及可選的 scripts/、references/、assets/。它們不會被硬寫進系統提示（system prompt），而是透過一個名為 Skill（大寫 S） 的「元工具（meta-tool）」動態管理。
誰做決策？
不是外部程式碼在做意圖分類，也沒有 embeddings 或關鍵字比對。是 LLM 本身在閱讀 Skill 列表的文字描述後，用語言理解自行決定是否要用哪個 Skill。這一切都發生在模型的前向推論之中。
Skills 與傳統工具的差異：
重點心智模型：
工具會「做事」，Skills會「讓模型準備好、以專家方法來做事」。Skills 調整的是模型的行為策略與權限環境。
從實例看 Skill 的構成：以 skill-creator 為例
關鍵洞見：
Skill = 提示模板 + 對話上下文注入 + 執行上下文修改 +（可選）資料與腳本
Skill 會被 Claude Code 從多處載入：使用者設定（~/.config/claude/skills/）、專案資料夾（.claude/skills/）、外掛提供的 skills、以及內建 skills。以 Claude Desktop，也可直接上傳自訂 Skill。
漸進式揭露（Progressive Disclosure）是核心設計哲學
- 先只曝光前言（frontmatter）：名稱與描述足夠讓 LLM 決定是否選用。
- 選中後再展開 SKILL.md：提供完整但聚焦的指示。
- 需要時才載入腳本與參考資料：把冗長內容拆到外部檔案，避免上下文暴漲。
🔍 沒有 /references 或 /assets 目錄，顯示該技能以提示為主體、腳本為輔。
SKILL.md：前言區（Frontmatter）與提示內容（Content）
SKILL.md 由兩部分組成：
Frontmatter
- name（必填）：Skill 名稱，也是 Skill 工具的
command。 - description（必填）：最關鍵訊號，LLM 靠它判斷何時使用此 Skill。建議用動作導向語言（「當使用者想要…時使用」）。
- license（選填）：授權說明。
- allowed-tools（選填）：預先開放的工具白名單。可用萬用字元或限定子命令。務必最小化權限。
- 範例：
allowed-tools: "Read,Write,Bash,Glob,Grep,Edit"（skill-creator）allowed-tools: "Bash(git status:*),Bash(git diff:*),Read,Grep"- ✅ 僅列必要工具；❌ 不要貪心全開，破壞安全模型。
- 範例：
- model（選填）：可指定特定模型，預設
inherit（沿用當前會話）。 - version（選填）：純記錄用途。
- disable-model-invocation（選填）：若
true，不會被自動列入給 LLM 的可用清單，只能用手動指令（如/skill-name）啟動。 - mode（選填）：若
true，此 Skill 被視為「模式指令」，會在清單上方以「Mode Commands」區塊凸顯（如debug-mode、expert-mode）。
關於 when_to_use（未文件化、可能已棄用或尚未公開）
程式碼中可見 when_to_use 被附加到 description 後方以加強語意，但 官方未文件化，行為可能變動。實務建議：把使用時機直接寫進 description，避免依賴未公布欄位。
SKILL.md提示內容
實務守則
- 盡量小於 5,000 字，避免淹沒上下文。
- 用 祈使句（「分析…」、「執行…」），不要用「你應該…」。
- 把冗長清單、範例、模板拆到外部檔案，用
{baseDir}引用路徑，不要寫死絕對路徑。- ✅
Read {baseDir}/config.json - ❌
Read /home/user/project/config.json
- ✅
與資源打包：scripts/／references/／assets
專案結構建議：
my-skill/ ├── SKILL.md ├── scripts/ # 可執行腳本（Python/Bash） ├── references/ # 文字型參考資料（會讀入上下文） └── assets/ # 模板與二進位資源（僅路徑引用，不讀入）
scripts/：交給 Bash 工具執行的自動化腳本（如init_skill.py）。適合多步驟、決定性邏輯或資料處理。references/：會被 Read 載入上下文的文件（規範、樣式指南、Schema 等）。assets/：只用路徑引用、不讀入上下文（HTML 模板、圖片、字型）。避免浪費 token。
常見設計樣式（Patterns）與進階工作流
Pattern 1：Script Automation（腳本自動化）
使用場景：需要多個指令或確定性邏輯的複雜操作。
這種模式將計算任務卸載到scripts/目錄中的 Python 或 Bash 腳本中。技能提示符號指示 Claude 執行腳本並處理其輸出。
SKILL.md 例：
Run scripts/analyzer.py on the target directory:
`python {baseDir}/scripts/analyzer.py --path "$USER_PATH" --output report.json`
Parse the generated `report.json` and present findings.所需工具：
allowed-tools: "Bash(python {baseDir}/scripts/*:*), Read, Write"Pattern 2：Read – Process – Write
情境：檔案轉換、格式清理、報表輸出。
最簡單的模式－讀取輸入，依照指令轉換，寫入輸出。適用於格式轉換、資料清理或報告產生。
SKILL.md 例：
## Processing Workflow 1. Read input file using Read tool 2. Parse content according to format 3. Transform data following specifications 4. Write output using Write tool 5. Report completion with summary
所需工具：
allowed-tools: "Read, Write"
Pattern 3：Search – Analyze – Report
情境：程式碼安全檢查、巨量資料模式搜尋。
使用 Grep 在程式碼庫中搜尋模式，讀取符合的檔案以取得上下文，分析結果，並產生結構化報告。或者，在企業數據儲存中搜尋數據，分析檢索到的數據以獲取信息，並產生結構化報告。
SKILL.md 例：
## Analysis Process 1. Use Grep to find relevant code patterns 2. Read each matched file 3. Analyze for vulnerabilities 4. Generate structured report
所需工具：
allowed-tools: "Grep, Read"
Pattern 4：Command Chain Execution
情境：具有依賴關係的多步驟操作。
執行一系列命令，其中每一步都依賴前一步的成功。這在類似 CI/CD 的工作流程中很常見。
SKILL.md 例：
Execute analysis pipeline: npm install && npm run lint && npm test Report results from each stage.
所需工具：
allowed-tools: "Bash(npm install:*), Bash(npm run:*), Read"
進階工作流
Wizard-style 多步驟嚮導
使用場景：每步驟向使用者確認後再前進。
SKILL.md 例：
## Workflow ### Step 1: Initial Setup 1. Ask user for project type 2. Validate prerequisites exist 3. Create base configuration Wait for user confirmation before proceeding. ### Step 2: Configuration 1. Present configuration options 2. Ask user to choose settings 3. Generate config file Wait for user confirmation before proceeding. ### Step 3: Initialization 1. Run initialization scripts 2. Verify setup successful 3. Report results
Template-based 產生
使用場景：從 assets/ 讀模板、填入欄位、輸出成品。
SKILL.md 例：
## Generation Process
1. Read template from {baseDir}/assets/template.html
2. Parse user requirements
3. Fill template placeholders:
- → user-provided name
- → generated summary
- → current date
4. Write filled template to output file
5. Report completionIterative Refinement
使用場景：先廣掃後深挖，再產出修正建議與工時估計。
SKILL.md 例：
## Iterative Analysis ### Pass 1: Broad Scan 1. Search entire codebase for patterns 2. Identify high-level issues 3. Categorize findings ### Pass 2: Deep Analysis For each high-level issue: 1. Read full file context 2. Analyze root cause 3. Determine severity ### Pass 3: Recommendation For each finding: 1. Research best practices 2. Generate specific fix 3. Estimate effort Present final report with all findings and recommendations.
Context Aggregation
使用場景：聚合多來源（README、package、git、grep）成整體視圖。
SKILL.md 例：
## Context Gathering 1. Read project README.md for overview 2. Analyze package.json for dependencies 3. Grep codebase for specific patterns 4. Check git history for recent changes 5. Synthesize findings into coherent summary
到這裡，我們已了解 Skills 是如何被設計、撰寫與打包的：
它不是外部程式，而是能讓 Claude 暫時「切換人格」的提示容器。
由於原文資料太多可以分享我們將分成上下兩篇來介紹，在下一篇中，我們將深入探討 Skills 在內部如何被載入、解析與執行——包括 Skill 工具（meta-tool）的 API 結構、兩段訊息注入設計，以及完整的執行生命週期，對原文有興趣也可前往原文觀看，我們下次見~~
