Introduction to Agent Skills：建立、分享與除錯 Skill

前一天的 The AI-Native SDLC Playbook 把焦點放在怎麼讓 AI 開發流程留下可以審查的規格、計畫和驗證結果。接著打開 Introduction to Agent Skills，問題變得更貼近日常：那些每次都要重新交代給 Claude 的工作方法，能不能整理成一包，之後遇到符合的任務就自動套用？

課程資訊一覽

官方列出的學習內容，包含這幾個方向：

• 說明 Skill 是什麼、存放在哪裡，以及 Claude Code 如何將它們與請求進行比對。
• 從零建立一個具有有效 SKILL.md frontmatter 的技能，並驗證已載入。
• 撰寫有效的技能描述，並用 allowed-tools 限制或預先核准工具存取。
• 用 Progressive Disclosure 漸進式揭露、參考檔案和可執行腳本組織較大型的技能。
• 針對特定使用案例，在 Skill、CLAUDE.md、Subagent、Hooks、MCP 伺服器之間做選擇。
• 透過專案儲存庫、外掛程式、企業管理設定和自訂子代理分享技能。
• 用技能驗證工具和 claude --debug 診斷觸發、載入、優先順序衝突和執行時期問題。

官方的一句話是：技能讓你不必再重複自己，而是一次性教導 Claude；寫在一個地方，請求符合時 Claude Code 自動讀取。

1. 什麼是技能？

Skill 技能是一組指示與資源的資料夾，Claude Code 可以發現並使用它們來更準確地處理任務。每個技能都存放在一個 SKILL.md，frontmatter 至少要有 name 與 description，下方才是實際指示，例如檢查清單、格式偏好或工作流程。

最小的 SKILL.md 可以長這樣：

1
---
2
name: pr-review
3
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
4
---

Claude Code 會先拿 description 和目前的請求比對。當你要求審查 PR 時，它會把請求與可用技能的描述比較，啟用符合的技能；啟用時終端機會看到它載入。這讓同一份工作方法可以在不同專案裡重複使用，也讓技能本身不用在每次對話一開始就佔住 context。

Skill 的存放位置，先用「誰要用」來判斷：

這也說明了 Skill、CLAUDE.md 和 slash command 的差異：

判斷原則很簡單：團隊每次都要遵守的專案規範放在 CLAUDE.md；只有特定任務才需要的專業知識，整理成 Skill；需要人主動點名才執行的固定入口，才做成 slash command。

2. 建立您的第一個技能

課程用一個 PR description 技能示範從零建立 Skill。先建目錄，再放入 SKILL.md：

1
mkdir -p ~/.claude/skills/pr-description

完整範例是：

1
---
2
name: pr-description
3
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
4
---
5

6
When writing a PR description:
7

8
1. Run `git diff main...HEAD` to see all changes on this branch
9
2. Write a description following this format:
10

11
## What
12
One sentence explaining what this PR does.
13

14
## Why
15
Brief context on why this change is needed
16

17
## Changes
18
- Bullet points of specific changes made
19
- Group related changes together
20
- Mention any files deleted or renamed

這裡的 name 用來識別技能，description 告訴 Claude 何時該用它；第二組破折號後的內容則是技能啟用後要遵循的指示。描述要具體到足以完成配對，單寫「協助處理文件」會讓觸發條件太模糊。

建立後要重新啟動工作階段，讓 Claude Code 重新掃描技能。可以在可用技能清單確認它是否出現，再在分支上製造一些變更，測試「為我的變更撰寫 PR 描述」是否能正確觸發。

課程把技能匹配的運作方式整理成三步：啟動時掃描技能的名稱和描述；請求進來時做語意比對；配對成功後載入完整的 SKILL.md，讓目前任務使用它。描述裡最好同時寫清楚技能做什麼，以及哪些說法也應該觸發它。

技能的優先順序則依設定層級排列：

