The Complete Guide to Claude Code Skills

Claude Code Skills 完全指南

Skills transform Claude from a general-purpose assistant into a specialized expert for your specific workflows. This guide explores everything you need to know about using Skills effectively — from understanding how they work internally to mastering best practices that dramatically improve activation rates.

Skills 能將 Claude 從一個通用助手轉變為針對你特定工作流程的專業專家。本指南探討你需要了解的關於有效使用 Skills 的一切——從理解它們的內部運作原理，到掌握能顯著提高觸發率的最佳實踐。

1. What Are Claude Code Skills?

1. 什麼是 Claude Code Skills？

1.1 Definition and Core Concepts

Claude Code Skills are reusable packages of instructions, templates, and resources that extend Claude's capabilities for specific tasks. Think of them as "specialized knowledge modules" that teach Claude how to complete particular types of work in a repeatable, consistent way.

Key characteristics:

Stored as directories containing a SKILL.md file (required) plus optional supporting files
Follow the Agent Skills open standard, making them compatible across multiple AI tools
Can be invoked manually with /skill-name or automatically by Claude when relevant
Support dynamic context injection, argument passing, and tool restrictions

Core philosophy: Skills enable progressive disclosure — information loads in stages as needed rather than consuming context upfront. A skill's description is always available to Claude so it knows what's possible, but the full skill content only loads when invoked.

1.1 定義與核心概念

Claude Code Skills 是可重複使用的指令、模板和資源包，用於擴展 Claude 在特定任務上的能力。可以把它們想像成「專業知識模組」，教導 Claude 如何以可重複、一致的方式完成特定類型的工作。

主要特點：

以目錄形式儲存，包含一個 SKILL.md 檔案（必需）加上可選的支援檔案
遵循 Agent Skills 開放標準，使其能跨多個 AI 工具相容
可以通過 /skill-name 手動觸發，或由 Claude 在相關時自動觸發
支援動態上下文注入、參數傳遞和工具限制

核心理念： Skills 實現了漸進式揭示 (progressive disclosure) ——資訊按需分階段載入，而不是一開始就消耗上下文。Skill 的描述始終對 Claude 可見，所以它知道有哪些能力可用，但完整的 skill 內容只在被調用時才會載入。

1.2 Two Main Types of Skills

Reference Content Skills — Add knowledge that Claude applies to current work:

yaml

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Always validate input parameters

Task Content Skills — Provide step-by-step instructions for specific actions (often with disable-model-invocation: true to prevent automatic triggering):

yaml

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to deployment
4. Verify health checks

1.2 兩種主要的 Skill 類型

參考內容型 Skills ——添加 Claude 應用到當前工作的知識：

yaml

---
name: api-conventions
description: 此程式碼庫的 API 設計模式
---
撰寫 API 端點時：
- 使用 RESTful 命名慣例
- 返回一致的錯誤格式
- 始終驗證輸入參數

任務內容型 Skills ——為特定動作提供逐步指令（通常會使用 disable-model-invocation: true 來防止自動觸發）：

yaml

---
name: deploy
description: 將應用程式部署到生產環境
disable-model-invocation: true
---
部署應用程式：
1. 運行測試套件
2. 建構應用程式
3. 推送到部署環境
4. 驗證健康檢查

1.3 Built-in Commands vs Custom Skills

It's important to understand the distinction:

Built-in commands (/help, /compact, /init, /context) are hardcoded into Claude Code and are NOT available through the Skill tool. These handle core functionality like session management and diagnostics.

Custom skills are user-created or distributed through plugins, templates, and organizations. They follow the SKILL.md format and support all frontmatter configuration options.

Type	Examples	Customizable	Scope
Built-in Commands	`/help`, `/compact`, `/init`	No	Global
Custom Skills	`/deploy`, `/review-pr`, `/explain-code`	Yes	Personal/Project/Enterprise

1.3 內建命令 vs 自訂 Skills

理解這個區別很重要：

內建命令（/help、/compact、/init、/context）是硬編碼在 Claude Code 中的，不能通過 Skill 工具使用。這些用於處理核心功能，如會話管理和診斷。

自訂 skills 是使用者建立的，或通過外掛、模板和組織分發的。它們遵循 SKILL.md 格式並支援所有 frontmatter 配置選項。

類型	範例	可自訂	範圍
內建命令	`/help`、`/compact`、`/init`	否	全域
自訂 Skills	`/deploy`、`/review-pr`、`/explain-code`	是	個人/專案/企業

2. How Skills Work Internally

2. Skills 的內部運作原理

2.1 The Skill Tool Mechanism

Claude Code implements skills through a Skill tool embedded with an <available_skills> list. Here's how the complete lifecycle works:

Discovery Phase: Claude Code scans skill directories at multiple scopes (enterprise, personal, project, plugin)
Description Loading: Skill descriptions are loaded into Claude's context so it knows what's available
Invocation: When triggered (by you or Claude), Claude sends a tool use with the skill name
Expansion: The system responds with the skill's full content, executing any dynamic commands first
Execution: Claude receives the fully-rendered prompt with actual data and executes the task

User Input → Claude interprets skill usage → Tool call with skill name + arguments
    ↓
System fetches SKILL.md + frontmatter → Executes dynamic commands
    ↓
Tool result returns skill content + base path
    ↓
Claude references bundled scripts relative to skill location
    ↓
Claude executes the task using skill instructions

2.1 Skill 工具機制

Claude Code 通過嵌入 <available_skills> 列表的 Skill 工具 來實現 skills。以下是完整的生命週期運作方式：

