自定義 Agents 與 Skills

你將學到什麼

Claude Code 不是一個固定的產品。它是一個可擴展的平台。只要將 Markdown 檔案放入特定目錄，你就能新增全新的功能 — 自定義斜線命令、專門的審查者、自動化工作流，以及特定領域的助手。

完成後，你將了解：

• Skills 和 Agents 之間的差異
• 如何撰寫 skill 檔案（使用者觸發的擴展）
• 如何撰寫 agent 檔案（AI 觸發的子代理）
• 兩者的設計模式
• 如何限制工具以確保安全
• 從觸發到執行的生命週期

問題是什麼

每個團隊都有工作流程。部署程序、程式碼審查清單、測試協議、新人導入指南。這些知識通常存在於兩個地方：沒人閱讀的文件，和某個人的腦中。

部落知識問題：

  「我們怎麼部署？」
  → 問 Sarah，她知道步驟

  「我們的 PR 審查清單是什麼？」
  → 在 wiki 裡... 某個地方

  「我們怎麼處理資料庫遷移？」
  → Dave 寫了一個腳本，去他的家目錄找找

如果這些知識可以被編碼為 AI 可執行的指令呢？不只是文件 — 而是 AI 每次都會按步驟遵循的指令。

這就是自定義 agents 和 skills 做的事。

如何運作

Skills 與 Agents

這兩個概念扮演不同的角色：

┌──────────────────────────────────────────────────────┐
│                                                       │
│  Skills（使用者觸發）         Agents（AI 觸發）       │
│                                                       │
│  ┌─────────────────────┐     ┌─────────────────────┐ │
│  │ 由使用者觸發          │     │ 由 AI 觸發           │ │
│  │ 透過斜線命令          │     │ 透過 Agent 工具      │ │
│  │                      │     │                       │ │
│  │ /deploy              │     │ 「讓我產生一個         │ │
│  │ /review              │     │  安全審查者」          │ │
│  │ /changelog           │     │                       │ │
│  │                      │     │ 作為子代理運行         │ │
│  │ 在主上下文中運行      │     │ 擁有自己的上下文      │ │
│  └─────────────────────┘     └─────────────────────┘ │
│                                                       │
│  位置：                       位置：                   │
│  .claude/skills/name/         .claude/agents/         │
│    SKILL.md                     name.md               │
│                                                       │
└──────────────────────────────────────────────────────┘

面向	Skill	Agent
觸發方式	使用者（/skill-name）	AI（子代理產生）
上下文	注入到主對話中	在隔離的子上下文中運行
用途	逐步工作流、範本	專門角色（審查者、探索者）
位置	.claude/skills/name/SKILL.md	.claude/agents/name.md
範圍	廣泛（完整工作流）	聚焦（單一職責）

Skill 的結構

一個 skill 檔案是一個帶有可選前置資料的 Markdown 文件：

# File: .claude/skills/deploy/SKILL.md

# Deploy Skill

Deploy the application to production with safety checks.

## Steps

1. Run `git status` to check for uncommitted changes
2. Run the full test suite with `npm test`
3. If tests fail, stop and report the failures
4. Run `npm run build` and verify no errors
5. Show the user a summary:
   - Test results
   - Build size
   - Files changed since last deploy
6. Ask: "Ready to deploy? [yes/no]"
7. Only if user confirms: run `git push origin main`
8. Report the deployment status

## Rules

- NEVER push without user confirmation
- If any step fails, stop and report
- Include build size comparison with previous deploy

當使用者輸入 /deploy 時，Claude Code 會找到匹配的 skill 檔案，將其內容注入對話中，並遵循指令。

Agent 的結構

一個 agent 檔案定義了 AI 可以作為子代理產生的專門角色：

# File: .claude/agents/security-reviewer.md

# Security Reviewer

You are a security-focused code reviewer. Your job is to find
security vulnerabilities in code changes.

## What to Check

- SQL injection: raw query strings with user input
- XSS: unescaped output in templates
- Auth bypass: missing middleware on protected routes
- Secrets: hardcoded API keys, passwords, tokens
- Path traversal: unsanitized file paths
- SSRF: user-controlled URLs in server requests

## Output Format

For each finding:
1. **File and line**: exact location
2. **Severity**: Critical / High / Medium / Low
3. **Issue**: what the vulnerability is
4. **Fix**: how to resolve it

If no issues found, say "No security issues found" and explain
what you checked.

## Tools

You may only use: Read, Glob, Grep
Do NOT edit files or run commands.

AI 在需要安全審查時產生這個 agent：

{
  "type": "tool_use",
  "name": "Agent",
  "input": {
    "agent": "security-reviewer",
    "prompt": "Review the changes in src/api/ for security issues"
  }
}

Skill 生命週期

┌──────────────────────────────────────────────────────┐
│              Skill 觸發生命週期                        │
│                                                       │
│  1. 使用者輸入 /deploy                                 │
│     │                                                 │
│     ▼                                                 │
│  2. Claude Code 掃描 .claude/skills/                   │
│     尋找匹配的目錄名稱                                  │
│     │                                                 │
│     ▼                                                 │
│  3. 找到：.claude/skills/deploy/SKILL.md               │
│     │                                                 │
│     ▼                                                 │
│  4. Skill 內容注入到對話中                              │
│     作為上下文（如同擴展的系統提示）                     │
│     │                                                 │
│     ▼                                                 │
│  5. AI 讀取指令並逐步遵循                              │
│     使用其正常的工具存取權限                             │
│     │                                                 │
│     ▼                                                 │
│  6. 工作流完成（或使用者中斷）                          │
│                                                       │
└──────────────────────────────────────────────────────┘