企業層級可以用技能強制標準，同時仍允許個人自訂。遇到同名衝突時，優先使用較高層級的版本；若要避免誤用，技能名稱應該描述清楚，不要只叫 review 這種過於寬泛的名字。

3. 配置與多檔案技能

Skill 的 frontmatter 可以放幾個核心欄位。name 和 description 是必要欄位，allowed-tools 與 model 則依使用情境選用：

allowed-tools 可以縮小技能工作時會碰到的工具範圍，也可以預先核准特定操作。課程同時提到 disallowed-tools，用來從 Claude 可用的工具集中移除指定工具：

1
---
2
name: codebase-onboarding
3
description: Helps new developers understand the system works.
4
allowed-tools: Read, Grep, Glob, Bash
5
model: sonnet
6
---

這裡有一個容易混淆的邊界：allowed-tools 是技能啟用期間的預先核准，不會把 Claude 永久限制在這些工具裡；如果技能指示需要編輯檔案或寫入內容，仍會依正常權限設定處理。單獨列出 Bash 會放得很寬，課程建議信任程度較高時才這樣做，也可以縮小成類似 Bash(git status *) 的模式。

Progressive Disclosure 漸進式揭露

所有內容都塞進一個 2,000 行的 SKILL.md，很快就會讓 context 變得擁擠，也讓技能難以維護。Progressive Disclosure 的做法，是只把啟用時一定需要的規則留在 SKILL.md，其他資料拆到技能目錄的子檔案：

SKILL.md 只要告訴 Claude 什麼時候讀取這些檔案即可。技能需要時再把參考資料帶進 context，能保留完整能力，也不必讓每次觸發都載入所有內容。經過測試的腳本則直接執行，輸出結果通常比把大段腳本內容貼進指示更穩定。

4. Skills 與其他 Claude Code 功能的比較

Claude Code 的自訂能力很多，放錯位置會讓設定變得難以理解。可以先用「何時觸發」和「要不要隔離 context」來分工：

Model Context Protocol（MCP） 和 Skill 放在不同層次：MCP 提供 Claude 可以呼叫的外部工具與資料來源；Skill 提供 Claude 如何處理某類任務的工作方法。兩者可以一起使用，例如 Skill 指示 Claude 依照團隊流程查資料，再透過 MCP 取得實際內容。

課程給的典型組合是：CLAUDE.md 放始終生效的專案標準；Skills 放按需載入的任務知識；Hooks 放事件觸發的自動化；Subagents 負責隔離與委派；MCP 伺服器提供外部工具和服務。

5. 分享技能

Skill 能不能被別人使用，取決於你把它放在哪一層。課程整理了三種分享方式：

.claude 目錄可以同時放代理、Hooks、Skills 和設定，全部受版本控制。企業也能透過 strictKnownMarketplaces 限制外掛程式只能從核准來源安裝：

1
"strictKnownMarketplaces": [
2
  { "source": "github", "repo": "acme-corp/approved-plugins" },
3
  { "source": "npm", "package": "@acme-corp/compliance-plugins" }
4
]

Skills 與子代理

這裡有一個很容易漏掉的設定邊界：子代理從全新的 context 開始，不會自動看到你的 Skills。內建代理，例如 Explorer、Plan、Verify，也無法直接存取技能；自訂子代理則可以在 frontmatter 的 skills 欄位明確列出要載入的技能。

1
---
2
name: frontend-security-accessibility-reviewer
3
description: "Use this agent when you need to review frontend code for accessibility..."
4
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
5
model: sonnet
6
color: blue
7
skills: accessibility-audit, performance-check
8
---

技能會在自訂子代理啟動時載入，載入的是整份 Skill，不只是名稱。因此，若要讓子代理使用某個技能，先確認技能真的存在於 .claude/skills，再在代理設定中明確列出來。

6. 疑難排解技能