探索階段：Claude Code 在多個範圍（企業、個人、專案、外掛）掃描 skill 目錄
描述載入：Skill 描述被載入到 Claude 的上下文中，讓它知道有哪些可用
調用：當被觸發時（由你或 Claude），Claude 發送包含 skill 名稱的工具調用
展開：系統回應 skill 的完整內容，首先執行任何動態命令
執行：Claude 收到帶有實際資料的完全渲染提示詞並執行任務

使用者輸入 → Claude 解讀 skill 使用 → 帶有 skill 名稱 + 參數的工具調用
    ↓
系統獲取 SKILL.md + frontmatter → 執行動態命令
    ↓
工具結果返回 skill 內容 + 基礎路徑
    ↓
Claude 參考相對於 skill 位置的捆綁腳本
    ↓
Claude 使用 skill 指令執行任務

2.2 Progressive Disclosure Architecture

Skills use a two-tier loading system to optimize context usage:

Context Budget (15,000 character default)
├── Skill Descriptions (always loaded)
│   ├── explain-code: Explains code with diagrams
│   ├── fix-issue: Fix GitHub issues
│   └── deploy: Deploy to production
│
└── Full Skill Content (loaded on-demand)
    └── Only the invoked skill expands into context

This architecture means you can have dozens of skills available without overwhelming Claude's context window. The descriptions act as a "menu" that Claude can browse, but the full instructions only load when needed.

2.2 漸進式揭示架構

Skills 使用雙層載入系統來優化上下文使用：

上下文預算（預設 15,000 字元）
├── Skill 描述（始終載入）
│   ├── explain-code：用圖表解釋程式碼
│   ├── fix-issue：修復 GitHub issues
│   └── deploy：部署到生產環境
│
└── 完整 Skill 內容（按需載入）
    └── 只有被調用的 skill 才會展開到上下文中

這個架構意味著你可以有數十個可用的 skills 而不會壓垮 Claude 的上下文窗口。描述充當 Claude 可以瀏覽的「選單」，但完整指令只在需要時才會載入。

2.3 Dynamic Command Execution

Skills support the !`command` syntax for preprocessing, which allows injecting live data before Claude sees the prompt:

yaml

name: pr-summary
---
PR diff: !`gh pr diff`
PR comments: !`gh pr view --comments`
Changed files: !`gh pr diff --name-only`

Summarize this pull request...

What happens when this skill is invoked:

Commands execute immediately (before Claude sees anything)
Output replaces the placeholder
Claude receives the fully-rendered prompt with actual PR data

This is preprocessing, not something Claude executes. It ensures Claude always works with current, real data rather than stale information.

2.3 動態命令執行

Skills 支援 !`command` 語法進行預處理，允許在 Claude 看到提示詞之前注入即時資料：

yaml

name: pr-summary
---
PR diff: !`gh pr diff`
PR comments: !`gh pr view --comments`
Changed files: !`gh pr diff --name-only`

總結這個 pull request...

當這個 skill 被調用時會發生什麼：

命令立即執行（在 Claude 看到任何東西之前）
輸出替換佔位符
Claude 收到帶有實際 PR 資料的完全渲染提示詞

這是預處理，不是 Claude 執行的東西。它確保 Claude 始終使用當前的真實資料，而不是過時的資訊。

2.4 Context Window Management

When skills exceed the character budget, they may be excluded. Here's how to manage this:

bash

# Check for warnings about excluded skills
/context

# If skills are being excluded, increase the limit
export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

For expensive skills that require extensive exploration, use subagent context:

yaml

---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly using read-only tools

The context: fork setting runs the skill in an isolated subagent, preventing it from consuming your main conversation's context.

2.4 上下文窗口管理

當 skills 超過字元預算時，它們可能會被排除。以下是如何管理這個問題：

bash

# 檢查是否有關於被排除 skills 的警告
/context

# 如果 skills 被排除，增加限制
export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

對於需要大量探索的昂貴 skills，使用子代理上下文：

yaml

---
name: deep-research
context: fork
agent: Explore
---
使用唯讀工具徹底研究 $ARGUMENTS

context: fork 設定會在隔離的子代理中運行 skill，防止它消耗你主要對話的上下文。

3. Using Skills in Claude Code CLI

3. 在 Claude Code CLI 中使用 Skills

3.1 Skill Storage Locations

Where you store skills determines their scope:

Location	Path	Scope
Enterprise	Managed settings	Organization-wide
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	All your projects
Project	`.claude/skills/<skill-name>/SKILL.md`	This project only
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	Where plugin installed

Automatic nested discovery: When working in packages/frontend/, Claude also discovers skills in packages/frontend/.claude/skills/ — this supports monorepo structures.

Precedence hierarchy:

enterprise > personal > project > plugins (namespaced as plugin-name:skill-name)

3.1 Skill 儲存位置

你儲存 skills 的位置決定了它們的範圍：

位置	路徑	範圍
企業	受管理的設定	整個組織
個人	`~/.claude/skills/<skill-name>/SKILL.md`	你所有的專案
專案	`.claude/skills/<skill-name>/SKILL.md`	僅限此專案
外掛	`<plugin>/skills/<skill-name>/SKILL.md`	外掛安裝的地方

自動嵌套探索： 當在 packages/frontend/ 工作時，Claude 也會探索 packages/frontend/.claude/skills/ 中的 skills——這支援 monorepo 結構。

優先級層次：

企業 > 個人 > 專案 > 外掛（命名空間為 plugin-name:skill-name）

3.2 Creating Your First Skill

Step 1: Create the directory

bash

mkdir -p ~/.claude/skills/explain-code

Step 2: Write SKILL.md

yaml

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

Step 3: Test automatic invocation

bash

# Claude detects the description and offers to use the skill:
claude "How does this authentication code work?"

