為 Claude Code 打造自訂技能：完整教學指南

連續三次工作階段，我都將同一份安全檢查清單貼進 Claude Code。這份清單包含我們團隊特有的弱點模式——針對我們 API 設計的 IDOR 檢查、我們驗證流程的 session 處理規則、我們 PII 欄位的資料洩露規則。每一次，Claude 都完美地套用了這些規則。每一次，我都得記著要貼上去。

當您發現自己反覆解釋同樣的上下文時，就是該建構技能的時刻。

TL;DR

技能是模型調用的擴充功能——Claude 會根據上下文自動發現並套用它們，無需您明確呼叫¹。可靠技能的關鍵在於 description 欄位：Claude 使用 LLM 推理（而非關鍵字匹配）來決定何時啟動每個技能¹。為跨工作階段適用的領域專業知識建構技能（安全模式、程式碼風格、商業規則）。不要為一次性任務建構技能——改用斜線命令。

先決條件：熟悉 Claude Code 的擴充系統。關於技能、命令和子代理之間的比較，請參閱指南的技能章節。

何時該建構技能

並非每個重複的提示都值得做成技能。以下是決策框架：

技能是Claude 隨時可用的知識。斜線命令是您明確觸發的操作。如果您在兩者之間猶豫，請自問：「Claude 應該自動套用這個，還是應該由我決定何時執行？」

常見錯誤：為每週只做一次的事情建構技能。我曾建構了一個 git-rebase-helper 技能，它在任何與 git 相關的提示上都會啟動——rebase、merge、cherry-pick，甚至 git status。描述太廣泛了，它在 80% 不需要的工作階段中污染了上下文，並且與其他技能競爭 2% 的上下文預算¹。解決方法是刪除該技能，改用斜線命令：在真正需要時使用 /rebase。技能應該編碼穩定的領域專業知識，而非偶爾的工作流程。

教學：建構程式碼審查技能

步驟 1：建立目錄

技能可以存放在四個位置，從最廣到最窄的範圍¹：

在本教學中，我們將建立一個個人技能：

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

步驟 2：撰寫含 frontmatter 的 SKILL.md

每個技能都需要一個 SKILL.md 檔案，包含兩個部分：YAML frontmatter（位於 --- 標記之間）告訴 Claude 何時使用該技能，以及 markdown 內容包含 Claude 在技能被調用時遵循的指令¹。

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

請注意 allowed-tools: Read, Grep, Glob——這將技能限制為唯讀操作。程式碼審查器可以檢視檔案但無法修改它們。工具限制能防止技能產生非預期的副作用。

除了 name、description 和 allowed-tools 之外，其他實用的 frontmatter 欄位¹：

官方文件中有一個注意事項：context: fork「僅對具有明確指令且受益於隔離的技能有意義」¹。將它用於分析類技能（程式碼審查、安全稽核），在這些場景中您需要乾淨的上下文，而非用於應融入主要對話的知識類技能。

步驟 3：新增輔助資源

技能可以參照同一目錄中的其他檔案¹：

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

從 SKILL.md 中使用相對連結參照它們：

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

當技能啟動時，Claude 會使用標準的檔案讀取工具按需讀取這些檔案¹。將 SKILL.md 保持在 500 行以內，並將詳細的參考資料移至輔助檔案中³——較短的技能檔案可減少上下文注入的開銷，讓 Claude 專注於當前任務。

步驟 4：測試啟動

技能會在您下次啟動 Claude Code 工作階段時生效。測試方式：

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

使用以下兩種方法之一驗證技能是否已載入¹：

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

如果技能未啟動，問題幾乎總是出在 description 欄位。請參閱步驟 5。

步驟 5：關鍵步驟——撰寫描述

description 欄位是您技能中最重要的一行。以下是其底層運作方式：在工作階段開始時，Claude Code 會擷取每個技能的 name 和 description 並注入 Claude 的上下文中。當您傳送訊息時，Claude 使用語言模型推理——不是正規表達式、不是關鍵字匹配、不是嵌入相似度——來判斷是否有任何技能相關。官方文件指出：「Claude 會將您的任務與技能描述進行匹配，以決定哪些是相關的。如果描述模糊或重疊，Claude 可能會載入錯誤的技能——或遺漏本應有幫助的技能」¹。