當 Skill 沒有如預期工作，可以先把問題分成四類：沒有觸發、無法載入、發生衝突，或載入後執行失敗。課程建議先使用技能驗證工具做結構檢查，再處理細節：

1
agent skills verifier

快速檢查時，可以依序問自己：描述是否真的說清楚「做什麼」與「什麼時候用」？目錄與檔名是否符合規定？同名技能是否在更高層級？腳本依賴和執行權限是否完整？這幾個問題通常能先把範圍縮小。

課程最後留下的理解很實用：最好的 Skill 往往來自真實痛點。當你發現自己一直重複向 Claude 解釋同一件事，就有一個工作方法值得被整理出來。

小結

這堂課把 Skill 從「一段比較長的 Prompt」拆成一個可以被發現、配對、載入、分享和驗證的工作單位，也把基礎觀念和資料結構接了起來。description 決定它什麼時候出場，SKILL.md 放核心規則，多檔案結構負責把細節按需帶進來，分享層級則決定這套方法只服務自己、整個 repo，還是整間公司。

這堂課最有價值的地方，是把「這個工作到底該包成 MCP、Skill 還是 Plugin？」這個一開始就會冒出的問題拆開回答。要固定規範就寫進 CLAUDE.md，要隔離工作就交給 Subagent，要保證事件發生時執行就使用 Hooks；需要外部工具與資料來源時再接 MCP，需要分發一整套能力時則考慮 Plugin。Claude Code 官方 Skills 文件也把這些邊界和 Skill 的實際設定寫得很清楚。

上完這堂課，我有三點想補充說明：

1. Commands vs Skills

第一堂只用一句話帶到 slash commands，Claude Code 的官方 Skills 文件則把兩者的關係寫得更清楚：自訂 commands 已經合併進 skills，但舊的 command 檔案仍然可以繼續使用。

從使用感受來說，Commands 顧名思義就是一個指令。我通常會把原本可能貼在記事本裡、需要時再複製出來的一段命令或 Prompt 收進 .claude/commands/；下次直接用 /name 叫用，不必再翻它存在哪裡。簡單說，它就是一個很小的 SOP，足以把一段固定操作收起來，複雜度還不到需要拆成 Skill 的程度。

所以差別先從結構看：Commands 是單一檔案，Skills 是可以容納完整工作方法的資料夾。兩者都用 /name 叫用；官方文件對新工作建議使用 Skills，因為它能裝進支援檔案，也能控制 Claude 是否可以自動載入或由使用者手動叫用。

兩個叫用控制欄位很值得記下來：disable-model-invocation: true 會阻止 Claude 自動載入，保留 /name 讓使用者手動觸發；user-invocable: false 則把 Skill 從 / 選單隱藏，讓它只在相關時由 Claude 使用。前者適合 deploy、commit 這種有副作用、需要人決定時機的工作，後者適合背景知識型 Skill。

2. 使用 skill-creator 建立 Skill

上面的手動範例適合用來理解 SKILL.md 的基本結構；實際要建立或改善 Skill 時，可以直接叫用 Anthropic 官方 plugin 裡的 skill-creator。它會協助整理 Skill 的意圖、觸發時機、輸出格式和成功標準，再產生幾個測試 Prompt，實際比較使用 Skill 與沒有使用 Skill 的結果，依回饋持續迭代。

這個流程讓 Skill 從「寫出一份看起來合理的 SKILL.md」多走幾步：先把需求說清楚，再用真實請求測試觸發和輸出品質，最後才決定要不要優化 description。因此，建立 Skill 時我會把課程的手動建立當成結構入門，把 skill-creator 當成實際製作與驗證的工作方法。

3. 反向封裝 Skill

這也讓我想到以前寫過的 Session is Skill。我把那個做法叫做反向封裝：當你和 agent 在同一個對話完成一件事時，最有價值的不只最後產出的檔案，還有剛剛走過的行為。趁著脈絡還在，立刻把這套行為封裝成 Skill，下次遇到同類任務就能直接重用。