Step 4: Test direct invocation

bash

claude "/explain-code src/auth/login.ts"

3.2 建立你的第一個 Skill

步驟一：建立目錄

bash

mkdir -p ~/.claude/skills/explain-code

步驟二：撰寫 SKILL.md

yaml

---
name: explain-code
description: 用視覺圖表和類比來解釋程式碼。當解釋程式碼如何運作、教導程式碼庫、或使用者問「這是怎麼運作的？」時使用。
---

解釋程式碼時，始終包含：

1. **從類比開始**：將程式碼與日常生活中的事物比較
2. **畫一張圖**：使用 ASCII 藝術來展示流程、結構或關係
3. **逐步講解程式碼**：一步步解釋發生了什麼
4. **強調一個陷阱**：常見的錯誤或誤解是什麼？

保持解釋的對話性。對於複雜概念，使用多個類比。

步驟三：測試自動觸發

bash

# Claude 檢測到描述並提議使用該 skill：
claude "這段認證程式碼是怎麼運作的？"

步驟四：測試直接觸發

bash

claude "/explain-code src/auth/login.ts"

3.3 Using Arguments in Skills

All arguments:

yaml

$ARGUMENTS     # All arguments passed as a single string
ARGUMENTS: <value>  # Appended if $ARGUMENTS not found in content

Individual arguments:

yaml

$ARGUMENTS[0]  # First argument
$ARGUMENTS[1]  # Second argument
$N            # Shorthand: $0, $1, etc.

Example skill with multiple arguments:

yaml

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Usage: /migrate-component SearchBar React Vue

3.3 在 Skills 中使用參數

所有參數：

yaml

$ARGUMENTS     # 所有參數作為單一字串傳遞
ARGUMENTS: <value>  # 如果內容中沒有 $ARGUMENTS 則追加

單獨參數：

yaml

$ARGUMENTS[0]  # 第一個參數
$ARGUMENTS[1]  # 第二個參數
$N            # 簡寫：$0、$1 等

帶有多個參數的範例 skill：

yaml

---
name: migrate-component
description: 將元件從一個框架遷移到另一個框架
---

將 $0 元件從 $1 遷移到 $2。
保留所有現有行為和測試。

用法：/migrate-component SearchBar React Vue

3.4 Controlling Invocation Behavior

Setting	User Invokes	Claude Invokes	Description Loaded
(default)	Yes	Yes	Always in context
`disable-model-invocation: true`	Yes	No	Not loaded until you invoke
`user-invocable: false`	No	Yes	Always in context, Claude-only

Disable automatic invocation (manual only):

yaml

disable-model-invocation: true
# Use for: /deploy, /commit, /send-slack-message
# Prevents Claude from deciding to deploy on its own

Hide from user menu (Claude-only):

yaml

user-invocable: false
# Use for: background knowledge skills
# Claude can invoke, but /legacy-system-context isn't meaningful for users

Control tool access:

yaml

allowed-tools: Read, Grep, Glob
# Restricts Claude to read-only tools when this skill is active

3.4 控制觸發行為

設定	使用者觸發	Claude 觸發	描述載入
（預設）	是	是	始終在上下文中
`disable-model-invocation: true`	是	否	直到你觸發才載入
`user-invocable: false`	否	是	始終在上下文中，僅 Claude

禁用自動觸發（僅手動）：

yaml

disable-model-invocation: true
# 用於：/deploy、/commit、/send-slack-message
# 防止 Claude 自行決定部署

從使用者選單隱藏（僅 Claude）：

yaml

user-invocable: false
# 用於：背景知識 skills
# Claude 可以觸發，但 /legacy-system-context 對使用者沒有意義

控制工具存取：

yaml

allowed-tools: Read, Grep, Glob
# 當此 skill 啟動時，限制 Claude 只能使用唯讀工具

3.5 Adding Supporting Files

Keep SKILL.md under 500 lines; move detailed reference material to separate files:

my-skill/
├── SKILL.md (overview and navigation)
├── reference.md (API docs - loaded when needed)
├── examples.md (usage examples)
└── scripts/
    ├── helper.py
    └── validator.sh

Reference from SKILL.md:

markdown

## Additional Resources

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

Claude can read these files when needed, keeping the initial skill load lightweight.

3.5 添加支援檔案

保持 SKILL.md 在 500 行以下；將詳細參考資料移到單獨的檔案：

my-skill/
├── SKILL.md（概述和導航）
├── reference.md（API 文件 - 需要時載入）
├── examples.md（使用範例）
└── scripts/
    ├── helper.py
    └── validator.sh

從 SKILL.md 參考：

markdown

## 額外資源

- 完整 API 詳情，請參閱 [reference.md](reference.md)
- 使用範例，請參閱 [examples.md](examples.md)

Claude 可以在需要時讀取這些檔案，保持初始 skill 載入的輕量性。

4. Using Skills in Cursor IDE

4. 在 Cursor IDE 中使用 Skills

4.1 Current Status (2026)

Cursor IDE integration with Claude Code is in active development:

Cursor is VSCode-based, sharing many IDE capabilities with Claude Code's VS Code integration
Claude Code doesn't automatically detect Cursor as a compatible IDE yet
Anthropic's team is actively working on official Cursor support
The tools are designed to complement each other, not compete

4.2 Recommended Workflow Until Official Support

Option 1: Run Claude Code alongside Cursor

Cursor IDE (for real-time code assistance and editing)
     ↓
Claude Code terminal (for specialized skills and autonomous tasks)
     ↓
Shared ~/.claude/skills/ (skills available to both)

Option 2: Use Cursor's integrated terminal

