Claude Code 手冊

Appearance

Claude How To

代理技能指南 (Agent Skills Guide) ​

代理技能 (Agent Skills) 是可重複使用的、基於檔案系統的功能，用來擴充 Claude 的功能。它們將特定領域的專業知識、工作流程和最佳實踐封裝成可被發現的組件，Claude 會在相關時自動使用它們。

概覽 (Overview) ​

代理技能 (Agent Skills) 是模組化的功能，能將通用代理 (General-Purpose Agents) 轉化為專家。與提示詞 (Prompts，即針對一次性任務的對話層級指示) 不同，技能會按需載入，免去了在多個對話中重複提供相同指導的麻煩。

主要優勢 (Key Benefits) ​

  • 專業化 Claude (Specialize Claude)：為特定領域任務量身客製功能
  • 減少重複 (Reduce Repetition)：一次建立，跨對話自動使用
  • 組合功能 (Compose Capabilities)：結合多個技能以建構複雜工作流程
  • 擴展工作流程 (Scale Workflows)：跨多個專案和團隊重複使用技能
  • 維持品質 (Maintain Quality)：將最佳實踐直接嵌入您的工作流程中

技能遵循 Agent Skills 開放標準，該標準可跨多個 AI 工具使用。Claude Code 進一步延伸了該標準，加入了調用控制 (Invocation Control)、子代理執行 (Subagent Execution) 以及動態脈絡注入 (Dynamic Context Injection) 等附加功能。

附註：自訂斜線指令 (Custom Slash Commands) 已合併至技能中。.claude/commands/ 檔案仍可運作並支援相同的 Frontmatter 欄位。建議在新開發中使用技能。當相同路徑同時存在兩者時（例如 .claude/commands/review.md 與 .claude/skills/review/SKILL.md），技能將優先採用。

技能如何運作：漸進式揭露 (How Skills Work: Progressive Disclosure) ​

技能利用漸進式揭露 (Progressive Disclosure) 架構——Claude 會根據需要分階段載入資訊，而不是預先消耗脈絡 (Context)。這能實現高效的脈絡管理，同時保持無限的擴充性。

三個載入層級 (Three Levels of Loading) ​

mermaid
graph TB
    subgraph "Level 1: Metadata (Always Loaded)"
        A["YAML Frontmatter"]
        A1["~100 tokens per skill"]
        A2["name + description"]
    end

    subgraph "Level 2: Instructions (When Triggered)"
        B["SKILL.md Body"]
        B1["Under 5k tokens"]
        B2["Workflows & guidance"]
    end

    subgraph "Level 3: Resources (As Needed)"
        C["Bundled Files"]
        C1["Effectively unlimited"]
        C2["Scripts, templates, docs"]
    end

    A --> B
    B --> C
層級 (Level)載入時機 (When Loaded)Token 成本 (Token Cost)內容 (Content)
層級 1：中繼資料 (Metadata)總是載入（啟動時）每個技能約 100 tokens來自 YAML Frontmatter 的 name 與 description
層級 2：指示 (Instructions)當技能被觸發時低於 5k tokens包含指示與指導的 SKILL.md 主體
層級 3+：資源 (Resources)根據需要實際上無限透過 Bash 執行的打包檔案，無需將內容載入到脈絡中

這意味著您可以安裝許多技能而不會產生脈絡負擔——Claude 只知道每個技能的存在以及何時使用它，直到真正被觸發為止。

技能載入流程 (Skill Loading Process) ​

mermaid
sequenceDiagram
    participant User
    participant Claude
    participant System
    participant SkillInst as Skill Instructions
    participant SkillRes as Skill Resources

    User->>Claude: "Review this code for security issues"
    Claude->>System: Check available skills (metadata)
    System-->>Claude: Skill descriptions loaded at startup
    Claude->>Claude: Match request to skill description
    Claude->>SkillInst: Read code-review-specialist/SKILL.md
    SkillInst-->>Claude: Level 2: Instructions loaded
    Claude->>Claude: Determine: Need templates?
    Claude->>SkillRes: Read templates/checklist.md
    SkillRes-->>Claude: Level 3: Template loaded
    Claude->>Claude: Execute skill instructions
    Claude->>User: Comprehensive code review

