Claude Code系列文9 – Skills深度攻略

你不想每次都從「教模型怎麼做事」開始

想像一個場景。

你每天早上到公司，都要跟同一個同事說：「嘿，你是前端工程師。我們用 React，狀態管理用 Zustand，CSS 用 Tailwind。API 在 /api 資料夾，測試用 Vitest。UI 規範在 Figma 上，命名用 camelCase，commit message 格式是 conventional commits。」

每天。每一次。從零開始。

這就是你現在跟 AI 互動的方式。

每次開新對話，你都在做同樣的事——角色設定、流程步驟、輸出格式、注意事項、邊界條件。你可能已經把這些存成某個地方的文字片段，每次手動貼上。但你心裡知道，這很笨。

Skills 就是 Claude Code 對這個問題的回答。

Skills 是什麼

一句話：Skills 是可重用的能力模組，把你已經想清楚、驗證過的做事方式，變成 AI 的內建能力。

不是 prompt template。不是文件參考。是一個完整的「能力」。

一個 Skill 裡可以包含：

• 固定流程：Search → Convert → Output JSON 那種標準化作業程序
• 領域知識：Flutter 的 Widget 設計原則、自由潛水的訓練計畫邏輯、資料同步的衝突處理策略
• 最佳實務：你踩過的雷、團隊累積的經驗、程式碼審查時反覆出現的問題
• 輸出規範：永遠是同一種結構、同一種格式、同一種品質標準

Claude 載入一個 Skill 的瞬間，就直接「進入狀態」。不需要暖身，不需要你再花 500 字解釋背景。它已經知道該怎麼做，因為你已經把方法論寫好了。

這跟 CLAUDE.md 有什麼不同？CLAUDE.md 是「讓 AI 認識你的專案」，它永遠在 context 裡。Skills 是「讓 AI 學會特定技能」，只在需要的時候才載入。一個是專案的基礎認知，一個是按需呼叫的專業能力。

三層載入機制：Skills 的設計核心

這是整篇文章最重要的部分。

Claude Code 的 Skills 不是「一次全部載入」的。它用了一個三層 lazy-loading 機制，精確控制什麼時候載入什麼內容。這個設計直接決定了 token 效率。

Level 1：Metadata（永遠載入）

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

只有這段 YAML header 會永遠存在於 context 中。

就這樣。不是整份文件，不是所有指令——只有名稱和描述。Claude 讀這段 metadata，判斷「我需不需要這個 Skill」。如果你這次的對話跟 PDF 完全無關，這個 Skill 的其他內容永遠不會被載入，token 消耗趨近於零。

這就像一本書的書名和簡介。你看到書名就知道要不要翻開它。

Level 2：Instructions（觸發時載入）

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()

For advanced form filling, see [FORMS.md](FORMS.md).

當 Claude 判斷「這次需要用到 PDF 處理」，它才會載入 SKILL.md 的主要內容。這裡面包含快速開始指南、核心指令、基本流程。

注意：這一層只在 Claude 主動判斷需要時才載入。你不需要手動觸發，Claude 會根據你的對話內容自動決定。

Level 3：Resources 與程式碼（按需載入）

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

額外的參考文件、範本、腳本——這些只有在 SKILL.md 中被明確引用，而且 Claude 在當下的任務中確實需要時，才會被載入。

你可以在一個 Skill 裡放一份完整的 API 文件（幾千行）、一個龐大的資料集、複雜的範例程式碼。這些內容在實際取用之前，完全不消耗任何 token。

三層載入的效率邏輯

Level 1: Metadata → 永遠在 context → 幾十個 token
Level 2: Instructions → 需要時載入 → 幾百到幾千個 token
Level 3: Resources → 實際引用時載入 → 無上限，用多少算多少

這個設計的精妙之處在於：你可以建立 20 個、50 個 Skills，但每次對話真正消耗的 token 只有「此刻需要的那一份」。其他所有 Skills 的存在成本，就只是各自那幾十個 token 的 metadata。

如果你在 Claude Code系列文8 – 七大元件 理解了 Claude Code 是一個生態系，那 Skills 的三層載入就是這個生態系「聰明又不浪費」的關鍵設計。

Token 效率的秘密

三層載入只是效率故事的一半。另一半更有意思。