Open Cursor's terminal panel
Run claude to start Claude Code session
Access all your skills via /skill-name commands

Option 3: Configure shared skill locations

Personal skills in ~/.claude/skills/ work with both tools
Project skills in .claude/skills/ are version-controlled and accessible from any environment

4.3 Why This Combination Works

Claude Code Strengths	Cursor Strengths
Autonomous multi-file operations	Real-time inline assistance
Complex refactoring tasks	Immediate code suggestions
Specialized skill workflows	Tab completion and autocomplete
CLI-based scripting	Visual diff and editing

4.1 目前狀態（2026）

Cursor IDE 與 Claude Code 的整合正在積極開發中：

Cursor 基於 VSCode，與 Claude Code 的 VS Code 整合共享許多 IDE 功能
Claude Code 尚未自動檢測 Cursor 為相容的 IDE
Anthropic 團隊正在積極開發官方 Cursor 支援
這些工具被設計為相互補充，而非競爭

4.2 在官方支援之前的建議工作流程

選項一：在 Cursor 旁邊運行 Claude Code

Cursor IDE（用於即時程式碼輔助和編輯）
     ↓
Claude Code 終端機（用於專業 skills 和自主任務）
     ↓
共享的 ~/.claude/skills/（skills 對兩者都可用）

選項二：使用 Cursor 的整合終端機

開啟 Cursor 的終端機面板
運行 claude 啟動 Claude Code 會話
通過 /skill-name 命令存取所有你的 skills

選項三：配置共享的 skill 位置

~/.claude/skills/ 中的個人 skills 與兩個工具都能使用
.claude/skills/ 中的專案 skills 是版本控制的，可從任何環境存取

4.3 為什麼這個組合有效

Claude Code 優勢	Cursor 優勢
自主多檔案操作	即時內聯輔助
複雜重構任務	即時程式碼建議
專業 skill 工作流程	Tab 補全和自動完成
基於 CLI 的腳本編寫	視覺化差異和編輯

5. Complete Frontmatter Reference

5. 完整的 Frontmatter 參考

5.1 All Available Fields

yaml

---
name: skill-name                    # Display name (lowercase, hyphens, max 64 chars)
description: Clear description      # When/why to use this skill (CRITICAL for auto-invocation)
argument-hint: [arg1] [arg2]       # Autocomplete hint shown in menu
disable-model-invocation: false     # true = manual only, prevents Claude from auto-invoking
user-invocable: true               # false = Claude-only, hidden from user menu
allowed-tools: Read, Grep, Glob   # Tools available without permission prompts
model: claude-opus-4.5             # Override model for this skill
context: fork                       # Run in isolated subagent context
agent: Explore                      # Subagent type (Explore, Plan, general-purpose)
hooks:                             # Skill-specific lifecycle hooks
  - matcher: always
    bash: ./hook-script.sh
---

5.2 Field Details

Field	Type	Required	Notes
`name`	string	No	Uses directory name if omitted
`description`	string	Recommended	Critical for auto-invocation — be specific!
`argument-hint`	string	No	Shown in `/` autocomplete menu
`disable-model-invocation`	boolean	No	Default: false
`user-invocable`	boolean	No	Default: true
`allowed-tools`	array	No	Comma-separated list with optional patterns
`model`	string	No	Overrides session model
`context`	string	No	Only value: `fork`
`agent`	string	No	Used with `context: fork`
`hooks`	object	No	Skill-scoped lifecycle hooks

5.3 Tool Restriction Patterns

yaml

allowed-tools: Read, Grep, Glob                    # Read-only skills
allowed-tools: Bash(gh *)                          # GitHub CLI only
allowed-tools: Bash(python *), Read               # Python scripts + reading
allowed-tools: Write, Edit, Bash                   # Full modification access
allowed-tools: Bash(npm *), Bash(yarn *)          # Package managers only

5.1 所有可用欄位

yaml

---
name: skill-name                    # 顯示名稱（小寫、連字號、最多 64 字元）
description: 清晰的描述             # 何時/為何使用此 skill（對自動觸發至關重要）
argument-hint: [arg1] [arg2]       # 選單中顯示的自動完成提示
disable-model-invocation: false     # true = 僅手動，防止 Claude 自動觸發
user-invocable: true               # false = 僅 Claude，從使用者選單隱藏
allowed-tools: Read, Grep, Glob   # 無需權限提示即可使用的工具
model: claude-opus-4.5             # 覆寫此 skill 的模型
context: fork                       # 在隔離的子代理上下文中運行
agent: Explore                      # 子代理類型（Explore、Plan、general-purpose）
hooks:                             # Skill 特定的生命週期鉤子
  - matcher: always
    bash: ./hook-script.sh
---

5.2 欄位詳情

欄位	類型	必需	備註
`name`	string	否	如果省略則使用目錄名稱
`description`	string	建議	對自動觸發至關重要——要具體！
`argument-hint`	string	否	顯示在 `/` 自動完成選單中
`disable-model-invocation`	boolean	否	預設：false
`user-invocable`	boolean	否	預設：true
`allowed-tools`	array	否	逗號分隔的列表，帶可選模式
`model`	string	否	覆寫會話模型
`context`	string	否	唯一值：`fork`
`agent`	string	否	與 `context: fork` 一起使用
`hooks`	object	否	Skill 範圍的生命週期鉤子

5.3 工具限制模式

yaml

allowed-tools: Read, Grep, Glob                    # 唯讀 skills
allowed-tools: Bash(gh *)                          # 僅 GitHub CLI
allowed-tools: Bash(python *), Read               # Python 腳本 + 讀取
allowed-tools: Write, Edit, Bash                   # 完整修改存取
allowed-tools: Bash(npm *), Bash(yarn *)          # 僅套件管理器