技能類型與位置 (Skill Types & Locations) ​

類型 (Type)位置 (Location)作用域 (Scope)共享 (Shared)最適合 (Best For)
企業級 (Enterprise)託管設定 (Managed settings)所有組織使用者是全組織標準
個人級 (Personal)~/.claude/skills/<skill-name>/SKILL.md個人否個人工作流程
專案級 (Project).claude/skills/<skill-name>/SKILL.md團隊是 (透過 git)團隊標準
外掛程式 (Plugin)<plugin>/skills/<skill-name>/SKILL.md啟用處視情況而定與外掛程式一同打包

當不同層級的技能擁有相同的名稱時，較高優先級的位置會勝出：企業級 > 個人級 > 專案級。預設情況下個人技能會覆蓋專案技能；skillOverrides 設定（v2.1.129+）可調整該行為 — 請參閱控制技能覆蓋行為。外掛程式技能使用 plugin-name:skill-name 命名空間，因此不會發生衝突。

子代理技能發現 (Subagent skill discovery) (v2.1.133+)：子代理現在與主工作階段相同，能透過 Skill 工具發現專案、使用者和外掛程式技能。早期版本限制子代理只能使用其嵌入的集合，這意味著技能+子代理工作流程會悄悄退化；從 v2.1.133 開始，兩者皆可看到相同的技能目錄。

自動發現 (Automatic Discovery) ​

巢狀目錄 (Nested directories)：當您處理子目錄中的檔案時，Claude Code 會自動從巢狀的 .claude/skills/ 目錄中發現技能。例如，若您正在編輯 packages/frontend/ 中的檔案，Claude Code 也會尋找 packages/frontend/.claude/skills/ 中的技能。這支援了套件擁有各自技能的 Monorepo 結構。自 v2.1.178 起，當技能名稱在巢狀 .claude/skills/ 目錄之間發生碰撞時，最接近您當前工作目錄的目錄勝出 — 套件層級的技能會覆蓋儲存庫根目錄的同名技能。

--add-dir 目錄：透過 --add-dir 新增的目錄中的技能會自動載入並支援即時變更偵測。對這些目錄中技能檔案的任何修改都會立即生效，無需重啟 Claude Code。

重新載入技能 (Reloading skills)：/reload-skills 指令（於 v2.1.152 新增）會在不重啟工作階段的情況下重新掃描所有技能目錄 — 當新增或編輯了未被即時偵測擷取到的技能時非常有用。SessionStart 掛鉤 (Hook) 可以透過傳回 reloadSkills: true 來觸發相同的重新掃描（請參閱掛鉤 (Hooks)）。

描述配額 (Description budget)：技能描述（層級 1 中繼資料）上限為脈絡視窗 (Context Window) 的 1%（備用值：8,000 個字元）。如果您安裝了許多技能，描述可能會被縮短。所有技能名稱始終包含在內，但描述會被截斷以符合配額。請將關鍵使用場景放在描述的最前面。您可以使用 SLASH_COMMAND_TOOL_CHAR_BUDGET 環境變數來覆蓋此配額。

建立自訂技能 (Creating Custom Skills) ​

基本目錄結構 (Basic Directory Structure) ​

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

SKILL.md 格式 (SKILL.md Format) ​

yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.
  • description（建議）：技能的作用以及何時使用它。若省略，Claude Code 會使用 Markdown 內容的第一段。組合後的 description + when_to_use 文字在技能列表中會被截斷至 1,536 個字元（可透過 skillListingMaxDescChars 配置）。這是 Claude 在決定何時啟用技能時進行比對的依據。
  • name（可選）：預設為技能的目錄名稱。提供時，它會設定顯示名稱 — 僅限小寫字母、數字與連字號（最多 64 個字元），且不能包含 "anthropic" 或 "claude"。對於外掛程式技能，name 也會設定指令的最後段落。