對 Claude Code 原始碼的獨立分析確認了這個機制：技能描述被注入系統提示的 available_skills 區段中，模型使用標準的語言理解能力在調用時選擇相關技能⁴。基於 LLM 的匹配機制對您撰寫描述的方式有重要影響。

不好的描述：

description: Helps with code

Claude 不知道何時該啟動這個技能。「Helps with code」匹配一切又不匹配任何東西——而且因為匹配是 LLM 推理，模糊的描述會造成不可預測的啟動行為。

較好的描述：

description: Review code for bugs and issues

太模糊。什麼類型的 bug？什麼類型的問題？Claude 何時該使用這個而非其內建的分析功能？

有效的描述：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

這個有效的描述之所以有效，是因為它包含： - 它做什麼：審查程式碼中的特定問題類型 - 何時使用：檢視變更、PR、品質分析 - 觸發詞彙：review、audit、check——使用者自然會輸入的詞彙

需要了解的一個限制：所有技能描述共享一個上下文預算，「以上下文視窗的 2% 動態調整，後備值為 16,000 個字元」¹。如果您有很多技能，請讓每個描述簡潔——冗長的描述會與其他技能競爭有限的空間。您可以透過 SLASH_COMMAND_TOOL_CHAR_BUDGET 環境變數覆寫預算²，但更好的做法是撰寫更短、更精確的描述。

測試不同的描述。開始一個新的工作階段，要求 Claude 審查程式碼，然後檢查技能是否啟動。如果沒有，新增更多觸發詞彙。如果在不該啟動時啟動了，讓描述更具體。

步驟 6：根據使用情況迭代

使用一週後，您會發現： - 技能應該檢查但尚未包含的模式——將它們加入 SKILL.md - 在不相關的任務上誤啟動——收緊描述，或新增 disable-model-invocation: true 並要求明確的 /code-reviewer 調用 - 缺少上下文——新增輔助資源檔案 - 工具限制太嚴或太鬆——調整 allowed-tools

技能是活的文件。第一個版本永遠不會是最終版本。

進階：技能作為提示詞庫

除了單一用途的技能，目錄結構也可作為組織化的提示詞庫：

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

每個技能編碼了您團隊專業知識的不同面向。它們共同形成一個知識庫，Claude 會根據上下文自動從中擷取。初級開發者無需主動詢問就能獲得資深級別的指導。

關於技能數量的注意事項：更多技能意味著更多描述競爭上下文預算¹。如果您發現技能未啟動，執行 /context 檢查是否有任何技能被排除。優先選擇少量描述完善的技能，而非大量模糊的技能。

與團隊共享技能

個人技能（~/.claude/skills/）僅屬於您。用於個人偏好、實驗性模式，或特定於您工作流程的專業知識。

專案技能（儲存庫根目錄的 .claude/skills/）透過 git 共享¹：

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

當團隊成員 pull 時，他們就會自動獲得該技能。無需安裝，無需設定。Git 分發是標準化團隊專業知識最有效的方式。

共享技能的指導方針： - 專案技能專注於領域專業知識（商業規則、架構模式） - 個人技能用於工作流程偏好（格式化、commit 風格） - 在 SKILL.md 頂部的註解中說明技能存在的原因 - 像審查其他程式碼一樣在 PR 中審查技能變更

重點摘要

• 當您發現自己反覆解釋上下文時，就建構技能。如果您貼了同一份清單三次，它就應該成為技能。
• 描述欄位決定一切。Claude 使用 LLM 推理將您的請求與描述進行匹配¹。在描述上投入的時間應比技能內容更多。
• 使用 allowed-tools 約束副作用。唯讀技能應限制為 Read、Grep、Glob。
• 透過 git 共享專案技能。零設定的團隊知識分發¹。
• 不要過度抽象。為每個微模式建構技能會產生維護負擔，而且會競爭上下文預算。為穩定、可重用、且值得維護的專業知識建構技能。

參考資料