6. Best Practices for Skill Activation

6. Skill 觸發的最佳實踐

6.1 The Activation Problem

Research by Scott Spence identified a critical issue: skills often don't activate when they should. Testing showed that simple instruction-based skills only achieved about 20% activation rate.

Why simple instructions fail:

yaml

---
name: my-skill
description: Consider using this skill when relevant
---
# Result: Claude sees it, acknowledges it mentally, then ignores it

The problem is that Claude "sees" the skill description but doesn't feel compelled to use it. It's like knowing a tool exists versus actually reaching for it.

6.2 The Forced Evaluation Hook (84% Activation)

The most effective solution is to force Claude to explicitly evaluate each skill before proceeding:

json

// ~/.claude/settings.json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "always",
        "bash": "cat"
      }
    ]
  }
}

This hook intercepts user input and forces Claude to make a written commitment evaluating which skills apply. The act of writing out the evaluation dramatically increases follow-through.

6.3 Key Insight: Structured Commitment

Claude needs structured commitment rather than casual suggestions. The difference is:

Passive Suggestion	Structured Commitment
"You might want to use the explain-code skill"	"Before proceeding, explicitly state which skills apply and why"
Claude knows about it but ignores it	Claude commits in writing, then follows through
~20% activation	~84% activation

6.1 觸發問題

Scott Spence 的研究發現了一個關鍵問題：skills 經常在應該觸發時沒有觸發。測試顯示，簡單的指令型 skills 只達到約 20% 的觸發率。

為什麼簡單指令會失敗：

yaml

---
name: my-skill
description: 在相關時考慮使用此 skill
---
# 結果：Claude 看到它，在心裡承認它，然後忽略它

問題在於 Claude「看到」了 skill 描述，但沒有感到必須使用它的動力。這就像知道一個工具存在和實際去拿它之間的區別。

6.2 強制評估鉤子（84% 觸發率）

最有效的解決方案是強制 Claude 在繼續之前明確評估每個 skill：

json

// ~/.claude/settings.json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "always",
        "bash": "cat"
      }
    ]
  }
}

這個鉤子攔截使用者輸入，強制 Claude 做出書面承諾來評估哪些 skills 適用。寫出評估的行為大大增加了執行率。

6.3 關鍵洞察：結構化承諾

Claude 需要結構化承諾而非隨意建議。區別是：

被動建議	結構化承諾
「你可能想使用 explain-code skill」	「在繼續之前，明確說明哪些 skills 適用以及為什麼」
Claude 知道它但忽略它	Claude 書面承諾，然後執行
~20% 觸發率	~84% 觸發率

6.4 Writing Effective Descriptions

Make descriptions specific and action-oriented:

yaml

# Good — specific trigger words:
description: Explains code with visual diagrams. Use when explaining how something works, teaching about a codebase, or answering "how does this work?"

# Vague — Claude won't know when to use:
description: Helps explain code

Include trigger phrases that users would naturally say:

"how does this work"
"explain this code"
"what does this do"
"walk me through"

6.5 Naming Conventions

Use gerund form (verb + -ing) for clearer intent:

bash

# Clearer — describes the activity:
/explaining-code
/fixing-issues
/deploying-app
/reviewing-pr

# Less clear — just the action:
/explain
/fix
/deploy
/review

The gerund form clearly communicates what Claude will be doing, not just the action name.

6.4 撰寫有效的描述

讓描述具體且面向行動：

yaml

# 好——具體的觸發詞：
description: 用視覺圖表解釋程式碼。當解釋某物如何運作、教導程式碼庫、或回答「這是怎麼運作的？」時使用。

# 模糊——Claude 不知道何時使用：
description: 幫助解釋程式碼

包含使用者自然會說的觸發短語：

「這是怎麼運作的」
「解釋這段程式碼」
「這是做什麼的」
「帶我走一遍」

6.5 命名慣例

使用動名詞形式（動詞 + -ing）以更清楚的意圖：

bash

# 更清楚——描述活動：
/explaining-code
/fixing-issues
/deploying-app
/reviewing-pr

# 較不清楚——只是動作：
/explain
/fix
/deploy
/review

動名詞形式清楚地傳達 Claude 將正在做什麼，而不只是動作名稱。

7. Common Skill Patterns

7. 常見的 Skill 模式

7.1 Pattern: Task Skills with Side Effects

For skills that modify external state (deploy, commit, send messages):

yaml

---
name: deploy-production
description: Deploy the application to production
disable-model-invocation: true  # CRITICAL: prevents accidental deployment
allowed-tools: Bash(*)
---

## Deployment Checklist

1. Run full test suite: `npm test`
2. Build application: `npm run build`
3. Deploy to production: `./scripts/deploy.sh`
4. Verify health endpoint: `curl https://api.example.com/health`
5. Monitor logs for 5 minutes

Only proceed if all tests pass. Report any failures immediately.

7.2 Pattern: Reference Knowledge Skills

For injecting project-specific knowledge:

yaml

---
name: api-conventions
description: API design patterns for this project
user-invocable: false  # Claude-only, auto-applies when relevant
---

## API Response Format

All endpoints return:
```json
{
  "success": boolean,
  "data": object | null,
  "error": { "code": string, "message": string } | null
}

Error Codes

AUTH_001: Invalid token
AUTH_002: Token expired
VALIDATION_001: Missing required field


### 7.3 Pattern: Data Fetching Skills

For skills that need live data:

```yaml
---
name: pr-review
description: Review the current pull request
allowed-tools: Bash(gh *)
---

## Pull Request Context