SKILL.md 的所有 Frontmatter 欄位皆為可選；description 是唯一建議填寫的欄位。

可選的 Frontmatter 欄位 (Optional Frontmatter Fields) ​

yaml
---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[filename] [format]"        # Hint for autocomplete
disable-model-invocation: true              # Only user can invoke
user-invocable: false                       # Hide from slash menu
allowed-tools: Read, Grep, Glob             # Restrict tool access
disallowed-tools: Write, Edit               # Remove specific tools while active (v2.1.152)
model: opus                                 # Specific model to use
effort: high                                # Effort level override (low, medium, high, xhigh, max)
context: fork                               # Run in isolated subagent
agent: Explore                              # Which agent type (with context: fork)
background: false                           # Fork skills run in background (default true); false = foreground
shell: bash                                 # Shell for commands: bash (default) or powershell
hooks:                                      # Skill-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
paths: "src/api/**/*.ts"               # Glob patterns limiting when skill activates
---
欄位 (Field)說明 (Description)
name僅限小寫字母、數字和連字號（最多 64 個字元）。不能包含 "anthropic" 或 "claude"。
description技能的作用以及何時使用它。組合後的 description + when_to_use 文字在技能列表中會被截斷至 1,536 個字元（可透過 skillListingMaxDescChars 配置）。對於自動調用比對至關重要。
when_to_use關於 Claude 何時應該調用該技能的附加脈絡。會追加到技能列表中的 description 後，並計入 1,536 字元的上限。
argument-hint在 / 自動補全功能表中顯示的提示（例如 "[filename] [format]"）。
disable-model-invocationtrue = 僅使用者可透過 /name 調用。Claude 永遠不會自動調用。
user-invocablefalse = 從 / 功能表中隱藏。僅 Claude 可以自動調用它。
allowed-tools技能無需權限提示即可使用的工具逗號分隔列表。
disallowed-tools當技能處於啟用狀態時要移除的特定工具逗號分隔列表（與 allowed-tools 互補）。於 v2.1.152 新增。
model技能啟用時的模型覆蓋（例如 opus、sonnet）。
effort技能啟用時的努力程度 (Effort Level) 覆蓋：low、medium、high、xhigh 或 max — 在 Opus 5、Sonnet 5、Opus 4.8 和 Opus 4.7 上皆支援這五種設定。在所有支援努力程度的模型上，預設努力程度皆為 high，但 Opus 4.7 預設為 xhigh。
contextfork 表示在獨立的子代理脈絡 (Subagent Context) 中執行技能，擁有獨立的脈絡視窗。
agent當 context: fork 時的子代理類型（例如 Explore、Plan、general-purpose）。
background僅在使用 context: fork 時有意義。對於 context: fork 技能預設為 true，因此它們在背景執行；設定為 false 可改在前景執行。於 v2.1.218 新增。
shell用於 !`command` 替換和指令碼的 Shell：bash（預設）或 powershell。
hooks作用域限定於此技能生命週期的掛鉤 (Hooks)（格式與全域掛鉤相同）。
paths限制技能何時自動啟用的 Glob 模式。逗號分隔的字串或 YAML 列表。格式與特定路徑規則相同。
arguments宣告技能接受的引數，用於自動補全和引數替換。
metadata用於您自己記帳的自由格式鍵/值對（例如 version、author）。Claude Code 會直接傳遞它。
license技能的授權條款標識符（例如 MIT）。
compatibility最長 500 字元的自由文字相容性聲明。Claude Code 會接受但不會對其採取行動。

附註：上傳至 claude.ai 或透過 Skills API 建立的技能，僅 name、description、license、compatibility、metadata 和 allowed-tools 為有效欄位。此表中的其他欄位為 Claude Code 特定欄位。

自 v2.1.218 起，布林值 Frontmatter 欄位除 true/false 外，還接受 yes/no、on/off 和 1/0（不區分大小寫）。

