Claude Skill 教學｜如何建立自己的 Skill？有哪些 Claude Code 技巧？
如果你已經用 Claude Code 一段時間，每次開新專案，Claude 都像個剛入職的新人，什麼都得從頭說明。你得告訴它「我們團隊用的是這套 Coding Style」、「Deploy 流程是這樣跑的」、「這個 API 要這樣串」。講一次還好，講十次、二十次之後就會開始懷疑到底我花錢是在用 AI 還是在當 AI 的助理？
你應該已經知道 CLAUDE.md 這個檔案的用途。把專案的慣例和規則寫在 CLAUDE.md 裡，Claude Code 啟動時就會自動讀取，省去每次重複解釋的麻煩。CLAUDE.md 常被拿來放專案指引，雖然 Claude Code 也支援使用者層級的 ~/.claude/CLAUDE.md 可以跨專案共用，但不管放哪一層，指引一長就會遇到難維護、而且啟動時全部載入的問題，我還遇過 Claude Code 提醒我再繼續下去效能會變差⋯⋯。
重點是，CLAUDE.md 的內容會在專案啟動的時候就全部載入，不管當前的任務用不用得到。
有沒有什麼方法，可以把「專業知識」打包成獨立的模組，讓 Agent 自己判斷什麼時候該用、只載入需要的部分、而且可以跨專案重複使用？嘿嘿，有的，就是 Anthropic 在 2025 年推出的 Skills 功能。
什麼是 Skills？
根據 Anthropic 的官方定義，Skills 是這樣的東西：
Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as 'onboarding guides' for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.
翻成白話文就是： Skills 是一種打包好的「專業技能包」，可以把 Claude 從一個什麼好像都略懂的通才，變成某個領域的專家 。
想像你開了一間小吃店，你是一位什麼料理都會做、都能做但可能都做的不太好吃的廚師。有天我經過你的小吃店，我看你骨骼精奇，是一位百年難得一見的練武奇才，覺得維護世界的和平就要靠你了，所以決定給你一本「台南小吃完全手冊」，裡面寫著擔仔麵的湯頭怎麼熬、肉燥要用什麼部位的豬肉、蝦仁要去哪個市場買最新鮮、還有那個獨門醬油膏的調配比例。看完這本秘笈之後，你就能做出道地的府城味了。
Skills 就是這本「武功秘笈」。Skills 能提供的東西很多，包括：
- 專業工作流程： 多步驟的作業程序，例如「怎麼做 Code Review」、「怎麼處理 PR」
- 工具整合： 跟特定檔案格式或 API 互動的方法，例如「怎麼處理 PDF」
- 領域專業知識： 你們公司或團隊特有的商業邏輯和慣例
- 資源： 腳本、參考文件、範本等執行任務時需要的素材
五分鐘速成：你只需要知道這些
Skills 是什麼？ 一個資料夾 + 一個 SKILL.md 檔案，裡面寫著「什麼時候該用這個技能」和「怎麼用」。
為什麼要用？ 解決三個痛點：
- 每次都要重複說明：不用再每個專案都從頭教 Claude 你們的規範
- CLAUDE.md 太肥：專案指引越寫越長，啟動時全部載入很浪費
- 知識難以重用：這個專案寫過的規則，下個專案又要重寫一遍
怎麼用？三步驟
第一步，建立資料夾和檔案：
mkdir my-first-skill
cd my-first-skill
第二步，建立 SKILL.md：
---
name: my-first-skill
description: 告訴 Claude 什麼時候該用這個 Skill
---
# 我的第一個 Skill
這裡寫 Claude 需要遵循的規則和步驟...
第三步，放到正確位置：
~/.claude/skills/my-first-skill/- 個人層級，所有專案都能用你的專案/.claude/skills/my-first-skill/- 專案層級，只有這個專案能用
完成！Claude 會自動判斷什麼時候該載入這個 Skill。
關鍵概念：Progressive Disclosure（漸進式揭露）
想像你去圖書館借書：
- Metadata（100 tokens） = 書的封面和簡介 → Claude 用這個判斷「要不要借這本書」
- Instructions（5000 tokens） = 書的目錄和重點章節 → Claude 覺得有用才會翻開來讀
- Resources（無限制） = 書裡的附錄、參考資料 → Claude 需要時才會查閱
這樣設計的好處：不會每次對話都把所有知識塞進去，用多少拿多少，省 token 又有效率。
好了，速成講完了，下面是完整教學 👇
Skills 長什麼樣子？
一個 Skills 的基本結構很簡單，至少需要一個 SKILL.md 檔案：
skill-name/
└── SKILL.md # 必要的
這個 SKILL.md 檔案開頭必須包含一段 YAML frontmatter：
---
name: skill-name
description: A description of what this skill does and when to use it.
---
根據 agentskills.io 的規格，name 欄位有一些規則要遵守：
-
長度在 1 到 64 個字元之間
-
只能用小寫字母、數字和 -
-
不能以 - 開頭或結尾，也不能有連續的 -
-
必須與目錄名稱一致，待會我們實作的時候就會看到
description 欄位也有限制：
-
長度在 1 到 1024 個字元之間，所以這裡不是寫執行細節的地方
-
應該描述這個 Skills 做什麼、什麼時候該用
frontmatter 之後的內容才是給 Agent 看的指令內容。你可以在裡面寫任何你想讓 Agent 知道的東西，例如操作步驟、注意事項、範例用法等等。如果你的 Skills 比較複雜，需要額外的腳本或參考資料，可以建立這樣的目錄結構：
skill-name/
├── SKILL.md # 必要的
├── scripts/ # 可執行的程式碼（Python、Bash、JavaScript）
├── references/ # 額外的參考文件
└── assets/ # 靜態資源（範本、圖片、資料檔）
根據 Agent Skills 規格，這三個目錄都是 Optional directories，也就是要加不加都可以。這些目錄名稱是規格建議的標準結構，讓不同的 Skills 有一致的組織方式。Claude 是透過你在 SKILL.md 裡的引用來發現這些檔案的，所以你需要在 SKILL.md 裡明確引用，Claude 才會知道它們的存在。
Progressive Disclosure是什麼？
這裡要講一個我認為 Skills 設計得最漂亮的地方，叫做 Progressive Disclosure（漸進式揭露）。
這概念有點像用 Google Maps 導航。當輸入目的地之後，它不會一次把整條路線的每個細節都唸出來，而是先給一個大方向，例如「往北走，大約 10 分鐘後右轉」。等快到路口了，才會接著說「前方 50 公尺右轉，進入衡陽路」。如果中途想找加油站或停車場，它才會載入附近的資訊，Skills 的運作方式就是這樣。
根據 Anthropic 部落格的說明，Skills 的內容分成三層：
第一層是 Metadata ，大概只有 100 個 tokens 左右。這層只包含 name 和 description 兩個欄位。當 Claude Code 啟動的時候，會預載所有已安裝 Skills 的 Metadata，用來判斷「這個任務跟哪些 Skills 有關」。
第二層是 Instructions ，就是 SKILL.md 的主體內容。依 Agent Skills 規格建議，這層最好控制在 5000 個 tokens 以內。當 Claude 判斷某個 Skills 跟當前任務相關，才會把這層載入。
第三層是 Resources ，就是 scripts/、references/、assets/ 這些目錄裡的檔案。這些內容是按需載入的，Claude 需要用到哪個檔案才會去讀取。
這樣設計的好處在於只要把 Skills 正確地分層，由於檔案和資源是按需讀取的，理論上可以在一個 Skills 裡打包無限量的知識。在 Blog 文章裡有提到一句：
因為 context window 是有限的，如果每次對話都把所有知識塞進去，就算是像是有百萬 context window 的 Gemini，撐爆也只是早晚的問題。Progressive Disclosure 的設計讓 Claude 可以「用多少、拿多少」，不浪費 context 又能在需要的時候取得足夠完整的資訊。
Skills 跟其他機制有什麼不同？
如果你用過 Claude Code 一段時間，應該會發現有好幾種方法可以「客製化」Claude 的行為。Skills 跟其他機制有什麼差別？什麼時候該用哪一種？我整理一個比較表：
| 機制 | 觸發方式 | 持久性 | 內容類型 | 載入時機 | 可包含程式碼 | 適用場景 |
|---|---|---|---|---|---|---|
| Skills | Claude 自動判斷何時啟用（根據 description） | 跨對話、跨專案可用 | 程序性知識 + 可執行腳本 | 動態載入（Progressive Disclosure） | 是 | 重複性專業工作流程、需要 Claude 主動判斷的情境 |
| Custom Commands | 使用者輸入 /command（也可引導 Claude 代為呼叫） | 專案或個人層級 | Prompt 範本 | 使用者觸發時載入 | 否（單一 prompt 檔） | 固定格式的重複操作、使用者明確知道要做什麼的情境 |
| MCP | 工具呼叫 | 啟動時載入 | 外部服務連接 | 按需呼叫 | 是（server 端） | 連接外部 API、資料庫、檔案系統 |
| Subagents | Claude 自動委派或手動啟動 | 任務期間 | 獨立 AI 實例 | 需要時建立 | 是 | 需要獨立 context、平行處理、專門化任務 |
我來解釋一下這些機制的差異。
Custom Commands機制
Custom Commands（也就是斜線命令）需要你手動輸入 /say-something 才會觸發。根據官方文件的說法，斜線命令是「A Markdown file containing a prompt that Claude executes when invoked」，也就是說它只能包含 prompt 範本，不會有程式腳本或其他資源。你可以把它想成一種「巨集」，預先寫好一段指令，之後一鍵展開執行。它適合用在你已經知道要做什麼的情況，例如每次 commit 前都要跑同一套檢查流程，像我就寫了好幾個這樣的指令，像是 /remove-comment 用來移除不必要的註解，或是 /sanitize-ai 用來清理 AI 產生的「機味」文字。
Skills機制
但 Skills 不一樣，Agent 會自動根據當時的對話內容或情境判斷要不要啟用某個 Skill。假設你裝了一個翻譯用的 Skill，當我們跟 Agent 說「幫我把這段英文翻成中文」，Agent 會自己判斷「喔，這個任務跟翻譯有關，我應該要使用那個翻譯的 Skill」，不需要我們特別去觸發。
Skills 沒有像 Slash Commands 那樣「輸入固定 /xxx 就必定執行」的觸發機制，它主要由模型依 description 做相似度判斷來決定要不要啟用。官方文件說 Skills 是「model-invoked」，也就是由 Agent 自己決定什麼時候用。如果你需要手動觸發的功能，那應該用 Custom Commands 而不是 Skills。不過你可以在對話中明確提到 Skills 的功能來引導 Agent，例如說「用我們的翻譯規則把這段翻成中文」，讓 Agent 更容易判斷該啟用哪個 Skill。
MCP機制
MCP（Model Context Protocol）也有類似的自動判斷機制，但兩者運作的層次不同。Skills 提供的是「知識」，Agent 載入後會根據這些知識來「指導自己」的行為。MCP 提供的是「工具」，Agent 會呼叫這些工具來執行具體操作。
再回到剛才翻譯的例子，如果我們要做翻譯，Skills 會告訴 Agent「翻譯的時候要用什麼語氣、專有名詞怎麼處理、哪些詞不要翻」，而 MCP 則是讓 Agent 可以存取你的術語表資料庫、或是呼叫 DeepL API 來輔助翻譯。一個是腦袋裡的知識，一個是手上的工具。
MCP 是用來連接外部服務的。如果我們需要請 Agent 存取資料庫、呼叫某個 API、或是操作檔案，就可以使用 MCP。根據官方定義，MCP「enables Claude Code plugins to integrate with external services and APIs by providing structured tool access」。
是說每次有新東西出現，總是就會有些先知會丟出「取代論」的說法，最近社群有些討論說 Skills 會取代 MCP，但就我看並不會，因為這兩個解決的是不同層次的問題。Skills 是給 Agent「腦袋」，MCP 是給 Agent「手腳」。你可以同時用 Skills 教 Agent 怎麼做翻譯，又用 MCP 讓它能存取術語庫，兩者之間是互補而不是互斥或互相取代的關係。
至於 Subagents，根據官方說明，它是「autonomous subprocesses that handle complex, multi-step tasks independently」。當一個任務太複雜、需要獨立的 context 空間、或是可以平行處理的時候，Claude 會啟動 Subagents 來幫忙。
簡單來說：
- 想讓 Agent 自己判斷什麼時候用什麼專業知識？ 用 Skills
- 想手動觸發固定的操作流程？ 用 Custom Commands
- 想連接外部服務？ 用 MCP
- 想平行處理複雜任務？ 讓 Claude 用 Subagents
這四個機制不是互斥的，可以同時運作。舉個例子：使用 Custom Command /review-pr 觸發 Code Review 流程，Claude 會載入 Code Review 的 Skills 來取得審查標準，同時透過 MCP 連接 GitHub API 拉取 PR 內容，如果 PR 改動的檔案很多，Claude 可能還會啟動 Subagents 平行審查不同的檔案。四個機制各司其職然後一起完成任務，看到 AI 很忙的樣子，看起來不是很酷嗎 :)
實際案例對比
為了讓大家更清楚什麼時候該用哪個機制，我整理了幾個常見的實際案例：
案例 1：處理 API 文件
- Skills 方式：建立
api-doc-skill，教 Agent「怎麼寫符合公司風格的 API 文件」、「必須包含哪些章節」、「範例程式碼的格式」等知識。當你說「幫我寫這個 endpoint 的文件」，Agent 會自動載入這個 Skill 並按照規範產出。 - Custom Commands 方式：建立
/gen-api-doc指令，每次都執行固定的文件生成流程。你必須手動輸入/gen-api-doc來觸發，適合用在文件格式非常固定、不需要 Agent 判斷的情境。 - MCP 方式：連接 Swagger/OpenAPI 工具來讀取現有的 API 定義，或是連接文件管理系統來儲存產生的文件。
在這個案例中，三者可以搭配使用：用 MCP 讀取 API 定義，用 Skills 指導文件撰寫風格，最後可以設定一個 Custom Command 把整個流程串起來。
案例 2：Code Review
- Skills 方式：建立
code-review-checklistSkill，裡面包含你們團隊的審查標準、常見的 code smell、安全檢查項目等。Agent 會根據程式碼的類型（前端/後端/資料庫）自動載入對應的檢查清單。 - Custom Commands 方式：建立
/review-pr指令，手動觸發完整的 PR 審查流程。每次執行都會跑一樣的步驟：拉取最新程式碼、執行 linter、檢查測試覆蓋率、產生審查報告。 - Subagents 方式：當 PR 包含大量檔案時，Claude 會自動啟動多個 Subagents 平行審查不同的檔案，最後彙整結果。
- MCP 方式：連接 GitHub API 拉取 PR 內容、留 comment、更新 PR 狀態。
案例 3：多語言翻譯
- Skills 方式：建立
translation-skill，教 Agent 你們的翻譯規範（例如專有名詞怎麼翻、語氣要正式還是輕鬆、哪些詞保留原文等）。當對話中出現「翻譯」、「i18n」等關鍵字，Agent 會自動載入這個 Skill。 - Custom Commands 方式：建立
/translate-to-zh和/translate-to-en兩個指令，分別處理中英翻譯。適合用在翻譯方向固定、格式統一的情境。 - MCP 方式：連接翻譯 API（如 DeepL、Google Translate）來輔助翻譯，或是連接術語表資料庫來確保專有名詞的一致性。
案例 4：部署流程
- Skills 方式：建立
deployment-guideSkill，包含部署前的檢查清單、環境設定、rollback 步驟等。Agent 會根據部署環境（dev/staging/production）載入對應的注意事項。 - Custom Commands 方式：建立
/deploy-staging和/deploy-prod等指令，固定執行特定環境的部署流程。 - MCP 方式：連接 CI/CD 系統（如 GitHub Actions、Jenkins）來實際執行部署，或是連接監控系統來確認部署狀態。
- Subagents 方式：在執行部署的同時，啟動另一個 Subagent 監控系統狀態，如果發現異常就立即通知。
透過這些實際案例，應該可以更清楚看出各個機制的適用時機。記住一個原則：需要自動判斷用 Skills，需要手動觸發用 Custom Commands，需要連接外部服務用 MCP，需要平行處理用 Subagents。
建立自己的 Skill
聽這麼多理論手癢了嗎？來實際動手做一個 Skills 吧！
最小可行版本：5 分鐘做出第一個 Skill
如果你想先快速體驗一下 Skills 怎麼運作，這裡有一個超級簡單的範例，不到 10 行就能完成：
第一步，建立資料夾：
mkdir -p ~/.claude/skills/hello-skill
cd ~/.claude/skills/hello-skill
第二步，建立 SKILL.md：
cat > SKILL.md << 'EOF'
---
name: hello-skill
description: A simple greeting skill. Use when user says hello, hi, or greets you.
---
# Hello Skill
When the user greets you (says hello, hi, hey, etc.), respond with:
"你好！我是透過 Skill 學會打招呼的 Claude。這代表 Skill 已經成功啟用了！🎉"
Always use this exact greeting format when this skill is activated.
EOF
第三步，測試： 重新啟動 Claude Code，然後跟它說「hello」，看看會不會出現上面那段特定的回應。
成功了？恭喜！ 你已經掌握 Skills 的核心概念了：
name必須跟資料夾名稱一致description告訴 Claude 什麼時候該用這個 Skill- SKILL.md 的內容就是給 Claude 的指令
這個超簡單的範例只是讓你快速體驗 Skills 的運作方式。下面我們來做一個真正實用的 Skill。
實戰範例：Commit Message Helper
從一個大家比較常會遇到的情境開始講起。我猜很多工程師都不喜歡寫 Git 的 Commit Message，我也是。如果我想要建立一個可以幫忙處理 Commit Message 的 Skill，讓 Agent 不只幫我們寫，而且還要遵循特定格式...
第一步，建立一個資料夾，名稱隨意：
mkdir commit-message-helper
第二步，在這個目錄裡建立 SKILL.md 檔案，內容如下：
---
name: commit-message-helper
description: Helps write Git commit messages following the Conventional Commits specification. Use this skill when the user asks to commit changes, write commit messages, or mentions git commits.
---
# Commit Message Helper
When writing commit messages, follow these rules:
## Format
<type>(<scope>): <subject>
<body>
<footer>
## Types
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing tests or correcting existing tests
- chore: Changes to the build process or auxiliary tools
## Guidelines
1. Subject line should be no longer than 50 characters
2. Use imperative mood ("add feature" not "added feature")
3. Do not end the subject line with a period
4. Separate subject from body with a blank line
5. Use the body to explain what and why, not how
## Examples
Good:
feat(auth): add OAuth2 login support
Implement OAuth2 authentication flow to allow users to log in
with their Google or GitHub accounts.
Closes #123
Bad:
updated stuff
別忘了 name 欄位要跟資料夾名稱一樣，這是規格要求的。 再來注意 description 欄位的寫法，這裡特別寫了「when the user asks to commit changes, write commit messages, or mentions git commits」，這樣 Claude 才知道「什麼時候」該啟用這個 Skill。description 寫得越具體，Claude 的判斷就越準確。
是說，如果不知道這個檔案的內容怎麼辦？問 AI 啊！把情境跟 AI 講，不管哪一家的 AI 應該都有辦法寫出來，上面的內容就是我請 Claude 幫我寫的。
如果你的 Skills 需要執行腳本，可以建立 scripts/ 目錄然後把程式碼放裡面。例如我想加一個驗證 commit message 格式的腳本，就把這個腳本放在 scripts 目錄裡，例如叫做 validate_commit.py：
import re
import sys
def validate_commit_message(message):
pattern = r'^(feat|fix|docs|style|refactor|perf|test|chore)(\(.+\))?: .{1,50}'
if re.match(pattern, message.split('\n')[0]):
return True, "Valid commit message format"
return False, "Invalid format. Expected: type(scope): subject"
if __name__ == "__main__":
message = sys.argv[1] if len(sys.argv) > 1 else ""
valid, msg = validate_commit_message(message)
print(msg)
sys.exit(0 if valid else 1)
光把腳本放進 scripts/ 目錄還不夠，你需要在 SKILL.md 裡加註說明，告知 Agent 這個腳本的存在和用法：
## Validation
Before committing, run the validation script to check the format:
python scripts/validate_commit.py "your commit message"
這樣 Agent 才知道有這個工具可以用。
最後，把這個 Skills 安裝到 Claude Code。有兩種放法：
放到 ~/.claude/skills/：這是個人層級，你在任何專案都能用
放到專案的 .claude/skills/：這是專案層級，只有這個專案能用，但只要專案裡有這個 Skill，團隊成員也都能用。
萬一兩邊有同名的 Skill，根據官方文件，個人層級的會蓋過專案層級的 Skill。
SKILL.md 撰寫模板
看完上面的例子，你應該對 Skills 的結構有基本概念了。不過如果要從零開始寫一個 SKILL.md，可能還是會不知道從何下手。這裡提供一個通用的模板，你可以直接套用：
---
name: your-skill-name
description: |
[第一句：這個 Skill 做什麼]
[第二句：什麼情境下該用]
[第三句：關鍵觸發詞或條件]
範例：
Helps translate technical documents from English to Traditional Chinese
following Taiwan localization standards. Use when user mentions translation,
i18n, localization, or provides English text that needs translation.
---
# [Skill 的完整名稱]
## 目的
一到兩句話說明這個 Skill 的用途和解決的問題。
例如：這個 Skill 幫助你撰寫符合團隊規範的 Git commit message，
確保每個 commit 都有清楚的類型標記、簡潔的摘要，以及必要的說明。
## 使用時機
列出這個 Skill 適用的具體情境，讓 Agent 更容易判斷：
- 情境 1：當使用者要 commit 程式碼時
- 情境 2：當使用者詢問「怎麼寫 commit message」時
- 情境 3：當使用者提供 diff 並要求產生 commit message 時
## 核心規則
這是 Skill 的主體部分，寫明 Agent 應該遵循的規則和步驟：
### 規則 1：格式要求
- 具體的格式定義
- 可以用範例輔助說明
- 如果有多種格式，說明如何選擇
### 規則 2：內容要求
- 必須包含哪些資訊
- 不應該包含哪些內容
- 字數或長度限制
### 規則 3：特殊情況處理
- 如果遇到 X 情況，應該 Y
- 如果使用者提供不完整資訊，應該詢問 Z
## 操作步驟（選用）
如果這個 Skill 涉及多步驟的流程，可以列出明確的步驟：
1. 第一步：檢查輸入資訊是否完整
2. 第二步：分析變更內容，判斷類型
3. 第三步：依據規則產生輸出
4. 第四步：驗證結果是否符合格式
## 範例
提供完整的輸入輸出範例，這對 Agent 的學習非常重要：
### 範例 1：新功能
**輸入情境**：
使用者新增了 OAuth2 登入功能
**預期輸出**：
feat(auth): add OAuth2 login support
Implement OAuth2 authentication flow to allow users to log in with their Google or GitHub accounts. This includes:
- OAuth2 client configuration
- Redirect URI handling
- Token exchange and validation
Closes #123
### 範例 2：Bug 修復
**輸入情境**：
修復了使用者登出後 session 沒有清除的問題
**預期輸出**：
fix(auth): clear session data on logout
Ensure all session data is properly cleared when user logs out to prevent security issues.
Fixes #456
## 常見問題處理
列出使用者可能遇到的問題和對應的處理方式：
**問題 1：使用者只說「幫我 commit」但沒提供變更內容**
處理方式：詢問使用者「請問這次的變更內容是什麼？」或「我需要查看 git diff 嗎？」
**問題 2：變更內容涉及多個不相關的功能**
處理方式：建議使用者分成多個 commit，並分別說明每個 commit 應該包含哪些檔案。
**問題 3：不確定該用哪個類型（feat vs fix vs refactor）**
處理方式：說明各類型的差異，並根據變更內容給出建議。
## 參考資源（選用）
如果有額外的參考文件或腳本，在這裡說明：
- 詳細的格式規範請見：`references/commit-format-spec.md`
- 驗證腳本位於：`scripts/validate_commit.py`
- 團隊 commit message 範例集：`references/commit-examples.md`
使用方式：
```bash
python scripts/validate_commit.py "feat(auth): add login"
注意事項（選用）
列出使用這個 Skill 時需要特別注意的事項：
- 注意事項 1：commit message 不應包含敏感資訊（密碼、API key 等）
- 注意事項 2：如果 commit 包含 breaking change，必須在 footer 註明
- 注意事項 3：subject 行不要超過 50 字元，body 每行不超過 72 字元
### 使用這個模板的技巧
**1. description 是最重要的部分**
這 100 個 tokens 決定了 Agent 會不會啟用你的 Skill。寫的時候要把自己當成是在跟 Agent 解釋「什麼時候你該用這個技能」。多測試幾次，看看 Agent 的判斷是否準確。
**2. 範例越具體越好**
不要寫「輸入：一段程式碼，輸出：重構後的程式碼」這種抽象的範例。要寫完整的、真實的、可以直接參考的範例。如果可以，提供 3-5 個涵蓋不同情境的範例。
**3. 用清單和結構化格式**
避免寫長篇大論的段落。Agent 更容易理解條列式的規則和步驟。善用 Markdown 的格式功能：標題、清單、程式碼區塊、粗體等。
**4. 先寫核心，再擴充**
不要一開始就想把所有細節都寫進去。先寫最核心的 20% 規則（通常就能處理 80% 的情況），測試看看效果如何，再根據實際使用情況慢慢補充 edge cases。
**5. 不會寫就問 AI**
真的，把你的需求告訴 ChatGPT、Claude 或任何你慣用的 AI，請它幫你產生 SKILL.md 的初稿。你再根據實際情況調整就好。AI 寫 AI 的指令，這個 meta 的迴圈挺有趣的。
## 真實世界範例：完整可用的 Skills
看完理論和模板，最好的學習方式就是看實際的範例。這裡提供三個完整的、可以直接複製使用的 Skills，涵蓋不同的使用場景。
### 範例 1：技術文件翻譯 Skill
這個 Skill 適合需要將英文技術文件翻譯成繁體中文的情境，特別是要保持技術用語的一致性。
**目錄結構：**
tech-translation/ ├── SKILL.md └── references/ └── terminology.md
**SKILL.md 完整內容：**
```markdown
---
name: tech-translation
description: Translates technical documentation from English to Traditional Chinese following Taiwan localization standards. Use when user mentions translation, localization, i18n, or provides English technical text that needs Chinese translation.
---
# 技術文件翻譯 Skill
## 目的
將英文技術文件翻譯成符合台灣用語習慣的繁體中文，確保技術術語的一致性和可讀性。
## 翻譯原則
### 1. 專有名詞處理
**保持原文的術語：**
- API、SDK、CLI 等縮寫不翻譯
- Git、Docker、Kubernetes 等產品名稱不翻譯
- React、Vue、Angular 等框架名稱不翻譯
**常見術語對照：**
- function → 函式（不用「函數」）
- array → 陣列
- object → 物件
- string → 字串
- deploy → 部署
- commit → 提交
- repository → 儲存庫（不用「倉庫」）
- pull request → 拉取請求（可簡稱 PR）
更多術語請參考：references/terminology.md
### 2. 語氣和風格
- 使用「你」而不是「您」（技術文件不需要過度正式）
- 避免過度翻譯，保持技術文件的簡潔性
- 程式碼範例中的註解也要翻譯
- 保留原文的 Markdown 格式
### 3. 特殊處理
**指令和路徑不翻譯：**
```bash
# ✅ 正確
執行 `npm install` 來安裝相依套件
# ❌ 錯誤
執行「國家套件管理器 安裝」來安裝相依套件
連結文字翻譯但 URL 保持：
✅ 正確：查看[官方文件](https://example.com/docs)
❌ 錯誤：查看[official documentation](https://example.com/docs)
翻譯步驟
- 先通讀全文，理解內容脈絡
- 識別需要保持原文的專有名詞
- 逐段翻譯，確保語意通順
- 檢查程式碼範例中的註解是否已翻譯
- 最後通讀一遍，確認用詞一致
範例
範例 1：API 文件翻譯
原文：
# Authentication
Use the API key to authenticate your requests. Pass the key in the Authorization header:
\```javascript
fetch('https://api.example.com/data', {
headers: {
'Authorization': `Bearer ${apiKey}` // Your API key
}
})
\```
翻譯：
# 身份驗證
使用 API 金鑰來驗證你的請求。在 Authorization 標頭中傳遞金鑰：
\```javascript
fetch('https://api.example.com/data', {
headers: {
'Authorization': `Bearer ${apiKey}` // 你的 API 金鑰
}
})
\```
範例 2：錯誤訊息翻譯
原文：
Error: Failed to connect to database. Please check your connection string.
翻譯：
錯誤：無法連接到資料庫。請檢查你的連線字串。
常見問題
Q: 遇到不確定的術語怎麼辦？ A: 先保留原文，並在旁邊用括號註明可能的翻譯，讓使用者決定。例如：「cache（快取）」
Q: 要不要翻譯變數名稱？ A: 絕對不要。所有程式碼內容（變數、函式名稱、class 名稱）都保持原文。
Q: 「你」和「您」如何選擇？ A: 技術文件統一使用「你」，除非是官方正式聲明或法律文件。
**references/terminology.md：**
```markdown
# 技術術語對照表
## 開發工具
- repository → 儲存庫
- branch → 分支
- commit → 提交
- merge → 合併
- pull request → 拉取請求
- issue → 議題
- fork → 分支（動詞：建立分支）
## 程式概念
- function → 函式
- method → 方法
- class → 類別
- object → 物件
- array → 陣列
- variable → 變數
- constant → 常數
- parameter → 參數
- argument → 引數
- return value → 回傳值
## 資料庫
- database → 資料庫
- table → 資料表
- query → 查詢
- index → 索引
- transaction → 交易
- schema → 架構
## Web 開發
- request → 請求
- response → 回應
- endpoint → 端點
- authentication → 身份驗證
- authorization → 授權
- session → 工作階段
- cookie → Cookie（不翻譯）
- cache → 快取
範例 2：Code Review Checklist Skill
這個 Skill 提供系統化的程式碼審查流程，確保每次 Code Review 都不會漏掉重要項目。
目錄結構：
code-review-checklist/
├── SKILL.md
├── references/
│ └── security-patterns.md
└── scripts/
└── check-dependencies.sh
SKILL.md 完整內容：
---
name: code-review-checklist
description: Provides systematic code review checklist for pull requests. Use when user asks to review code, check PR, or mentions code quality, security review, or code review.
---
# Code Review Checklist Skill
## 審查流程
執行 Code Review 時，依照以下順序檢查：
### 1. 基本檢查（5 分鐘）
- [ ] PR 描述清楚說明改動的目的
- [ ] 改動範圍合理（單一 PR 不超過 500 行）
- [ ] 沒有包含不相關的檔案修改
- [ ] 測試都通過了
- [ ] 沒有 merge conflict
### 2. 程式碼品質（10 分鐘）
**命名和可讀性：**
- [ ] 變數、函式命名有意義
- [ ] 沒有過長的函式（超過 50 行要注意）
- [ ] 複雜邏輯有註解說明
- [ ] 沒有被註解掉的程式碼（要刪就刪乾淨）
**結構和設計：**
- [ ] 沒有重複的程式碼（DRY 原則）
- [ ] 函式職責單一（SRP 原則）
- [ ] 適當的錯誤處理
- [ ] 沒有 hard-coded 的設定值
### 3. 安全性檢查（15 分鐘）
**常見漏洞：**
- [ ] 沒有 SQL Injection 風險（使用 prepared statement）
- [ ] 沒有 XSS 風險（輸出有適當跳脫）
- [ ] 沒有敏感資訊外洩（API key、密碼等）
- [ ] 檔案上傳有驗證和限制
- [ ] 使用者輸入都有驗證
**認證和授權：**
- [ ] API endpoint 有適當的權限檢查
- [ ] 敏感操作需要再次驗證
- [ ] Session 管理正確
詳細的安全檢查項目請參考：references/security-patterns.md
### 4. 效能檢查（10 分鐘）
- [ ] 沒有 N+1 查詢問題
- [ ] 大量資料有分頁處理
- [ ] 適當使用快取
- [ ] 避免在迴圈中做 I/O 操作
- [ ] 資料庫查詢有使用索引
### 5. 測試檢查（5 分鐘）
- [ ] 新功能有對應的測試
- [ ] Bug fix 有回歸測試
- [ ] 測試涵蓋 edge cases
- [ ] 測試名稱清楚描述測試目的
## 審查輸出格式
**使用以下格式提供審查意見：**
```markdown
## Code Review Summary
### ✅ 做得好的地方
- [具體指出值得肯定的改進]
### ⚠️ 需要改進
- [嚴重程度：高/中/低] 問題描述
- 建議修改方式
- 相關的最佳實踐
### 💡 建議（非必要）
- [可以考慮的優化方向]
### 📝 總結
[整體評估：Approve / Request Changes / Comment]
範例
輸入情境
使用者提供了一個新增使用者註冊功能的 PR
審查輸出
## Code Review Summary
### ✅ 做得好的地方
- 使用 bcrypt 雜湊密碼，安全性考慮周全
- 測試覆蓋率達 85%，包含各種 edge cases
- 錯誤訊息清楚，方便除錯
### ⚠️ 需要改進
- [嚴重程度：高] `UserController.js:45` - 沒有驗證 email 格式
- 建議：使用 validator.isEmail() 驗證
- 參考：https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
- [嚴重程度：中] `UserModel.js:23` - 密碼強度沒有檢查
- 建議：要求至少 8 個字元，包含大小寫字母和數字
- 可以使用 zxcvbn 套件評估密碼強度
- [嚴重程度：低] `register.test.js:67` - 測試用的 email 應該使用 example.com
- 建議：改用 test@example.com 而不是真實網域
### 💡 建議（非必要）
- 可以考慮加入 rate limiting，防止大量註冊攻擊
- Email 驗證可以抽成獨立的 middleware
### 📝 總結
整體程式碼品質良好，但有幾個安全性問題需要修正後才能合併。
建議：**Request Changes**
使用腳本檢查相依套件
執行以下指令檢查是否有已知漏洞：
```bash bash scripts/check-dependencies.sh ```
這個腳本會檢查：
- npm audit 結果
- 過時的套件版本
- 已知的安全漏洞
**scripts/check-dependencies.sh：**
```bash
#!/bin/bash
echo "🔍 檢查相依套件安全性..."
# 檢查 npm 套件漏洞
if [ -f "package.json" ]; then
echo "\n📦 執行 npm audit..."
npm audit --audit-level=moderate
fi
# 檢查過時套件
echo "\n📅 檢查過時套件..."
npm outdated
echo "\n✅ 檢查完成"
references/security-patterns.md：
# 安全檢查模式
## SQL Injection 防護
❌ 危險寫法：
\```javascript
const query = `SELECT * FROM users WHERE email = '${userInput}'`;
\```
✅ 安全寫法：
\```javascript
const query = 'SELECT * FROM users WHERE email = ?';
db.execute(query, [userInput]);
\```
## XSS 防護
❌ 危險寫法：
\```javascript
element.innerHTML = userInput;
\```
✅ 安全寫法：
\```javascript
element.textContent = userInput;
// 或使用框架提供的安全方法
\```
## 敏感資訊保護
❌ 危險寫法：
\```javascript
const apiKey = "sk-1234567890abcdef";
\```
✅ 安全寫法：
\```javascript
const apiKey = process.env.API_KEY;
\```
範例 3：Git Commit 訊息格式化 Skill
這個 Skill 幫助團隊維持一致的 Git commit 格式，包含驗證腳本。
目錄結構：
commit-formatter/
├── SKILL.md
└── scripts/
└── validate-commit.py
SKILL.md 完整內容：
---
name: commit-formatter
description: Formats Git commit messages following Conventional Commits specification. Use when user asks to write commit message, create commit, or mentions git commit.
---
# Commit Message Formatter
## 格式規範
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 規範：