Diff: !`gh pr diff`
Comments: !`gh pr view --comments`
CI Status: !`gh pr checks`

## Review Instructions

1. Analyze the diff for:
   - Logic errors
   - Security vulnerabilities
   - Performance issues
   - Missing tests

2. Check if CI is passing

3. Provide specific, actionable feedback

7.4 Pattern: Specialized Agent Skills

For complex research or exploration:

yaml

---
name: architecture-analysis
description: Deep analysis of codebase architecture
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Analyze the architecture of $ARGUMENTS:

1. Identify main components and their responsibilities
2. Map dependencies between modules
3. Find potential circular dependencies
4. Document entry points and data flow
5. Create ASCII diagram of architecture

Use only read operations. Do not modify any files.

7.1 模式：帶有副作用的任務 Skills

對於修改外部狀態的 skills（部署、提交、發送訊息）：

yaml

---
name: deploy-production
description: 將應用程式部署到生產環境
disable-model-invocation: true  # 關鍵：防止意外部署
allowed-tools: Bash(*)
---

## 部署清單

1. 運行完整測試套件：`npm test`
2. 建構應用程式：`npm run build`
3. 部署到生產環境：`./scripts/deploy.sh`
4. 驗證健康端點：`curl https://api.example.com/health`
5. 監控日誌 5 分鐘

只有在所有測試通過時才繼續。立即報告任何失敗。

7.2 模式：參考知識 Skills

用於注入專案特定知識：

yaml

---
name: api-conventions
description: 此專案的 API 設計模式
user-invocable: false  # 僅 Claude，在相關時自動應用
---

## API 回應格式

所有端點返回：
```json
{
  "success": boolean,
  "data": object | null,
  "error": { "code": string, "message": string } | null
}

錯誤代碼

AUTH_001：無效的 token
AUTH_002：Token 已過期
VALIDATION_001：缺少必要欄位


### 7.3 模式：資料獲取 Skills

對於需要即時資料的 skills：

```yaml
---
name: pr-review
description: 審查當前的 pull request
allowed-tools: Bash(gh *)
---

## Pull Request 上下文

Diff：!`gh pr diff`
評論：!`gh pr view --comments`
CI 狀態：!`gh pr checks`

## 審查指示

1. 分析 diff 尋找：
   - 邏輯錯誤
   - 安全漏洞
   - 效能問題
   - 缺少的測試

2. 檢查 CI 是否通過

3. 提供具體、可操作的回饋

7.4 模式：專業代理 Skills

用於複雜的研究或探索：

yaml

---
name: architecture-analysis
description: 深度分析程式碼庫架構
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

分析 $ARGUMENTS 的架構：

1. 識別主要元件及其職責
2. 映射模組之間的依賴關係
3. 找出潛在的循環依賴
4. 記錄入口點和資料流
5. 建立架構的 ASCII 圖表

僅使用讀取操作。不要修改任何檔案。

8. Troubleshooting Common Issues

8. 常見問題排解

8.1 Problem: Skill Never Activates

Symptoms: You expect Claude to use a skill, but it never does.

Solutions:

Check description specificity — Is it vague? Add specific trigger words.
Use forced evaluation hook — Increases activation from ~20% to ~84%.
Verify skill is loaded — Run /context to see if it's in the budget.
Check for name conflicts — Enterprise/personal skills may override project skills.

8.2 Problem: Skill Activates Too Often

Symptoms: Claude uses a skill when you don't want it to.

Solutions:

Make description more specific — Narrow the trigger conditions.
Add disable-model-invocation: true — Require manual invocation.
Use conditional language — "Only use when the user explicitly asks to..."

8.3 Problem: Context Overload

Symptoms: /context shows warnings about excluded skills.

Solutions:

bash

# Increase budget
export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

# Or use subagent context for expensive skills
context: fork
agent: Explore

8.4 Problem: Arguments Not Passing

Symptoms: Skill receives empty or incorrect arguments.

Solutions:

Check syntax — Use $ARGUMENTS or $0, $1, etc.
Verify quotes — /skill "arg with spaces" keeps spaces together.
Add argument-hint — Helps users understand expected format.

8.5 Problem: Dynamic Commands Failing

Symptoms: !`command` shows errors or empty output.

Solutions:

Check command availability — Is gh installed? Is the user logged in?
Test command manually — Run the command directly in terminal first.
Add error handling — Use !command || echo "fallback"``.

8.1 問題：Skill 從不觸發

症狀： 你期望 Claude 使用某個 skill，但它從未使用。

解決方案：

檢查描述的具體性 ——是否模糊？添加具體的觸發詞。
使用強制評估鉤子 ——將觸發率從 ~20% 提升到 ~84%。
驗證 skill 已載入 ——運行 /context 查看是否在預算內。
檢查名稱衝突 ——企業/個人 skills 可能覆蓋專案 skills。

8.2 問題：Skill 觸發太頻繁

症狀： Claude 在你不想要時使用 skill。

解決方案：

讓描述更具體 ——縮小觸發條件。
添加 disable-model-invocation: true ——要求手動觸發。
使用條件語言 ——「只有當使用者明確要求時才使用...」

8.3 問題：上下文超載

症狀： /context 顯示關於被排除 skills 的警告。

解決方案：

bash

# 增加預算
export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

# 或對昂貴的 skills 使用子代理上下文
context: fork
agent: Explore

8.4 問題：參數未傳遞

症狀： Skill 收到空的或不正確的參數。

解決方案：

檢查語法 ——使用 $ARGUMENTS 或 $0、$1 等。
驗證引號 ——/skill "arg with spaces" 保持空格在一起。
添加 argument-hint ——幫助使用者理解預期格式。