技能內容類型 (Skill Content Types) ​

技能可以包含兩種類型的內容，每種類型適用於不同的目的：

參考內容 (Reference Content) ​

新增 Claude 套用到您當前工作的知識 — 慣例、模式、風格指南、領域知識。與您的對話脈絡內嵌執行。

yaml
---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

任務內容 (Task Content) ​

針對特定操作的逐步指示。通常透過 /skill-name 直接調用。

yaml
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

控制技能調用 (Controlling Skill Invocation) ​

預設情況下，您和 Claude 都可以調用任何技能。兩個 Frontmatter 欄位控制著三種調用模式：

Frontmatter您可以調用Claude 可以調用
(預設)是是
disable-model-invocation: true是否
user-invocable: false否是

對具有副作用的工作流程使用 disable-model-invocation: true：例如 /commit、/deploy、/send-slack-message。您不會希望 Claude 因為您的程式碼看起來準備好了而自行決定部署。

對無法作為指令執行的背景知識使用 user-invocable: false：例如 legacy-system-context 技能解釋了舊系統如何運作 — 這對 Claude 很實用，但對使用者來說並非一個有意義的操作。

字串替換 (String Substitutions) ​

技能支援動態值，這些值在技能內容傳遞給 Claude 之前會被解析：

變數 (Variable)說明 (Description)
$ARGUMENTS調用技能時傳遞的所有引數
$ARGUMENTS[N] 或 $N透過索引存取特定引數（從 0 開始）
${CLAUDE_SESSION_ID}當前工作階段 ID
${CLAUDE_SKILL_DIR}包含技能 SKILL.md 檔案的目錄
${CLAUDE_PROJECT_DIR}專案根目錄的絕對路徑。可在技能主體和 allowed-tools 中使用（v2.1.196）
${CLAUDE_EFFORT}當前的努力程度（low、medium、high、xhigh 或 max）。對技能行為進行分支很有用：例如 [ "${CLAUDE_EFFORT}" = "max" ] && deep_analysis（v2.1.120+）
!`command`動態脈絡注入 — 執行 Shell 指令並內嵌輸出

範例：

yaml
---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

執行 /fix-issue 123 會將 $ARGUMENTS 替換為 123。

堆疊技能 (Stacking Skills) ​

您可以在單次調用中堆疊斜線技能，例如 /code-review /fix-issue 123。自 v2.1.199 起，這會載入所有前置技能 — 第一個加上最多額外 5 個 — 並將末尾的引數 (123) 傳遞給每一個技能；在此之前僅載入第一個技能。若相同的技能被調用多次，其相同的內容會被去重（v2.1.202），而不會附加兩次。

注入動態脈絡 (Injecting Dynamic Context) ​

!`command` 語法會在技能內容傳送到 Claude 之前執行 Shell 指令：

yaml
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

指令會立即執行；Claude 只會看到最終輸出。預設情況下，指令在 bash 中執行。在 Frontmatter 中設定 shell: powershell 可改用 PowerShell。

在子代理中執行技能 (Running Skills in Subagents) ​

新增 context: fork 可在獨立的子代理脈絡中執行技能。技能內容會成為具有獨立脈絡視窗的專用子代理的任務，從而保持主對話的整潔。自 v2.1.218 起，對於 context: fork 的技能，background 預設為 true，因此它們在背景執行；在 Frontmatter 中設定 background: false 可以改在前景執行分叉技能。

v2.1.145 修復：使用 context: fork 的技能先前在極少數情況下可能會觸發無限重新調用迴圈。若您撰寫或依賴分叉技能，請升級至 v2.1.145+。

agent 欄位指定要使用的代理類型：

代理類型 (Agent Type)最適合 (Best For)
Explore唯讀研究、程式碼庫分析
Plan建立實作計畫
general-purpose需要所有工具的廣泛任務
自訂代理 (Custom agents)在您的配置中定義的專業代理

Frontmatter 範例：

yaml
---
context: fork
agent: Explore
---

