Claude Code 的 Custom Skills（自訂技能）是一項強大的擴充機制，讓你可以將常用的工作流程、程式碼規範、專案知識打包成可重複使用的技能模組。透過建立 SKILL.md 檔案，你可以教 Claude 學會新技能，無論是自動化部署流程、統一程式碼風格，還是產生專案文件，都能透過一個簡單的 /skill-name 指令完成。本篇教學將帶你從零開始建立、設定、分享你的專屬自訂技能。

Custom Skills 是 Claude Code 的技能擴充系統，遵循 Agent Skills 開放標準。每個 Skill 本質上就是一個資料夾，裡面包含一份 SKILL.md 檔案作為進入點，搭配可選的範本、範例、腳本等輔助檔案。當你或 Claude 觸發一個 Skill 時，Claude 會讀取 SKILL.md 的內容作為指引，按照其中的步驟執行任務。

Skills 的核心特色包含：

• 靈活觸發：你可以用 /skill-name 手動觸發，Claude 也能在對話中自動判斷何時該使用
• 自動發現：Claude 會根據 Skill 的描述，自動在適當的情境中載入使用
• 支援輔助檔案：可以包含範本、範例、腳本和參考文件
• Subagent 執行：可以在隔離的子代理環境中執行，不影響主對話
• 工具權限控制：可以指定 Skill 執行時允許使用的工具，減少權限確認提示

Skills 的存放位置決定了它的適用範圍和優先順序。當多個層級存在相同名稱的 Skill 時，較高優先順序的會覆蓋較低的。

Plugin 層級的 Skills 使用 plugin-name:skill-name 的命名空間，因此不會與其他層級的 Skill 衝突。如果你同時在 .claude/commands/ 和 .claude/skills/ 下有相同名稱的檔案，Skill 會優先於 Command。

在 monorepo 架構的專案中，Claude Code 會自動發現子目錄中的 .claude/skills/。例如，當你正在編輯 packages/frontend/src/auth.ts 時，Claude 也會搜尋 packages/frontend/.claude/skills/ 下的 Skills，讓每個子套件可以擁有各自的技能設定。

每個 Skill 都需要一份 SKILL.md 檔案，由兩個部分組成：YAML frontmatter（用 --- 包裹的設定區域）告訴 Claude 何時使用這個 Skill，以及 Markdown 內容區域包含 Claude 執行時遵循的指示。

一個完整的 Skill 目錄結構如下：

my-skill/ ├── SKILL.md # 主要指示檔（必要） ├── template.md # 範本，供 Claude 填寫 ├── examples/ │ └── sample.md # 範例輸出 └── scripts/ └── validate.sh # Claude 可執行的腳本

以下是一個教 Claude 用視覺圖表解釋程式碼的 Skill 範例：

--- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" --- When explaining code, always include: 1. Start with an analogy: Compare the code to something from everyday life 2. Draw a diagram: Use ASCII art to show the flow, structure, or relationships 3. Walk through the code: Explain step-by-step what happens 4. Highlight a gotcha: What's a common mistake or misconception? Keep explanations conversational. For complex concepts, use multiple analogies.

在這個範例中，name 欄位定義了 /explain-code 斜線指令，description 幫助 Claude 判斷何時自動載入這個技能。當你問「這段程式碼怎麼運作的？」時，Claude 會自動套用此技能的指引。

SKILL.md 的 YAML frontmatter 提供了豐富的設定選項，所有欄位都是可選的，但建議至少填寫 description 讓 Claude 知道何時使用。

讓我們一步步建立一個實用的 Skill。以下範例建立一個「程式碼解說器」，放在個人目錄中，所有專案都可以使用。

mkdir -p ~/.claude/skills/explain-code

在 ~/.claude/skills/explain-code/ 目錄下建立 SKILL.md：

--- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" --- When explaining code, always include: 1. Start with an analogy: Compare the code to something from everyday life 2. Draw a diagram: Use ASCII art to show the flow, structure, or relationships 3. Walk through the code: Explain step-by-step what happens 4. Highlight a gotcha: What's a common mistake or misconception? Keep explanations conversational. For complex concepts, use multiple analogies.