8.5 問題：動態命令失敗

症狀： !`command` 顯示錯誤或空輸出。

解決方案：

檢查命令可用性 ——gh 是否已安裝？使用者是否已登入？
手動測試命令 ——先在終端機中直接運行命令。
添加錯誤處理 ——使用 !`command || echo "fallback"`。

9. Popular Skills and Resources

9. 熱門 Skills 與資源

9.1 Recommended Skills for All Developers

Skill	Purpose	Source
Superpowers	Enforces planning before coding	Community
planning-with-files	Prevents context loss in long projects	Community
pr-summary	Summarizes GitHub pull requests	Built-in pattern
fix-issue	GitHub-integrated issue fixing	Built-in pattern

9.2 Official Resources

Claude Code Skills Docs — Official comprehensive guide
Anthropic Skills Repository — Example implementations
Agent Skills Specification — Cross-platform standard

9.3 Community Collections

VoltAgent/awesome-agent-skills — 200+ community skills
travisvn/awesome-claude-skills — Curated list
alirezarezvani/claude-skills — Real-world examples

9.4 Installing Skills from Community

bash

# Clone a skill repository
git clone https://github.com/example/skill-repo ~/.claude/skills/skill-name

# Or use plugin installation
/plugin install <github-repo-url>

9.1 推薦給所有開發者的 Skills

Skill	用途	來源
Superpowers	強制在編碼前進行規劃	社群
planning-with-files	防止長期專案中的上下文丟失	社群
pr-summary	總結 GitHub pull requests	內建模式
fix-issue	GitHub 整合的問題修復	內建模式

9.2 官方資源

Claude Code Skills 文件 — 官方完整指南
Anthropic Skills 儲存庫 — 範例實作
Agent Skills 規範 — 跨平台標準

9.3 社群收藏

VoltAgent/awesome-agent-skills — 200+ 社群 skills
travisvn/awesome-claude-skills — 精選列表
alirezarezvani/claude-skills — 真實世界範例

9.4 從社群安裝 Skills

bash

# 複製 skill 儲存庫
git clone https://github.com/example/skill-repo ~/.claude/skills/skill-name

# 或使用外掛安裝
/plugin install <github-repo-url>

10. Summary: Key Takeaways

10. 總結：關鍵要點

Core Principles

Progressive Disclosure — Descriptions always in context, full content on-demand
Auto-Invocation — Claude loads relevant skills automatically when your request matches
Composability — Skills can be chained and combined for complex workflows
Version Control — Project skills live in .claude/skills/ and get committed to Git
Scope Hierarchy — Enterprise > Personal > Project, with plugins namespaced separately

Activation Success Formula

Specific Description + Trigger Words + Forced Evaluation Hook = High Activation Rate

Quick Start Checklist

[ ] Create ~/.claude/skills/my-skill/SKILL.md for personal skills
[ ] Create .claude/skills/my-skill/SKILL.md for project skills
[ ] Write specific, action-oriented descriptions with trigger words
[ ] Use disable-model-invocation: true for dangerous operations
[ ] Add allowed-tools to restrict capabilities when appropriate
[ ] Monitor skill loading with /context
[ ] Consider forced evaluation hooks for critical skills

Remember

Skills are not just about teaching Claude new commands — they're about encoding your team's best practices, workflows, and domain knowledge into reusable, consistent behaviors. The most valuable skills aren't generic utilities; they're the ones that capture how your team works best.

核心原則

漸進式揭示 ——描述始終在上下文中，完整內容按需載入
自動觸發 ——當你的請求匹配時，Claude 自動載入相關 skills
可組合性 ——Skills 可以串聯和組合用於複雜工作流程
版本控制 ——專案 skills 位於 .claude/skills/ 並提交到 Git
範圍層次 ——企業 > 個人 > 專案，外掛單獨命名空間

觸發成功公式

具體描述 + 觸發詞 + 強制評估鉤子 = 高觸發率

快速入門清單

[ ] 為個人 skills 建立 ~/.claude/skills/my-skill/SKILL.md
[ ] 為專案 skills 建立 .claude/skills/my-skill/SKILL.md
[ ] 撰寫具體、面向行動、帶觸發詞的描述
[ ] 對危險操作使用 disable-model-invocation: true
[ ] 在適當時添加 allowed-tools 來限制能力
[ ] 用 /context 監控 skill 載入狀態
[ ] 對關鍵 skills 考慮使用強制評估鉤子

記住

Skills 不只是教 Claude 新命令——它們是關於將你團隊的最佳實踐、工作流程和領域知識編碼成可重複使用、一致的行為。最有價值的 skills 不是通用工具；而是那些捕捉你的團隊如何最佳工作的 skills。

The Complete Guide to Claude Code Skills ​

Claude Code Skills 完全指南 ​

1. What Are Claude Code Skills? ​

1. 什麼是 Claude Code Skills？ ​

1.1 Definition and Core Concepts ​

1.1 定義與核心概念 ​

1.2 Two Main Types of Skills ​

1.2 兩種主要的 Skill 類型 ​

1.3 Built-in Commands vs Custom Skills ​

1.3 內建命令 vs 自訂 Skills ​

2. How Skills Work Internally ​

2. Skills 的內部運作原理 ​

2.1 The Skill Tool Mechanism ​

2.1 Skill 工具機制 ​

2.2 Progressive Disclosure Architecture ​

2.2 漸進式揭示架構 ​

2.3 Dynamic Command Execution ​

2.3 動態命令執行 ​

2.4 Context Window Management ​

2.4 上下文窗口管理 ​

3. Using Skills in Claude Code CLI ​

3. 在 Claude Code CLI 中使用 Skills ​