Skills 中的程式碼執行只消耗 output token。

什麼意思？一般情況下，你讓 Claude 「幫我寫一個腳本來處理 CSV」，它會先生成程式碼（消耗 output token），然後執行（再消耗一輪）。但如果這個腳本已經寫好存在 Skill 裡，Claude 直接執行它——跳過「生成」這一步，只消耗執行輸出的 token。

這個差異在頻繁執行的工作流中非常顯著。你有一個數據轉換腳本每天跑三次，放在 Skill 裡比每次請 Claude 重新寫，一個月下來省的 token 是可觀的。

另外一個效率面向：附加資源檔案沒有大小限制。 你可以放：

• 完整的第三方 API 文件
• 大型參考資料集
• 複雜的範例程式碼庫
• 任何 Claude 在執行任務時可能需要參考的素材

這些內容在被實際讀取之前，零 token 消耗。這讓你可以大方地準備詳盡的參考資料，不用擔心「放太多會浪費 token」。

實戰：四個你現在就能建的 Skill

理論講完了，給你四個在真實開發中馬上能用的 Skill 設計。

Skill 1：Code Review 標準化

---
name: code-review
description: Review code changes following team standards. Use when reviewing PRs, checking code quality, or when the user mentions "review".
---

When reviewing code, follow this checklist:

## Review Flow
1. **Read the diff** — Understand what changed and why
2. **Check naming** — Variables, functions, files follow our conventions
3. **Check error handling** — All async operations have proper error handling
4. **Check edge cases** — Null, empty arrays, boundary conditions
5. **Check tests** — Changes have corresponding test updates
6. **Check performance** — No N+1 queries, unnecessary re-renders, or memory leaks

## Output Format
For each issue found:
- **Severity**: Critical / Warning / Suggestion
- **Location**: File and line number
- **Problem**: What's wrong
- **Fix**: How to fix it

If no issues found, explicitly state "Reviewed, no issues found."

Skill 2：API Endpoint 產生器

---
name: create-api
description: Generate RESTful API endpoints following project conventions. Use when creating new endpoints, API routes, or backend services.
---

When creating an API endpoint:

1. **Route naming**: Use kebab-case, plural nouns (`/api/user-profiles`)
2. **Validation**: Use Zod schemas for all request/response types
3. **Error handling**: Return standardized error responses with error codes
4. **Response format**: Always wrap in `{ data, error, meta }` structure

## File structure
- Route: `src/app/api/[resource]/route.ts`
- Schema: `src/schemas/[resource].ts`
- Tests: `src/__tests__/api/[resource].test.ts`

## Additional resources
- For Zod schema patterns, see [schemas.md](schemas.md)
- For error code reference, see [errors.md](errors.md)

Skill 3：Git Commit 規範

---
name: commit
description: Create standardized git commits. Use when committing changes, creating PRs, or when the user says "commit".
disable-model-invocation: true
---

Create a git commit for the current changes. $ARGUMENTS

## Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

## Types
- feat: New feature
- fix: Bug fix
- refactor: Code restructuring
- docs: Documentation
- test: Test additions/changes
- chore: Build, CI, dependencies

## Rules
1. Subject line: imperative mood, no period, under 50 chars
2. Body: explain "why" not "what"
3. Footer: reference issues (Closes #123)
4. Run `git diff --staged` first to understand changes
5. Group related changes, split unrelated changes

Skill 4：技術文件撰寫

---
name: write-docs
description: Write technical documentation following team standards. Use when creating README, API docs, architecture docs, or when the user mentions "documentation".
---

When writing technical documentation:

## Structure
1. **Title** — Clear, descriptive
2. **Overview** — One paragraph, what this is and why it exists
3. **Quick Start** — Minimal steps to get running
4. **Architecture** — System diagram (use Mermaid)
5. **API Reference** — Every public interface documented
6. **Examples** — At least 2 real-world usage examples
7. **Troubleshooting** — Common issues and solutions

## Style Rules
- Write for the reader who will maintain this code in 6 months
- Every code block must specify the language
- Use Mermaid for diagrams, not ASCII art
- Link to related docs, don't duplicate content

## Additional resources
- For Mermaid syntax, see [mermaid-guide.md](mermaid-guide.md)
- For documentation templates, see [templates/](templates/)