Claude Code 技能：打造會自動啟用的自訂擴充功能

該怎麼為 Claude Code 打造自訂技能？ 在 ~/.claude/skills/<name>/（個人層級）或 .claude/skills/<name>/（專案層級）底下建立一個 SKILL.md 檔案，YAML frontmatter 裡填入 name、description 與 allowed-tools 欄位，後面接著以 markdown 撰寫的專業知識內容。Claude 會針對 description 進行 LLM 推理，在任務相符時自動啟用該技能。以 git 共享的專案技能，隊友這端完全不需要任何設定。

連續三次工作階段，我都把同一份安全檢查清單貼進 Claude Code。清單裡是團隊獨有的漏洞樣式：我們 API 設計特有的 IDOR 檢查、認證流程的工作階段處理規則、PII 欄位的資料外洩規則。每一次，Claude 都套用得無可挑剔。也每一次，都得靠我自己記得去貼。

當您發現自己一再重複解釋同一段脈絡，那一刻就是該打造技能的時候。

TL;DR

技能是由模型自行呼叫的擴充功能——Claude 會依照上下文自動找到並套用，不必您明白下令 ¹。技能可不可靠，關鍵在 description 欄位：Claude 是用 LLM 推理（而非關鍵字比對）來決定何時啟用每個技能 ¹。跨工作階段都通用的領域知識（安全樣式、程式碼風格、商業規則）適合做成技能。一次性的任務就別做技能了——改用斜線指令。

先決條件： 熟悉 Claude Code 的擴充機制。至於技能、指令與子代理之間的比較，請參閱指南中的 Skills 章節。

什麼時候該打造技能

不是每一段重複用到的提示詞都值得做成技能。判斷框架如下：

技能承載的是 Claude 隨時備妥的知識，斜線指令承載的則是 由您明白觸發的動作。在兩者之間猶豫時，不妨自問：「這件事該讓 Claude 自動套用，還是該由我決定何時執行？」

一個常見的誤區： 為一週才做一次的事情打造技能。我曾寫過一個 git-rebase-helper 技能，結果只要提示詞沾到 git 就會觸發——rebase、合併、cherry-pick，連 git status 都不放過。它的 description 寫得太寬鬆，在八成根本用不到它的工作階段裡污染上下文，還得跟其他技能搶那 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 寫好

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

隊友一拉取，技能就自動到手。不必安裝，也不必設定。用 git 散布，是在團隊裡統一專業知識最有效的辦法。

共享技能的幾項準則： - 專案技能專注在領域專業知識（商業規則、架構樣式） - 個人技能留給工作流程偏好（格式化、提交風格） - 在 SKILL.md 開頭用註解寫明這個技能為何存在 - 像看待其他程式碼一樣，在 PR 裡審查技能的改動

重點整理

• 當您發現自己一再重複解釋脈絡，就該打造技能。 同一份檢查清單貼了三次，它就該變成技能。
• description 欄位決定一切。 Claude 靠 LLM 推理，拿您的請求去比對描述 ¹。花在描述上的時間，該多過花在技能內文上的時間。
• 用 allowed-tools 收住副作用。 唯讀技能就該限制在 Read、Grep、Glob。
• 透過 git 共享專案技能。 零設定的團隊知識散布 ¹。
• 別過度抽象化。 為每個瑣碎的小樣式都建一個技能，既帶來維護負擔，又得搶上下文預算。只為那些穩定、可重複使用、值得維護的專業知識打造技能。

常見問題

什麼是 Claude Code 技能？

技能是以 markdown 檔案形式存放、由模型自行呼叫的擴充功能，Claude 會依上下文自動找出並套用。與需要您明白觸發的斜線指令不同，技能是在 Claude 的 LLM 推理判定目前任務與技能描述相符時自動啟用。它們編碼領域專業知識——安全樣式、程式碼風格規則、商業邏輯——而且跨工作階段留存，您不必每次重新解釋脈絡。

我要怎麼為 Claude Code 建立自訂技能？

個人技能請在 ~/.claude/skills/<name>/ 底下建立目錄，專案層級技能則放在 .claude/skills/<name>/。目錄內建立一個 SKILL.md 檔案，先寫 YAML frontmatter（含 name、description，以及選填的 allowed-tools），再接上 markdown 內文，寫出 Claude 該套用的專業知識。description 欄位至關重要——Claude 會針對它進行 LLM 推理，決定何時啟用技能。完整的逐步走查請見上文的教學。

Claude Code 技能與斜線指令有什麼差別？

技能依上下文自動啟用——由 Claude 用 LLM 推理對照技能描述，判斷它們是否相關。斜線指令則是由使用者呼叫的動作，得由您輸入 /command-name 明白觸發。若希望 Claude 隨時握有這些知識（領域專業知識、品質標準），就打造技能；若希望由自己決定何時執行（部署指令碼、一次性的工作流程），就打造斜線指令。

Claude Code 技能可以呼叫其他工具嗎？

可以，但哪些工具能用由您透過 frontmatter 的 allowed-tools 欄位掌控。像程式碼審查器這種唯讀技能，就該限制在 Read, Grep, Glob，以免造成非預期的副作用。若省略 allowed-tools，技能便能使用 Claude 所能存取的任何工具。技能也可以在 frontmatter 中定義自己的掛鉤，這些掛鉤只在技能執行期間生效。

為什麼我的 Claude Code 技能不會啟用？

最常見的原因，是 description 欄位寫得含糊或過於寬鬆。Claude 是用 LLM 推理——而非關鍵字比對——判斷技能與您目前的任務是否相關。如果描述只寫「helps with code」，Claude 無從分辨它跟其他任何寫程式的任務有何不同。請把描述寫具體：指名確切的問題類型、觸發情境，以及使用者自然會打出來的動詞。另外也可以在工作階段中執行 /context，看看技能是不是因為 2% 的上下文預算上限而被排除。當眾多技能爭搶空間，總有一些會被捨去。

Claude Code 技能存放在哪裡？又該如何共享？

技能有四個存放位置，作用範圍依序放大：個人（~/.claude/skills/<name>/SKILL.md）、專案（.claude/skills/<name>/SKILL.md）、外掛，以及企業層級（受管設定）。個人技能適用於您的所有專案。專案技能透過 git 共享——隊友一拉取就自動取得，零設定。所有技能描述共用上下文視窗 2% 的預算，因此技能較多時，描述請盡量精簡。

參考資料