完整技能範例：

yaml
---
name: topic-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

實用範例 (Practical Examples) ​

範例 1：程式碼審查技能 (Code Review Skill) ​

目錄結構：

~/.claude/skills/code-review-specialist/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

檔案： ~/.claude/skills/code-review-specialist/SKILL.md

yaml
---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization.
---

# Code Review Skill

This skill provides comprehensive code review capabilities focusing on:

1. **Security Analysis**
   - Authentication/authorization issues
   - Data exposure risks
   - Injection vulnerabilities
   - Cryptographic weaknesses

2. **Performance Review**
   - Algorithm efficiency (Big O analysis)
   - Memory optimization
   - Database query optimization
   - Caching opportunities

3. **Code Quality**
   - SOLID principles
   - Design patterns
   - Naming conventions
   - Test coverage

4. **Maintainability**
   - Code readability
   - Function size (should be < 50 lines)
   - Cyclomatic complexity
   - Type safety

## Review Template

For each piece of code reviewed, provide:

### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas

### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example

For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md).

範例 2：程式碼庫視覺化工具技能 (Codebase Visualizer Skill) ​

產生互動式 HTML 視覺化的技能：

目錄結構：

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

檔案： ~/.claude/skills/codebase-visualizer/SKILL.md

yaml
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view showing your project's file structure.

## Usage