3.1 Skill Storage Locations ​

3.1 Skill 儲存位置 ​

3.2 Creating Your First Skill ​

3.2 建立你的第一個 Skill ​

3.3 Using Arguments in Skills ​

3.3 在 Skills 中使用參數 ​

3.4 Controlling Invocation Behavior ​

3.4 控制觸發行為 ​

3.5 Adding Supporting Files ​

3.5 添加支援檔案 ​

4. Using Skills in Cursor IDE ​

4. 在 Cursor IDE 中使用 Skills ​

4.1 Current Status (2026) ​

4.2 Recommended Workflow Until Official Support ​

4.3 Why This Combination Works ​

4.1 目前狀態（2026） ​

4.2 在官方支援之前的建議工作流程 ​

4.3 為什麼這個組合有效 ​

5. Complete Frontmatter Reference ​

5. 完整的 Frontmatter 參考 ​

5.1 All Available Fields ​

5.2 Field Details ​

5.3 Tool Restriction Patterns ​

5.1 所有可用欄位 ​

5.2 欄位詳情 ​

5.3 工具限制模式 ​

6. Best Practices for Skill Activation ​

6. Skill 觸發的最佳實踐 ​

6.1 The Activation Problem ​

6.2 The Forced Evaluation Hook (84% Activation) ​

6.3 Key Insight: Structured Commitment ​

6.1 觸發問題 ​

6.2 強制評估鉤子（84% 觸發率） ​

6.3 關鍵洞察：結構化承諾 ​

6.4 Writing Effective Descriptions ​

6.5 Naming Conventions ​

6.4 撰寫有效的描述 ​

6.5 命名慣例 ​

7. Common Skill Patterns ​

7. 常見的 Skill 模式 ​

7.1 Pattern: Task Skills with Side Effects ​

7.2 Pattern: Reference Knowledge Skills ​

Error Codes ​

7.4 Pattern: Specialized Agent Skills ​

7.1 模式：帶有副作用的任務 Skills ​

7.2 模式：參考知識 Skills ​

錯誤代碼 ​

7.4 模式：專業代理 Skills ​

8. Troubleshooting Common Issues ​

8. 常見問題排解 ​

8.1 Problem: Skill Never Activates ​

8.2 Problem: Skill Activates Too Often ​

8.3 Problem: Context Overload ​

8.4 Problem: Arguments Not Passing ​

8.5 Problem: Dynamic Commands Failing ​

8.1 問題：Skill 從不觸發 ​

8.2 問題：Skill 觸發太頻繁 ​

8.3 問題：上下文超載 ​

The Complete Guide to Claude Code Skills

Claude Code Skills 完全指南

1. What Are Claude Code Skills?

1. 什麼是 Claude Code Skills？

1.1 Definition and Core Concepts

1.1 定義與核心概念

1.2 Two Main Types of Skills

1.2 兩種主要的 Skill 類型

1.3 Built-in Commands vs Custom Skills

1.3 內建命令 vs 自訂 Skills

2. How Skills Work Internally

2. Skills 的內部運作原理

2.1 The Skill Tool Mechanism

2.1 Skill 工具機制

2.2 Progressive Disclosure Architecture

2.2 漸進式揭示架構

2.3 Dynamic Command Execution

2.3 動態命令執行

2.4 Context Window Management

2.4 上下文窗口管理

3. Using Skills in Claude Code CLI

3. 在 Claude Code CLI 中使用 Skills

3.1 Skill Storage Locations

3.1 Skill 儲存位置

3.2 Creating Your First Skill

3.2 建立你的第一個 Skill

3.3 Using Arguments in Skills

3.3 在 Skills 中使用參數

3.4 Controlling Invocation Behavior

3.4 控制觸發行為

3.5 Adding Supporting Files

3.5 添加支援檔案

4. Using Skills in Cursor IDE

4. 在 Cursor IDE 中使用 Skills

4.1 Current Status (2026)

4.2 Recommended Workflow Until Official Support

4.3 Why This Combination Works

4.1 目前狀態（2026）

4.2 在官方支援之前的建議工作流程

4.3 為什麼這個組合有效

5. Complete Frontmatter Reference

5. 完整的 Frontmatter 參考

5.1 All Available Fields

5.2 Field Details

5.3 Tool Restriction Patterns

5.1 所有可用欄位

5.2 欄位詳情

5.3 工具限制模式

6. Best Practices for Skill Activation

6. Skill 觸發的最佳實踐

6.1 The Activation Problem

6.2 The Forced Evaluation Hook (84% Activation)

6.3 Key Insight: Structured Commitment

6.1 觸發問題

6.2 強制評估鉤子（84% 觸發率）

6.3 關鍵洞察：結構化承諾

6.4 Writing Effective Descriptions

6.5 Naming Conventions

6.4 撰寫有效的描述

6.5 命名慣例

7. Common Skill Patterns

7. 常見的 Skill 模式

7.1 Pattern: Task Skills with Side Effects

7.2 Pattern: Reference Knowledge Skills

Error Codes

7.4 Pattern: Specialized Agent Skills

7.1 模式：帶有副作用的任務 Skills

7.2 模式：參考知識 Skills

錯誤代碼

7.4 模式：專業代理 Skills

8. Troubleshooting Common Issues

8. 常見問題排解

8.1 Problem: Skill Never Activates

8.2 Problem: Skill Activates Too Often

8.3 Problem: Context Overload

8.4 Problem: Arguments Not Passing

8.5 Problem: Dynamic Commands Failing

8.1 問題：Skill 從不觸發

8.2 問題：Skill 觸發太頻繁

8.3 問題：上下文超載