Skill 設計模式

模式 1：逐步工作流

最常見的模式。一系列編號的操作：

## Steps
1. Check preconditions
2. Gather information
3. Present plan to user
4. Execute with safety checks
5. Verify results
6. Report summary

模式 2：決策樹

用於根據條件分支的工作流：

## Process

Check the project type:

- If `package.json` exists → Node.js project
  - If `tsconfig.json` exists → TypeScript
    - Use `npx tsc --noEmit` for type checking
  - Else → JavaScript
    - Use `node --check` for syntax validation

- If `requirements.txt` exists → Python project
  - Use `python -m py_compile` for syntax checking

- If `Cargo.toml` exists → Rust project
  - Use `cargo check` for compilation checking

模式 3：基於範本的輸出

用於生成結構化內容的 skill：

## Output Template

Generate a changelog entry using this format:

### [version] - YYYY-MM-DD

#### Added
- New features

#### Changed
- Changes to existing features

#### Fixed
- Bug fixes

Fill each section by analyzing git commits since the last tag.

Agent 設計模式

模式：專門審查者

# Performance Reviewer

Analyze code for performance issues.

## Check For
- N+1 queries in database access patterns
- Missing pagination on list endpoints
- Unbounded array operations (map/filter on large datasets)
- Missing indexes suggested by query patterns
- Synchronous operations that should be async

## Tools: Read, Glob, Grep only

模式：帶結構化輸出的探索者

# Architecture Explorer

Map the architecture of an unfamiliar codebase.

## Output Format
- Entry points (main files, index files)
- Dependency graph (what imports what)
- Data flow (where data enters, transforms, exits)
- External dependencies (APIs, databases, services)

## Tools: Read, Glob, Grep only

工具限制

限制 agent 的工具是一種安全機制。審查者不應該編輯程式碼。探索者不應該執行命令。

## Tools

Allowed: Read, Glob, Grep
Not allowed: Edit, Write, Bash, Agent

當 AI 產生這個 agent 時，它只能存取列出的工具。這遵循最小權限原則 — 只給每個 agent 它所需要的能力。

關鍵洞見

自定義 agents 和 skills 是你編碼團隊工作流知識的方式。 它們將部落知識轉化為可重複、一致的 AI 行為。

平庸的 Claude Code 設定和強大的之間的差異，不在於模型或硬體 — 而在於 skills 和 agents 的品質。一個寫得好的部署 skill 意味著每次部署都遵循相同的安全檢查。一個寫得好的安全審查者意味著每個 PR 都得到相同的審視。

這是「基礎設施即程式碼」原則應用到 AI 工作流上：工作流即 Markdown。

想想你的團隊重複做的事情：

• 帶有特定清單的程式碼審查
• 帶有安全閘門的部署程序
• 資料遷移協議
• 讓新團隊成員熟悉程式碼庫

每一項都可以成為一個 skill 或 agent，每次都以相同的方式運行，無論是誰觸發的。

實作範例

建構一個自定義的程式碼審查 skill 和一個安全審查者 agent。

審查 Skill

建立 .claude/skills/review/SKILL.md：

# Code Review

Review the current branch's changes against the base branch.

## Steps

1. Run `git diff main...HEAD --stat` to see changed files
2. For each changed file:
   - Read the full diff with `git diff main...HEAD -- <file>`
   - Check for:
     - Missing error handling
     - Hardcoded values that should be config
     - Functions longer than 50 lines
     - Missing type annotations
     - Console.log or debug statements left in
3. Spawn the security-reviewer agent on changed files
4. Compile all findings into a report:

## Report Format

### Summary
[1-2 sentence overview]

### Findings
| File | Line | Severity | Issue |
|------|------|----------|-------|

### Security Review
[Output from security-reviewer agent]

### Recommendation
[Approve / Request Changes / Needs Discussion]

安全審查者 Agent

建立 .claude/agents/security-reviewer.md：

# Security Reviewer

You review code for security vulnerabilities. Be thorough
but avoid false positives. Only flag issues you are
confident about.

## Checklist
- [ ] No SQL injection (parameterized queries)
- [ ] No XSS (output escaping)
- [ ] No hardcoded secrets
- [ ] Auth middleware on protected routes
- [ ] Input validation on user-facing endpoints
- [ ] No path traversal in file operations

## Output
List findings with file, line, severity, and fix.
If clean, state "No security issues found."

## Tools: Read, Glob, Grep

現在當你輸入 /review 時，AI 會遵循審查 skill，將安全審查者作為子代理產生，並生成結構化的報告。每次審查都是一致的。

前後對比

沒有擴展	有自定義 Agents 與 Skills
工作流存在於文件中	工作流是 AI 可執行的 Markdown
一致性取決於誰在運行	每次都是相同的步驟
新團隊成員需要培訓	Skills 編碼了培訓內容
審查因審查者而異	Agents 應用相同的清單
部落知識在人的腦中	知識編碼在檔案中，受版本控制
新增能力需要寫程式碼	新增能力只需要一個 Markdown 檔案

下一堂課

你已經擁有用自己的工作流擴展 Claude Code 的工具。第 24 堂課將所有內容整合在一起，涵蓋生產環境模式 — 如何從個人生產力工具轉變為團隊級平台，包含可觀測性、CI/CD 整合，以及擴展 AI 輔助開發的成熟度模型。