Run the visualization script from your project root:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```

This creates `codebase-map.html` and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

打包的 Python 指令碼負責繁重的工作，而 Claude 處理編排。

範例 3：部署技能（僅限使用者調用）(Deploy Skill (User-Invoked Only)) ​

yaml
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status

範例 4：品牌語調技能（背景知識）(Brand Voice Skill (Background Knowledge)) ​

yaml
---
name: brand-voice
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content.
user-invocable: false
---

## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs

## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition

For templates, see [templates/](templates/).

範例 5：CLAUDE.md 產生器技能 (CLAUDE.md Generator Skill) ​

yaml
---
name: claude-md
description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding.
---

## Core Principles

**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation.

### The Golden Rules

1. **Less is More**: Keep under 300 lines (ideally under 100)
2. **Universal Applicability**: Only include information relevant to EVERY session
3. **Don't Use Claude as a Linter**: Use deterministic tools instead
4. **Never Auto-Generate**: Craft it manually with careful consideration

## Essential Sections

- **Project Name**: Brief one-line description
- **Tech Stack**: Primary language, frameworks, database
- **Development Commands**: Install, test, build commands
- **Critical Conventions**: Only non-obvious, high-impact conventions
- **Known Issues / Gotchas**: Things that trip up developers

範例 6：帶有指令碼的重構技能 (Refactoring Skill with Scripts) ​

目錄結構：

refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

檔案： refactor/SKILL.md

yaml
---
name: refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells.
---

# Code Refactoring Skill

A phased approach emphasizing safe, incremental changes backed by tests.

## Workflow

Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment →
Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation →
Phase 5: Incremental Implementation → Phase 6: Review & Iteration

## Core Principles

1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event

For code smell catalog, see [references/code-smells.md](references/code-smells.md).
For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md).

支援檔案 (Supporting Files) ​

技能除了 SKILL.md 之外，還可以在其目錄中包含多個檔案。這些支援檔案（範本、範例、指令碼、參考文件）可讓您保持主技能檔案的焦點，同時為 Claude 提供可按需載入的附加資源。

my-skill/
├── SKILL.md              # Main instructions (required, keep under 500 lines)
├── templates/            # Templates for Claude to fill in
│   └── output-format.md
├── examples/             # Example outputs showing expected format
│   └── sample-output.md
├── references/           # Domain knowledge and specifications
│   └── api-spec.md
└── scripts/              # Scripts Claude can execute
    └── validate.sh

支援檔案的指導方針：

  • 保持 SKILL.md 在 500 行以內。將詳細的參考材料、大型範例和規格移動到單獨的檔案中。
  • 從 SKILL.md 使用相對路徑引用附加檔案（例如 [API reference](references/api-spec.md)）。
  • 支援檔案在層級 3 載入（按需），因此在 Claude 實際讀取它們之前不會消耗脈絡。

管理技能 (Managing Skills) ​

檢視可用技能 (Viewing Available Skills) ​

直接詢問 Claude：

What Skills are available?

或者檢查檔案系統：

bash
# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/

技巧 (v2.1.121+)：輸入內容可過濾 /skills 互動式功能表 — 當安裝了許多技能時非常有用。

測試技能 (Testing a Skill) ​

兩種測試方式：

讓 Claude 自動調用它，方式是提出符合描述的請求：

Can you help me review this code for security issues?

或使用技能名稱直接調用：

/code-review-specialist src/auth/login.ts

附註：此本機技能安裝為 code-review-specialist，因此不會與內建的 /code-review 指令（在 Claude Code v2.1.146 中發布、重新命名自 /simplify 的指令）發生碰撞。若您將其複製到 ~/.claude/skills/code-review/，它將掩蔽內建指令 — 請保留 -specialist 後綴以避免該情況。

更新技能 (Updating a Skill) ​

直接編輯 SKILL.md 檔案，然後執行 /reload-skills（v2.1.152+）以重新掃描技能目錄。重啟 Claude Code 也可以運作，但非必需 — --add-dir 目錄中的技能會即時讀取，傳回 reloadSkills: true 的 SessionStart 掛鉤會觸發相同的重新掃描。

bash
# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md

限制 Claude 的技能存取 (Restricting Claude's Skill Access) ​

控制 Claude 可以調用哪些技能的三種方法：

在 /permissions 中停用所有技能：

# Add to deny rules:
Skill

允許或拒絕特定技能：

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

透過在其 Frontmatter 中新增 disable-model-invocation: true 來隱藏單個技能。

控制技能覆蓋行為 (skillOverrides) (Controlling Skill Override Behavior (skillOverrides)) ​

當專案技能與使用者技能共享相同名稱時，預設由專案勝出。skillOverrides 設定（v2.1.129+）允許您微調此行為。將其新增至 ~/.claude/settings.json 或專案 .claude/settings.json：

json
{
  "skillOverrides": "name-only"
}

接受的值：

值 (Value)行為 (Behavior)
"on"（預設）儲存庫技能可以覆蓋同名的使用者技能。
"off"完全停用覆蓋 — 使用者技能總是勝出。
"name-only"僅根據技能名稱進行覆蓋比對（忽略描述/來源）。
"user-invocable-only"僅可由使用者調用的技能可以被覆蓋 — 模型調用的技能總是來自其原始位置。

當團隊政策規定「使用者定義的技能必須始終優先」("off") 或「僅允許狹隘的基於名稱的覆蓋」("name-only") 時非常有用。

最佳實踐 (Best Practices) ​

1. 使描述更具體 (Make Descriptions Specific) ​

  • 不良（模糊）："Helps with documents"
  • 良好（具體）："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."

2. 保持技能專注 (Keep Skills Focused) ​

  • 一個技能 = 一種功能
  • ✅ "PDF form filling"
  • ❌ "Document processing"（過於寬泛）

3. 包含觸發詞 (Include Trigger Terms) ​

在描述中新增與使用者請求相比對的關鍵字：

yaml
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.

4. 保持 SKILL.md 在 500 行以內 (Keep SKILL.md Under 500 Lines) ​

將詳細的參考資料移動到 Claude 按需載入的單獨檔案中。

5. 引用支援檔案 (Reference Supporting Files) ​

markdown
## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

應該做的事 (Do's) ​

  • 使用清晰且具描述性的名稱
  • 包含完整的指示
  • 新增具體的範例
  • 打包相關的指令碼和範本
  • 使用真實場景進行測試
  • 記錄相依性 (Dependencies)

不該做的事 (Don'ts) ​

  • 不要為一次性任務建立技能
  • 不要重複現有的功能
  • 不要讓技能過於寬泛
  • 不要跳過 description 欄位
  • 在未經審查的情況下，不要安裝來自不可信來源的技能

疑難排解 (Troubleshooting) ​

快速參考 (Quick Reference) ​

問題 (Issue)解決方案 (Solution)
Claude 未使用技能使用觸發詞使描述更具體
找不到技能檔案驗證路徑：~/.claude/skills/name/SKILL.md
YAML 錯誤檢查 --- 標記、縮排，避免使用 Tab 鍵
技能衝突在描述中使用不同的觸發詞
指令碼未執行檢查權限：chmod +x scripts/*.py
Claude 看不到所有技能技能過多；檢查 /context 中的警告，然後執行 /skill-doctor (v2.1.252+) 查看哪些技能未使用以及它們的代價

技能未觸發 (Skill Not Triggering) ​

若 Claude 未在預期時使用您的技能：

  1. 檢查描述是否包含使用者自然會說出的關鍵字
  2. 驗證詢問 "What skills are available?" 時技能是否出現
  3. 嘗試重新表達您的請求以符合描述
  4. 使用 /skill-name 直接調用以進行測試

技能觸發過於頻繁 (Skill Triggers Too Often) ​

若 Claude 在您不希望時使用了您的技能：

  1. 使描述更加具體
  2. 新增 disable-model-invocation: true 以實現僅手動調用

Claude 看不到所有技能 (Claude Doesn't See All Skills) ​

技能描述在 1% 的脈絡視窗 上載入（備用值：8,000 個字元）。無論配額如何，每個條目上限為 250 個字元。執行 /context 檢查有關排除技能的警告。使用 SLASH_COMMAND_TOOL_CHAR_BUDGET 環境變數覆蓋配額。

安全性考量 (Security Considerations) ​

僅使用來自可信來源的技能。 技能透過指示和程式碼為 Claude 提供功能 — 惡意技能可以指示 Claude 以有害方式調用工具或執行程式碼。

關鍵安全性考量：

  • 徹底審查：審查技能目錄中的所有檔案
  • 外部來源存在風險：從外部 URL 擷取的技能可能會受到威脅
  • 工具濫用：惡意技能可以以有害方式調用工具
  • 視同安裝軟體：僅使用來自可信來源的技能

在技能中停用 Shell 替換 (Disabling shell substitution in skills) ​

技能支援 !`command` 語法，可在 Claude 看到提示詞之前將 Shell 指令的輸出注入提示詞中。在安全性敏感的環境（共享企業部署、鎖定的 CI Runner）中，您可以透過 disableSkillShellExecution 設定（於 v2.1.91 新增）完全停用此替換：

jsonc
// ~/.claude/settings.json or managed policy
{
  "disableSkillShellExecution": true
}

當 disableSkillShellExecution 為 true 時，技能中的任何 !`command` 標記都會保留為字面文字而非被執行 — 這樣可以在不停用技能本身的情況下，移除技能層級的 Shell 注入攻擊面。考慮將此與 allowedTools 允許列表結合使用以實現縱深防禦。

隱藏打包技能 (disableBundledSkills) (Hiding bundled skills (disableBundledSkills)) ​

disableBundledSkills 設定（於 v2.1.169 新增）可向模型隱藏隨 Claude Code 附帶的打包技能、工作流程和指令。當內建技能對特定專案來說屬於雜訊，或者為了減少模型的技能表面時使用它：

jsonc
// ~/.claude/settings.json or project .claude/settings.json
{
  "disableBundledSkills": true
}

等效的環境變數形式為：

bash
export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1

技能與其他功能的比較 (Skills vs Other Features) ​

功能 (Feature)調用方式 (Invocation)最適合 (Best For)
技能 (Skills)自動或 /name可重複使用的專業知識、工作流程
斜線指令 (Slash Commands)使用者發起的 /name快速捷徑（已合併至技能中）
子代理 (Subagents)自動委派隔離的任務執行
記憶體 (Memory) (CLAUDE.md)總是載入持久專案脈絡
MCP (Model Context Protocol)即時存取外部資料/服務
掛鉤 (Hooks)事件驅動自動化副作用

內建技能 (Bundled Skills) ​

Claude Code 隨附一組無需安裝即可使用的內建技能（以下列出最實用的技能；完整列表請參閱 指令參考）：

技能 (Skill)說明 (Description)
/batch <instruction>使用 git worktree 在整個程式碼庫中編排大規模平行變更
/claude-api載入 Claude API/SDK 參考資料；在匯入 anthropic/@anthropic-ai/sdk 時自動啟用
/dataviz圖表和儀表板設計指導，帶有可執行的調色盤驗證工具 (v2.1.198)
/debug [description]透過讀取偵錯記錄檔來排查當前工作階段的問題
/deep-research <topic>對某個主題執行深度研究（自 v2.1.218 起僅限顯式調用 — Claude 不會自行觸發此功能）
/fewer-permission-prompts掃描逐字稿並為常見的唯讀工具提出優先處理允許列表
/loop [interval] <prompt>按時間間隔重複執行提示詞（例如 /loop 5m check the deploy）
/run (v2.1.145+)啟動此專案的應用程式以查看執行的變更 — 尋找專案技能，否則根據專案類型回退至內建模式
/run-skill-generator (v2.1.145+)透過產生每個專案的技能教導 /run//verify 如何處理特定專案
/code-review [effort]在選定的努力程度下審查當前差異的正確性 Bug（例如 /code-review high）；傳入 --comment 以將發現作為內聯 PR 評論發布。這是一個與 /simplify（品質/重用清理，於 v2.1.154 重新拆分）不同的技能。（自 v2.1.215 起僅限顯式調用 — Claude 不會自行觸發此功能）自 v2.1.218 起作為背景子代理執行，因此審查工作不再佔用您的對話空間，且堆疊的斜線指令保持為其審查目標。
/simplify僅限清理的審查 — 重用、簡化、效率、高度 — 並套用修復。於 v2.1.154 中從 /code-review 重新拆分
/verify (v2.1.145+)建置、執行並觀察應用程式以確認修復有效（而不僅僅是測試通過）（自 v2.1.215 起僅限顯式調用 — Claude 不會自行觸發此功能）

這些技能開箱即用，不需要安裝或配置。它們遵循與自訂技能相同的 SKILL.md 格式。

共享技能 (Sharing Skills) ​

專案技能 (團隊共享) (Project Skills (Team Sharing)) ​

  1. 在 .claude/skills/ 中建立技能
  2. 提交至 git
  3. 團隊成員拉取變更 — 技能立即可用

個人技能 (Personal Skills) ​

bash
# Copy to personal directory
cp -r my-skill ~/.claude/skills/

# Make scripts executable
chmod +x ~/.claude/skills/my-skill/scripts/*.py

外掛程式散佈 (Plugin Distribution) ​

將技能打包在外掛程式的 skills/ 目錄中以進行更廣泛的散佈。

深入了解：技能集合與技能管理器 (Going Further: A Skill Collection and a Skill Manager) ​

一旦您開始認真建立技能，有兩件事會變得至關重要：經實證的技能庫以及管理它們的工具。

luongnv89/skills — 我在幾乎所有專案中日常使用的技能集合。亮點包括 logo-designer（即時產生專案標誌）和 ollama-optimizer（針對您的硬體調優本機 LLM 效能）。若您需要開箱即用的技能，這是一個極佳的起點。

luongnv89/asm — 代理技能管理器 (Agent Skill Manager)。處理技能開發、重複檢測和測試。asm link 指令讓您可以在任何專案中測試技能而無需複製檔案 — 一旦您擁有超過一把技能，這將是不可或缺的。

附加資源 (Additional Resources) ​

最後更新: 2026年9月6日 Claude Code 版本: 2.1.263 來源:

Released under the MIT License.

Copyright © 2026 Claude Code HowTo Guide