你可以用兩種方式測試：

• 讓 Claude 自動觸發：在對話中問「這段程式碼怎麼運作的？」，Claude 會根據 description 判斷是否啟用
• 手動觸發：直接輸入 /explain-code src/auth/login.ts

透過 disable-model-invocation 和 user-invocable 兩個欄位，你可以精確控制 Skill 的觸發權限。這在不同場景下非常重要——例如部署腳本你不希望 Claude 自動執行，而背景知識類的 Skill 則不需要出現在使用者的指令選單中。

以下是一個僅允許手動觸發的部署 Skill 範例：

--- name: deploy description: Deploy the application to production disable-model-invocation: true --- Deploy $ARGUMENTS to production: 1. Run the test suite 2. Build the application 3. Push to the deployment target 4. Verify the deployment succeeded

Skills 支援參數傳遞，讓同一個 Skill 可以處理不同的輸入。你可以使用 $ARGUMENTS 取得所有參數，或用 $ARGUMENTS[N]（等同 $N）取得特定位置的參數。

--- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Fix GitHub issue $ARGUMENTS following our coding standards. 1. Read the issue description 2. Understand the requirements 3. Implement the fix 4. Write tests 5. Create a commit

執行 /fix-issue 123 時，$ARGUMENTS 會被替換為 123。如果需要多個參數，可以使用位置索引：

--- name: migrate-component description: Migrate a component from one framework to another --- Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests.

執行 /migrate-component SearchBar React Vue 時，$0 = SearchBar、$1 = React、$2 = Vue。

除了參數替換，Skills 還支援以下動態變數：

Skills 支援一個強大的前處理機制：使用 !`command` 語法，在 Skill 內容送給 Claude 之前先執行 Shell 指令，並將輸出結果注入到提示詞中。這讓 Claude 能夠接收到即時的、動態的資料。

--- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) --- Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` Your task Summarize this pull request...

執行流程是：每個 !`command` 會先被執行，輸出結果直接取代佔位符，Claude 只會看到最終渲染後的完整內容。這是預處理機制，不是 Claude 執行的指令。

對於多行指令，可以使用 ! 開頭的程式碼區塊：

 Environment ! node --version npm --version git status --short 

在 frontmatter 中加入 context: fork，可以讓 Skill 在隔離的子代理環境中執行。Skill 的內容會成為驅動子代理的提示詞，子代理不會存取你的對話歷史，適合需要獨立執行的大型任務。

agent 欄位指定使用哪種子代理：內建選項有 Explore（唯讀探索）、Plan（架構規劃）、general-purpose（通用），也可以使用 .claude/agents/ 下的自訂子代理。

--- name: deep-research description: Research a topic thoroughly context: fork agent: Explore --- Research $ARGUMENTS thoroughly: 1. Find relevant files using Glob and Grep 2. Read and analyze the code 3. Summarize findings with specific file references

Skill 目錄可以包含多個輔助檔案，讓 SKILL.md 保持精簡，Claude 只在需要時才載入詳細的參考資料。建議將 SKILL.md 控制在 500 行以內，把詳細的 API 文件、範例集合等移到獨立檔案。

my-skill/ ├── SKILL.md # 概覽與導航（必要） ├── reference.md # 詳細 API 文件（需要時載入） ├── examples.md # 使用範例（需要時載入） └── scripts/ └── helper.py # 工具腳本（執行用，不會載入 Context）

在 SKILL.md 中引用這些檔案，讓 Claude 知道每個檔案的用途和載入時機：

 Additional resources - For complete API details, see [reference.md](reference.md) - For usage examples, see [examples.md](examples.md)

使用 allowed-tools 欄位可以限制 Claude 在 Skill 啟用時能使用的工具。這不僅提升安全性，也能減少每次使用工具時的權限確認提示，讓工作流程更順暢。

--- name: safe-reader description: Read files without making changes allowed-tools: Read Grep Glob --- 只能讀取檔案，不能修改任何內容。

你也可以使用更精細的工具匹配模式，例如 Bash(docker *) 只允許執行 docker 相關的指令，Bash(npm test) 只允許執行測試。

Claude Code 內建了多個實用的 Bundled Skills，這些技能隨 Claude Code 一起安裝，每個 session 都可以直接使用。與內建指令不同，Bundled Skills 是基於提示詞的——它們會給 Claude 一份詳細的執行劇本，讓 Claude 使用工具來完成工作。

建立一個自動套用團隊程式碼規範的 Skill，放在專案目錄中與團隊共享：

--- name: code-review description: Review code following our team's coding standards. Use when reviewing pull requests or checking code quality. allowed-tools: Read Grep Glob paths: src//*.ts, src//*.tsx --- Review the code following our team standards: Naming Conventions - Components: PascalCase - Functions/variables: camelCase - Constants: UPPER_SNAKE_CASE - Files: kebab-case.ts Code Quality Checks 1. No any types - use proper TypeScript types 2. All functions must have JSDoc comments 3. Error handling must use custom error classes 4. No console.log in production code 5. Maximum function length: 50 lines

Skills 可以綁定並執行任何語言的腳本，一個強大的模式是產生互動式 HTML 檔案。以下是一個專案結構視覺化器的範例：

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo or understanding project structure.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure.

 Usage

Run the visualization script from your project root:

bash
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .


This creates codebase-map.html and opens it in your browser.

這個模式可以應用在各種視覺化場景：依賴關係圖、測試覆蓋率報告、API 文件、資料庫 Schema 視覺化等。腳本負責繁重的工作，Claude 負責調度和執行。

根據分享對象的不同，可以選擇不同的方式分發 Skills：

最簡單的方式就是將 Skill 目錄加入 Git 版本控制：

# 建立專案 Skill mkdir -p .claude/skills/my-skill

編輯 SKILL.md

vim .claude/skills/my-skill/SKILL.md

提交到版本控制

git add .claude/skills/ git commit -m “Add my-skill for team use”

你可以透過 Claude Code 的權限系統來控制 Claude 能使用哪些 Skills：

• 停用所有 Skills：在 /permissions 的拒絕規則中加入 Skill
• 允許特定 Skills：使用 Skill(commit) 精確匹配，或 Skill(review-pr *) 前綴匹配
• 拒絕特定 Skills：在拒絕規則中加入 Skill(deploy *)
• 隱藏個別 Skills：在 frontmatter 加入 disable-model-invocation: true，從 Claude 的 Context 中完全移除

1. 精心設計 Description：Description 是 Claude 判斷是否使用 Skill 的唯一依據，把最關鍵的使用場景放在開頭，例如「Fix GitHub issues. Use when you see an issue number」
2. 區分任務型與參考型：任務型 Skill（部署、提交）加上 disable-model-invocation: true，參考型 Skill（規範、知識庫）加上 user-invocable: false
3. 善用輔助檔案：大型參考文件、API 規格、範例集合移到獨立檔案，在 SKILL.md 中引用
4. 限制工具權限：用 allowed-tools 明確指定 Skill 需要的工具，避免不必要的權限提示
5. 使用 paths 限制啟用範圍：避免 Skill 在不相關的檔案上觸發，例如只在 .tsx 檔案上啟用 React 規範
6. 善用動態 Context 注入：用 !`command` 語法注入即時資料，讓 Skill 更智慧
7. 保持 SKILL.md 精簡：控制在 500 行以內，把詳細資料移到輔助檔案

Custom Skills 是 Claude Code 最強大的擴充機制之一。透過一份簡單的 SKILL.md 檔案，你可以將任何重複性工作流程、團隊規範、或專案知識打包成可重複使用的技能。從最簡單的程式碼規範 Skill 開始，逐步嘗試動態 Context 注入、Subagent 執行等進階功能，你會發現 Claude Code 的潛力遠超想像。