看完這份Claude code Skill的官方規範，我把 8 個 Skill 全重構了

作者：AI漫遊朝朝
日期：2026年5月6日 上午5:15
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

Claude Code Skill嘅關鍵唔係指令內容，而係description同fork模式，掌握呢兩個設計原則先發揮到真正威力。

整理版摘要

呢篇文章係作者分享佢寫咗8個Skill但Claude Code唔主動調用嘅親身經驗。佢發現問題唔係Prompt寫得唔好，而係description寫得唔清楚同埋冇用fork模式。於是佢翻曬官方文檔，發現大部分人對Skill嘅理解停留喺「快捷指令」，但官方規範背後係一套完整嘅AI工作流設計框架。

作者整理咗幾個核心概念：Skill唔係一個文件而係一個目錄，reference資料可以按需加載；description嘅前250個字符決定Claude會唔會自動調用你個Skill，寫description係寫路由規則；fork模式可以將Skill放喺獨立子Agent運行，唔會蠶食主對話嘅上下文，係複雜任務嘅生存策略。

整體結論係：寫Skill唔係寫死指令，而係設計AI嘅工作流程。理解三層加載機制、觸發控制、fork隔離同動態注入呢啲設計原則，先發揮到Skill嘅真正威力。作者最後仲分享咗個簡單優化方法：將官方文檔直接交俾Claude叫佢幫手重構自己啲Skill。

  • Skill本質係AI工作流框架，唔係快捷指令，關鍵喺description同context設計。
  • description前250字符要講清做咩同咩時候觸發，Claude根據呢段文字決定係咪自動調用。
  • fork模式令Skill喺獨立子Agent運行，唔佔主對話上下文，係複雜任務嘅生存策略。
  • 用context: fork可以避免上下文爆炸，inline模式適合需要對話歷史嘅場景。
  • 立即檢查自己Skill嘅description，確保前250字符包含核心觸發條件；將需要大量token嘅任務改用fork模式。
結構示例

內容結構

內容結構 text 
my-skill/├──
SKILL.md          # 必須——核心指令├── references/       # 可選——參考資料，被引用時才加載├── assets/           # 可選——模板、圖片等└── scripts/          # 可選——可執行腳本
整理重點

Skill唔係一個文件，係一個目錄結構

大部分人以為Skill就係一個markdown文件放喺.claude/skills/就算。但官方定義嘅Skill係一個目錄，入面有SKILL.md核心指令，仲有可選嘅references、assets、scripts資料夾。

SKILL.md正文要控制在500行以內，大約1500-2000詞

呢個結構隱藏咗一個關鍵設計：references目錄嘅資料係按需加載。如果你將所有參考資料塞曬入正文，每次調用都會燒token；放喺references/入面，只有Claude主動引用先會讀取。就好似寫code要拆函數，唔好整幾千行嘅上帝檔案。

  1. 1 my-skill/ ├── SKILL.md （必須） ├── references/ （按需加載） ├── assets/ （模板圖片） └── scripts/ （可執行腳本）
  2. 2 正文只放核心指令，參考資料外掛，跟寫code一樣要拆分邏輯。
整理重點

三層加載機制：description係你嘅路由規則

Claude Code對Skill採用三層漸進式加載。Level 1係元數據（name+description），每次會話一啟動就入上下文；Level 2係SKILL.md全文，只有被調用先注入；Level 3係目錄資源，正文引用先讀取。

description嘅前250字符必須講清楚兩件事：呢個Skill做咩，同咩時候應該用佢

所有Skill嘅description共享一個上下文預算，默認係上下文窗口嘅1%（約2000 tokens）。如果你有20個Skill，每個description得返約100 tokens。所以description要極致精簡，用動詞開頭，直接寫觸發條件，唔好寫「呢個Skill可以幫你...」呢類廢話。

  • Level 1：元數據（name + description）— 會話啟動時入上下文
  • Level 2：SKILL.md正文 — 被調用時注入
  • Level 3：references目錄資源 — 正文引用先讀取
整理重點

fork vs inline：揀錯模式等於白寫

默認Skill喺當前會話運行（inline），繼承你完整對話歷史，同時佔用主對話嘅token配額。但如果你將context設為fork，Skill會喺一個獨立子Agent入面運行，唔影響主對話嘅上下文。

fork模式係上下文窗口嘅生存策略，唔係可選功能

咩情況一定要用fork？複雜任務例如代碼審查、批量重構、全項目搜索，呢啲任務本身消耗大量token，如果仲用inline模式，主對話好快會因為上下文爆滿而「失憶」。簡單判斷法則：如果指令本身已經包含完成任務所需嘅全部信息，用fork；如果指令需要依賴對話歷史先理解，用inline。

  • fork模式：獨立窗口，唔繼承對話歷史，適用獨立任務
  • inline模式：繼承完整歷史，佔用主對話token，適用需要上下文嘅場景
整理重點

Description預算同Shell預處理：動態工作流嘅關鍵

description預算係官方規範嘅隱藏約束。所有Skill嘅description共享1%嘅上下文窗口，每個description喺列表中會被截斷為250字符。呢個限制逼你要將核心觸發條件放喺最前面。

用動詞開頭，直接寫觸發條件，例如「當用戶提到...時觸發」

另外一個被低估嘅功能係Shell預處理。正文支援 !`<command>` 語法，喺發送俾Claude之前執行shell命令，將輸出替換到正文入面。例如 !`git status --short` 可以自動讀取Git狀態。呢個功能令Skill從靜態指令變成動態工作流。

  1. 1 description預算默認為上下文窗口1%，每個description截斷為250字符
  2. 2 前250字符必須包含核心觸發條件，用動詞開頭，唔好寫客套話
  3. 3 Shell預處理可用 !`<command>` 或 ```! 開頭嘅程式碼塊
  4. 4 可透過disableSkillShellExecution全局禁用此功能

你寫咗 8 個 Skill，但 Claude 從來唔會主動 call 其中 5 個。

你以為係 prompt 寫得唔好，其實係你冇寫 description。

你發現每次 call 一次 Skill 上下文就爆曬，其實係你冇用 context: fork。

我最近睇完咗 Claude Code 官方 Skills 文檔，發現大部分人對 Skill 嘅理解仲停留喺「呢個就係個快捷指令」度。但官方規範入面藏咗一套完整嘅 AI 工作流設計框架。

Image

今日將呢套規範拆開嚟講。唔講方法論，淨係講官方文檔入面寫咗但你大概冇留意到嘅細節。


一、Skill 唔係一個文件，而係一個目錄

大部分人理解嘅 Skill：寫個 markdown，放 .claude/skills/ 度，搞掂。

官方定義嘅 Skill 係一個目錄結構：

my-skill/
├── SKILL.md          # 必須——核心指令
├── references/       # 可選——參考資料，被引用時才加載
├── assets/           # 可選——模板、圖片等
└── scripts/          # 可選——可執行腳本

呢度藏咗一個關鍵設計意圖：references 目錄係按需加載嘅。

咩意思？你將所有參考資料塞曬入 SKILL.md 正文度，每次 call Skill 都會將呢啲內容注入上下文，白白燒 token。但如果擺喺 references/ 度，只會喺 Claude 主動引用嗰陣先讀取。

官方建議：正文控制喺 500 行以內（大約 1500-2000 詞），參考資料外掛。呢個同寫 code 一樣——function 要短，邏輯要拆開，唔好搞幾千行嘅上帝文件。


二、三層加載機制：description 係你 Skill 嘅名片

呢個係成份規範入面最被低估嘅設計。

Claude Code 對 Skill 採用三層漸進式加載：


呢個意味住咩？

你寫咗 10 個 Skill，會話一啟動，10 個 description 全部入曬 Claude 嘅上下文，佔用大約 1000 tokens。所有 Skill 嘅 description 共享一個上下文預算——默認係上下文窗口嘅 1%，fallback 係 8000 字符。

但更加關鍵嘅係：每個 Skill 嘅 description 喺列表中會被截斷做 250 字符。

所以 description 嘅前 250 個字符，一定要講清楚兩件事：

  1. 1.呢個 Skill 做咩
  2. 2.幾時要用佢

寫 description 唔係喺寫簡介，而係喺寫路由規則。Claude 根據呢段文字決定係咪要自動 call 你嘅 Skill。寫得唔清楚 = Claude 揾唔到 = 白寫咗。

❌ description: 一個幫助寫代碼的工具
✅ description: 根據功能需求生成完整的 React 組件代碼。當用戶提到"創建組件"、"寫個頁面"、"新增功能模塊"時觸發。

三、12 個 Frontmatter 字段，核心得 4 組

官方定義咗 12 個可選 frontmatter 字段。睇落嚇人，其實按功能分得 4 組：

第一組：標識（同系統講你係邊個）

name: my-skill          # 也是 /slash-command 的名稱
description: ...        # 上面講過了，必寫
argument-hint: "[參數]"  # 自動補全時的提示

第二組：觸發控制（決定邊個可以令 Skill 運行）

disable-model-invocation: false  # true = Claude 不能自動調用
user-invocable: true             # false = 用戶看不到，只有 Claude 能調
paths: "*.md, src/**/*.ts"       # 只在處理匹配文件時才激活

呢三個字段組合出咗三種模式：


user-invocable: false 呢個用法好少人用，但佢好妙——你可以寫一個用戶完全見唔到嘅 Skill，叫 Claude 喺背景自動調用，例如自動格式化輸出、自動檢查文件結構。呢種係一種「隱形工作流」嘅設計思路。

第三組：執行模式（Skill 喺邊度行）

context: fork           # fork = 獨立子 Agent，省略 = 當前會話（inline）
agent: "general-purpose"  # 子 Agent 類型，可選 Explore / Plan / 自定義
allowed-tools: Read Write Edit  # Skill 激活時免詢問的工具
model: sonnet           # 覆蓋模型
effort: medium          # 覆蓋 effort

呢組係成份規範入面實戰價值最高嘅部分，會分開講。

第四組：其他

hooks:                  # Skill 級鈎子
shell: bash             # 預處理命令的 shell

四、fork vs inline：揀錯等於白寫

呢個係我見過最多人中招嘅位。

默認情況下，Skill 喺當前會話入面運行（inline）——佢繼承你嘅完整對話歷史，佔用主對話嘅 token 配額。

但當你設定 context: fork 嗰陣，Skill 會喺一個獨立嘅子 Agent 入面運行：


幾時一定要用 fork？

當你寫咗一個複雜嘅 Skill——例如 code review、批量重構、全項目搜索——呢啲任務本身就會消耗大量 token。如果行喺 inline 模式，你主對話嘅上下文會被嚴重擠佔，傾嚇傾嚇 Claude 就開始「忘記」之前講過咩。

fork 模式唔係可選功能，而係上下文窗口嘅生存策略。

幾時一定要用 inline？

當 Skill 需要你之前嘅對話信息——例如「幫我將頭先討論嘅嗰個功能寫出嚟」——呢種情況 fork 模式拎唔到對話歷史，根本冇辦法工作。

一個簡單判斷法則：如果指令本身就包含咗完成任務所需嘅全部信息，用 fork；如果指令依賴對話上下文嚟理解，用 inline。


五、Description 預算：一個被你忽略嘅稀缺資源

前面提過，所有 Skill 嘅 description 共享一個上下文預算。

呢個預算默認係上下文窗口嘅 1%。以 Claude Sonnet 嘅 200K 窗口為例，1% 就係 2000 個 token。

睇落唔細，但如果你有 20 個 Skill，每個 description 就得返 100 tokens。而 100 tokens 大約 75 個中文字。

所以 description 一定要極致精簡。呢個係官方規範嘅隱藏約束：唔係你想寫幾詳細就寫幾詳細，而係預算決定咗你一定要精簡。

策略：


  • 前 250 字符內一定要包含核心觸發條件（因為列表截斷）

  • 用動詞開頭：當用戶提到...嗰陣觸發

  • 唔好寫廢話：刪咗「呢個 Skill 可以幫到你...」之類嘅客套話

最後：一個被低估嘅功能——Shell 預處理

正文支援 !`<command>` 語法，喺傳送畀 Claude 之前執行 shell 命令，將輸出替換返落正文度。

當前項目的 Git 狀態：
!`git status --short`

呢個意味住你嘅 Skill 可以係動態的——行一次命令，讀取當前環境狀態，生成對應嘅上下文。例如：


  • 自動讀取 package.json 判斷項目技術棧

  • 檢查最近修改嘅文件列表

  • 獲取當前分支名同未提交嘅改動

呢個功能令 Skill 由「靜態指令」變咗做「動態工作流」。


Claude Code 嘅 Skill 規範，本質上係一套 AI 工作流設計框架。三層加載、fork 隔離、動態注入——呢啲唔係一個文件後綴可以概括嘅。

寫好 Skill 嘅關鍵唔係寫更多指令，而係理解你嘅 Skill 喺咩時候被加載、以咩方式運行、佔用幾多上下文。

description 嘅前 250 個字符，決定 Claude 會唔會用你嘅 Skill。

context: fork 唔係選項，而係生存策略。

寫 Skill 唔係喺寫指令，而係喺設計一個 AI 嘅工作流。

我都根據官方手冊優化我嘅 skill，令 skill 更好用咗。

優化方式好簡單，直接將官方文檔畀我嘅蝦，叫佢優化對應嘅 skill 就得。

Image

原文

# Claude Code Skill 官方規範

> 來源：code.claude.com/docs/en/skills
> 僅包含 Claude Code 官方文檔中明確定義的內容，無自定義方法論。
> 最後更新：2026-04-07

---

## 一、Skill 是什麼

Skill（也叫 Custom Slash Command）是一個**目錄**，核心是 `SKILL.md` 文件。

- frontmatter = Claude Code 解析的配置（觸發控制、工具權限、執行模式）
- 正文 = 調用時注入到 Claude 上下文中的指令

```
my-skill/
├── SKILL.md          # 必須
├── references/       # 可選——參考資料，被引用時按需加載
├── assets/           # 可選——模板、圖片等
└── scripts/          # 可選——可執行腳本
```

---

## 二、三層漸進式加載

| 層級 | 何時加載 | 上下文佔用 |
|------|---------|-----------|
| Level 1：元數據 | 會話啓動時 | name + description，~100 tokens/skill |
| Level 2：SKILL.md 正文 | 被調用時 | 全文注入 |
| Level 3：目錄資源 | 正文引用時 | 僅讀取的文件 |

**關鍵：** description 始終在上下文裏（佔路由空間），正文和目錄資源只在調用時才加載。

---

## 三、存放位置（按優先級高→低）

| 優先級 | 路徑 | 範圍 |
|--------|------|------|
| 1 | Managed settings | 組織內所有用戶 |
| 2 | `~/.claude/skills/<name>/SKILL.md` | 用戶全局 |
| 3 | `.claude/skills/<name>/SKILL.md` | 當前項目 |
| 4 | `<plugin>/skills/<name>/SKILL.md` | Plugin 作用域 |

- 同名 Skill，高優先級覆蓋低優先級
- Plugin Skill 使用 `plugin-name:skill-name` 命名空間，不衝突
- `.claude/commands/` 舊文件仍有效，同名時 Skill 優先
- 嵌套目錄的 `.claude/skills/` 也會被自動發現（支持 monorepo）
- `--add-dir` 目錄中的 `.claude/skills/` 會被加載

---

## 四、Frontmatter 完整字段（官方 12 字段）

**所有字段都是可選的。** 強烈建議寫 `description`。

```yaml
---
# ================================================================
# 標識
# ================================================================

# Skill 名稱和 /slash-command 名稱。
# 全小寫+數字+連字符，≤64 字符。省略時用目錄名。
# 禁止包含 XML 標籤、"anthropic"、"claude"。
name: write-tweet

# Skill 做什麼 + 什麼時候觸發。
# ≤1024 字符（列表中截斷為 250 字符）。
# Claude 根據這個字段決定是否自動調用此 Skill。
# 省略時使用正文第一段。
description: |
  根據素材撰寫推文。當用戶提到"寫推文"、"發推"、
  "幫我寫一條"時觸發。

# 參數提示。自動補全時顯示給用戶。
argument-hint: "[素材內容或連結]"

# ================================================================
# 觸發控制
# ================================================================

# true = 只能用戶手動 /name 觸發。
# description 不進入上下文，Claude 不知道此 Skill 存在。
# 默認：false
disable-model-invocation: false

# false = 用戶看不到此 Skill，只有 Claude 能調用。
# 默認：true
user-invocable: true

# Glob 模式。只在處理匹配文件時才自動激活。
# 逗號分隔或 YAML 列表。
paths: "*.md, src/**/*.ts"

# ================================================================
# 工具與執行
# ================================================================

# Skill 激活時免詢問的工具。
# 空格分隔或 YAML 列表。
allowed-tools: Read Write Edit Glob Grep

# 覆蓋會話模型。
model: sonnet

# 覆蓋會話 effort。low | medium | high | max
effort: medium

# fork = 在獨立子 Agent 中運行（隔離，無對話歷史）。
# 省略 = 在當前會話中運行（inline）。
context: fork

# context: fork 時使用的子 Agent 類型。
# 內置：Explore | Plan | general-purpose
# 或 .claude/agents/ 中的自定義 Agent name。
# 默認：general-purpose
agent: "general-purpose"

# ================================================================
# 生命週期
# ================================================================

# Skill 級鈎子。與全局/Agent 級鈎子隔離。
# 支持：PreToolUse | PostToolUse | UserPromptSubmit | Stop
hooks:
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "echo 'done'"

# ================================================================
# 其他
# ================================================================

# Shell 預處理命令使用的 shell。bash | powershell
# powershell 需要 CLAUDE_CODE_USE_POWERSHELL_TOOL=1
shell: bash
---
```

---

## 五、字符串替換變量

正文中以下變量會被運行時自動替換：

| 變量 | 說明 |
|------|------|
| `$ARGUMENTS` | 用戶調用時傳入的所有參數。如果正文中不包含此變量，參數自動追加為 `ARGUMENTS: <value>` |
| `$ARGUMENTS[N]` | 按索引訪問第 N 個參數（0 開始） |
| `$N` | `$ARGUMENTS[N]` 的簡寫。`$0` = 第一個參數 |
| `${CLAUDE_SKILL_DIR}` | SKILL.md 所在目錄的絕對路徑。引用目錄內文件用 |
| `${CLAUDE_SESSION_ID}` | 當前會話 ID |

---

## 六、Shell 預處理（動態上下文注入）

正文支持 `` !`<command>` `` 語法。在發送給 Claude **之前**執行 shell 命令，輸出替換佔位符。

```markdown
當前 Git 狀態：
!`git status --short`
```

多行命令用 ` ```! ` 開頭的代碼塊：

````markdown
```!
find . -name "*.md" -newer /tmp/last_check | head -20
```
````

- 可通過 `"disableSkillShellExecution": true` 全局禁用
- 正文包含 "ultrathink" 會啓用 extended thinking

---

## 七、正文（Skill 指令）

**官方沒有規定正文結構。** 正文是自由格式的 Markdown，調用時完整注入到 Claude 上下文中。

### 官方示例

```markdown
---
name: commit
description: Commit staged changes with a descriptive message
allowed-tools: Bash
---

Review staged changes with `git diff --cached`, then create a concise
commit message following conventional commits format. Run `git commit`
with the message. If nothing is staged, check `git status` and suggest
what to stage.
```

### 官方最佳實踐（來自 Skill authoring best practices）

- SKILL.md 正文目標 **≤500 行 / 1500-2000 詞**
- 參考資料放 `references/` 目錄，不要全塞正文
- 引用目錄內文件用 `${CLAUDE_SKILL_DIR}/references/xxx.md`
- references 保持一層深度，避免深度嵌套引用鏈

---

## 八、Description 預算

```
所有 Skill 的 description 共享上下文預算：
- 默認 = 上下文窗口的 1%，fallback 為 8000 字符
- 每個 Skill 的 description 在列表中截斷為 250 字符
- 環境變量 SLASH_COMMAND_TOOL_CHAR_BUDGET 可調整
```

**含義：** description 要精簡。核心信息（做什麼 + 觸發詞）必須在前 250 字符內。

---

## 九、調用控制矩陣

| 配置 | 用戶可調用 | Claude 可自動調用 | description 在上下文 |
|------|-----------|------------------|-------------------|
| 默認（都不設） | ✅ | ✅ | ✅ |
| `disable-model-invocation: true` | ✅ | ❌ | ❌ |
| `user-invocable: false` | ❌ | ✅ | ✅ |

---

## 十、context: fork 的行為

| | fork 模式 | inline 模式（默認） |
|--|----------|-------------------|
| 對話歷史 | 不繼承 | 繼承完整歷史 |
| 上下文消耗 | 獨立窗口，不佔主對話 | 佔用主對話 token |
| 執行 Agent | 由 `agent` 字段指定 | 當前會話 |
| 適用場景 | 獨立任務 | 需要對話上下文 |

---

## 十一、權限控制

三種方式限制 Claude 對 Skill 的訪問：

| 方式 | 效果 |
|------|------|
| `/permissions` 中添加 `Skill` 到 deny | 禁用所有 Skill |
| `Skill(commit)` 精確匹配 / `Skill(deploy *)` 前綴匹配 | 允許/禁用特定 Skill |
| frontmatter `disable-model-invocation: true` | 從 Claude 上下文完全移除 |

`allowed-tools` 在 Skill 激活時授予免詢問權限，但會話級權限設置仍然是基線。

---

## 十二、分發方式

| 方式 | 路徑 |
|------|------|
| 項目 Skill | 提交 `.claude/skills/` 到版本控制 |
| Plugin | 在 plugin 中創建 `skills/` 目錄 |
| 企業 | 通過 managed settings 部署 |

---

## 十三、內置 Skill

Claude Code 自帶以下 Skill：

| Skill | 功能 |
|-------|------|
| `/batch <instruction>` | 通過 git worktree 編排大規模並行代碼修改 |
| `/claude-api` | 加載你項目語言的 Claude API 參考 |
| `/debug [description]` | 啓用 debug 日誌排查問題 |
| `/loop [interval] <prompt>` | 按間隔重複執行 prompt |
| `/simplify [focus]` | 審查改動文件的複用性、質量、效率 |

---

## 十四、跨平台說明

Skill 遵循 Agent Skills 開放標準（agentskills.io）。但**自定義 Skill 不跨平台同步**——Claude Code 的 Skill 基於文件系統，與 claude.ai 和 API 的 Skill 各自獨立管理。

你寫了 8 個 Skill，但 Claude 從來不主動調其中 5 個。

你以為是 prompt 寫得不好，其實是你沒寫 description。

你發現每調一次 Skill 上下文就爆炸，其實是你沒用 context: fork。

我最近翻完了 Claude Code 官方 Skills 文檔，發現大部分人對 Skill 的理解停在"這就是個快捷指令"。但官方規範裏藏着一套完整的 AI 工作流設計框架。

Image

今天把這套規範拆開來講。不講方法論，只講官方文檔裏寫了但你大概率沒注意到的細節。


一、Skill 不是一個文件，是一個目錄

大部分人理解的 Skill：寫個 markdown，放 .claude/skills/ 裏，完事。

官方定義的 Skill 是一個目錄結構：

my-skill/
├── SKILL.md          # 必須——核心指令
├── references/       # 可選——參考資料，被引用時才加載
├── assets/           # 可選——模板、圖片等
└── scripts/          # 可選——可執行腳本

這裏面藏着一個關鍵設計意圖：references 目錄是按需加載的。

什麼意思？你把所有參考資料塞進 SKILL.md 正文裏，每次調用 Skill 都會把這些內容注入上下文，白白燒 token。但如果放在 references/ 裏，只在 Claude 主動引用時才讀取。

官方建議：正文控制在 500 行以內（約 1500-2000 詞），參考資料外掛。這跟寫代碼一樣——函數要短，邏輯要拆分，別搞幾千行的上帝文件。


二、三層加載機制：description 是你 Skill 的名片

這是整份規範裏最被低估的設計。

Claude Code 對 Skill 採用三層漸進式加載：


這意味着什麼？

你寫了 10 個 Skill，會話一啓動，10 個 description 全部進入 Claude 的上下文，佔用約 1000 tokens。所有 Skill 的 description 共享一個上下文預算——默認是上下文窗口的 1%，fallback 為 8000 字符。

但更關鍵的是：每個 Skill 的 description 在列表中會被截斷為 250 字符。

所以 description 的前 250 個字符，必須說清楚兩件事：

  1. 1.這個 Skill 幹什麼
  2. 2.什麼時候該用它

寫 description 不是在寫簡介，是在寫路由規則。Claude 根據這段文字決定要不要自動調用你的 Skill。寫不清楚 = Claude 找不到 = 白寫了。

❌ description: 一個幫助寫代碼的工具
✅ description: 根據功能需求生成完整的 React 組件代碼。當用戶提到"創建組件"、"寫個頁面"、"新增功能模塊"時觸發。

三、12 個 Frontmatter 字段，核心只有 4 組

官方定義了 12 個可選 frontmatter 字段。看着嚇人，其實按功能分只有 4 組：

第一組：標識（告訴系統你是誰）

name: my-skill          # 也是 /slash-command 的名稱
description: ...        # 上面講過了，必寫
argument-hint: "[參數]"  # 自動補全時的提示

第二組：觸發控制（決定誰能讓 Skill 運行）

disable-model-invocation: false  # true = Claude 不能自動調用
user-invocable: true             # false = 用戶看不到，只有 Claude 能調
paths: "*.md, src/**/*.ts"       # 只在處理匹配文件時才激活

這三個字段組合出了三種模式：


user-invocable: false 這個用法很少人用，但它很妙——你可以寫一個用戶完全看不到的 Skill，讓 Claude 在後台自動調用，比如自動格式化輸出、自動檢查文件結構。這是一種"隱形工作流"的設計思路。

第三組：執行模式（Skill 在哪跑）

context: fork           # fork = 獨立子 Agent，省略 = 當前會話（inline）
agent: "general-purpose"  # 子 Agent 類型，可選 Explore / Plan / 自定義
allowed-tools: Read Write Edit  # Skill 激活時免詢問的工具
model: sonnet           # 覆蓋模型
effort: medium          # 覆蓋 effort

這一組是整份規範裏實戰價值最高的部分，單獨講。

第四組：其他

hooks:                  # Skill 級鈎子
shell: bash             # 預處理命令的 shell

四、fork vs inline：選錯等於白寫

這是我見過最多人踩的坑。

默認情況下，Skill 在當前會話中運行（inline）——它繼承你的完整對話歷史，佔用主對話的 token 配額。

但當你設置 context: fork 時，Skill 會在一個獨立的子 Agent 中運行：


什麼時候必須用 fork？

當你寫了一個複雜的 Skill——比如代碼審查、批量重構、全項目搜索——這些任務本身就會消耗大量 token。如果跑在 inline 模式，你主對話的上下文會被嚴重擠佔，聊着聊着 Claude 就開始"忘記"之前說了什麼。

fork 模式不是可選功能，是上下文窗口的生存策略。

什麼時候必須用 inline？

當 Skill 需要你之前的對話信息——比如"幫我把剛才討論的那個功能寫出來"——這種情況 fork 模式拿不到對話歷史，根本沒法工作。

一個簡單判斷法則：如果指令本身就包含了完成任務所需的全部信息，用 fork；如果指令依賴對話上下文來理解，用 inline。


五、Description 預算：一個被你忽略的稀缺資源

前面提過，所有 Skill 的 description 共享一個上下文預算。

這個預算默認是上下文窗口的 1%。以 Claude Sonnet 的 200K 窗口為例，1% 就是 2000 個 token。

看起來不小，但如果你有 20 個 Skill，每個 description 就只剩 100 tokens。而 100 tokens 大約 75 箇中文字。

所以 description 必須極致精簡。這是官方規範的隱藏約束：不是你想寫多詳細就寫多詳細，是預算決定了你必須精簡。

策略：


  • 前 250 字符內必須包含核心觸發條件（因為列表截斷）

  • 用動詞開頭：當用戶提到...時觸發

  • 別寫廢話：去掉"這個 Skill 可以幫助你..."之類的客套

最後：一個被低估的功能——Shell 預處理

正文支持 !`<command>` 語法，在發送給 Claude 之前執行 shell 命令，把輸出替換到正文裏。

當前項目的 Git 狀態：
!`git status --short`

這意味着你的 Skill 可以是動態的——跑一次命令，讀取當前環境狀態，生成對應的上下文。比如：


  • 自動讀取 package.json 判斷項目技術棧

  • 檢查最近修改的文件列表

  • 獲取當前分支名和未提交改動

這個功能讓 Skill 從"靜態指令"變成了"動態工作流"。


Claude Code 的 Skill 規範，本質上是一套 AI 工作流設計框架。三層加載、fork 隔離、動態注入——這些不是一個文件後綴能概括的。

寫好 Skill 的關鍵不是寫更多指令，而是理解你的 Skill 在什麼時候被加載、以什麼方式運行、佔用多少上下文。

description 的前 250 個字符，決定 Claude 會不會用你的 Skill。

context: fork 不是選項，是生存策略。

寫 Skill 不是在寫指令，是在設計一個 AI 的工作流。

我也根據官方手冊優化我的skill，讓skill更好用了。

優化方式很簡單，直接把官方文檔給我的蝦，讓它優化對應的skill即可。

Image

原文

# Claude Code Skill 官方規範

> 來源：code.claude.com/docs/en/skills
> 僅包含 Claude Code 官方文檔中明確定義的內容，無自定義方法論。
> 最後更新：2026-04-07

---

## 一、Skill 是什麼

Skill（也叫 Custom Slash Command）是一個**目錄**，核心是 `SKILL.md` 文件。

- frontmatter = Claude Code 解析的配置（觸發控制、工具權限、執行模式）
- 正文 = 調用時注入到 Claude 上下文中的指令

```
my-skill/
├── SKILL.md          # 必須
├── references/       # 可選——參考資料，被引用時按需加載
├── assets/           # 可選——模板、圖片等
└── scripts/          # 可選——可執行腳本
```

---

## 二、三層漸進式加載

| 層級 | 何時加載 | 上下文佔用 |
|------|---------|-----------|
| Level 1：元數據 | 會話啓動時 | name + description，~100 tokens/skill |
| Level 2：SKILL.md 正文 | 被調用時 | 全文注入 |
| Level 3：目錄資源 | 正文引用時 | 僅讀取的文件 |

**關鍵：** description 始終在上下文裏（佔路由空間），正文和目錄資源只在調用時才加載。

---

## 三、存放位置（按優先級高→低）

| 優先級 | 路徑 | 範圍 |
|--------|------|------|
| 1 | Managed settings | 組織內所有用戶 |
| 2 | `~/.claude/skills/<name>/SKILL.md` | 用戶全局 |
| 3 | `.claude/skills/<name>/SKILL.md` | 當前項目 |
| 4 | `<plugin>/skills/<name>/SKILL.md` | Plugin 作用域 |

- 同名 Skill，高優先級覆蓋低優先級
- Plugin Skill 使用 `plugin-name:skill-name` 命名空間，不衝突
- `.claude/commands/` 舊文件仍有效，同名時 Skill 優先
- 嵌套目錄的 `.claude/skills/` 也會被自動發現（支持 monorepo）
- `--add-dir` 目錄中的 `.claude/skills/` 會被加載

---

## 四、Frontmatter 完整字段（官方 12 字段）

**所有字段都是可選的。** 強烈建議寫 `description`。

```yaml
---
# ================================================================
# 標識
# ================================================================

# Skill 名稱和 /slash-command 名稱。
# 全小寫+數字+連字符，≤64 字符。省略時用目錄名。
# 禁止包含 XML 標籤、"anthropic"、"claude"。
name: write-tweet

# Skill 做什麼 + 什麼時候觸發。
# ≤1024 字符（列表中截斷為 250 字符）。
# Claude 根據這個字段決定是否自動調用此 Skill。
# 省略時使用正文第一段。
description: |
  根據素材撰寫推文。當用戶提到"寫推文"、"發推"、
  "幫我寫一條"時觸發。

# 參數提示。自動補全時顯示給用戶。
argument-hint: "[素材內容或連結]"

# ================================================================
# 觸發控制
# ================================================================

# true = 只能用戶手動 /name 觸發。
# description 不進入上下文，Claude 不知道此 Skill 存在。
# 默認：false
disable-model-invocation: false

# false = 用戶看不到此 Skill，只有 Claude 能調用。
# 默認：true
user-invocable: true

# Glob 模式。只在處理匹配文件時才自動激活。
# 逗號分隔或 YAML 列表。
paths: "*.md, src/**/*.ts"

# ================================================================
# 工具與執行
# ================================================================

# Skill 激活時免詢問的工具。
# 空格分隔或 YAML 列表。
allowed-tools: Read Write Edit Glob Grep

# 覆蓋會話模型。
model: sonnet

# 覆蓋會話 effort。low | medium | high | max
effort: medium

# fork = 在獨立子 Agent 中運行（隔離，無對話歷史）。
# 省略 = 在當前會話中運行（inline）。
context: fork

# context: fork 時使用的子 Agent 類型。
# 內置：Explore | Plan | general-purpose
# 或 .claude/agents/ 中的自定義 Agent name。
# 默認：general-purpose
agent: "general-purpose"

# ================================================================
# 生命週期
# ================================================================

# Skill 級鈎子。與全局/Agent 級鈎子隔離。
# 支持：PreToolUse | PostToolUse | UserPromptSubmit | Stop
hooks:
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "echo 'done'"

# ================================================================
# 其他
# ================================================================

# Shell 預處理命令使用的 shell。bash | powershell
# powershell 需要 CLAUDE_CODE_USE_POWERSHELL_TOOL=1
shell: bash
---
```

---

## 五、字符串替換變量

正文中以下變量會被運行時自動替換：

| 變量 | 說明 |
|------|------|
| `$ARGUMENTS` | 用戶調用時傳入的所有參數。如果正文中不包含此變量，參數自動追加為 `ARGUMENTS: <value>` |
| `$ARGUMENTS[N]` | 按索引訪問第 N 個參數（0 開始） |
| `$N` | `$ARGUMENTS[N]` 的簡寫。`$0` = 第一個參數 |
| `${CLAUDE_SKILL_DIR}` | SKILL.md 所在目錄的絕對路徑。引用目錄內文件用 |
| `${CLAUDE_SESSION_ID}` | 當前會話 ID |

---

## 六、Shell 預處理（動態上下文注入）

正文支持 `` !`<command>` `` 語法。在發送給 Claude **之前**執行 shell 命令，輸出替換佔位符。

```markdown
當前 Git 狀態：
!`git status --short`
```

多行命令用 ` ```! ` 開頭的代碼塊：

````markdown
```!
find . -name "*.md" -newer /tmp/last_check | head -20
```
````

- 可通過 `"disableSkillShellExecution": true` 全局禁用
- 正文包含 "ultrathink" 會啓用 extended thinking

---

## 七、正文（Skill 指令）

**官方沒有規定正文結構。** 正文是自由格式的 Markdown，調用時完整注入到 Claude 上下文中。

### 官方示例

```markdown
---
name: commit
description: Commit staged changes with a descriptive message
allowed-tools: Bash
---

Review staged changes with `git diff --cached`, then create a concise
commit message following conventional commits format. Run `git commit`
with the message. If nothing is staged, check `git status` and suggest
what to stage.
```

### 官方最佳實踐（來自 Skill authoring best practices）

- SKILL.md 正文目標 **≤500 行 / 1500-2000 詞**
- 參考資料放 `references/` 目錄，不要全塞正文
- 引用目錄內文件用 `${CLAUDE_SKILL_DIR}/references/xxx.md`
- references 保持一層深度，避免深度嵌套引用鏈

---

## 八、Description 預算

```
所有 Skill 的 description 共享上下文預算：
- 默認 = 上下文窗口的 1%，fallback 為 8000 字符
- 每個 Skill 的 description 在列表中截斷為 250 字符
- 環境變量 SLASH_COMMAND_TOOL_CHAR_BUDGET 可調整
```

**含義：** description 要精簡。核心信息（做什麼 + 觸發詞）必須在前 250 字符內。

---

## 九、調用控制矩陣

| 配置 | 用戶可調用 | Claude 可自動調用 | description 在上下文 |
|------|-----------|------------------|-------------------|
| 默認（都不設） | ✅ | ✅ | ✅ |
| `disable-model-invocation: true` | ✅ | ❌ | ❌ |
| `user-invocable: false` | ❌ | ✅ | ✅ |

---

## 十、context: fork 的行為

| | fork 模式 | inline 模式（默認） |
|--|----------|-------------------|
| 對話歷史 | 不繼承 | 繼承完整歷史 |
| 上下文消耗 | 獨立窗口，不佔主對話 | 佔用主對話 token |
| 執行 Agent | 由 `agent` 字段指定 | 當前會話 |
| 適用場景 | 獨立任務 | 需要對話上下文 |

---

## 十一、權限控制

三種方式限制 Claude 對 Skill 的訪問：

| 方式 | 效果 |
|------|------|
| `/permissions` 中添加 `Skill` 到 deny | 禁用所有 Skill |
| `Skill(commit)` 精確匹配 / `Skill(deploy *)` 前綴匹配 | 允許/禁用特定 Skill |
| frontmatter `disable-model-invocation: true` | 從 Claude 上下文完全移除 |

`allowed-tools` 在 Skill 激活時授予免詢問權限，但會話級權限設置仍然是基線。

---

## 十二、分發方式

| 方式 | 路徑 |
|------|------|
| 項目 Skill | 提交 `.claude/skills/` 到版本控制 |
| Plugin | 在 plugin 中創建 `skills/` 目錄 |
| 企業 | 通過 managed settings 部署 |

---

## 十三、內置 Skill

Claude Code 自帶以下 Skill：

| Skill | 功能 |
|-------|------|
| `/batch <instruction>` | 通過 git worktree 編排大規模並行代碼修改 |
| `/claude-api` | 加載你項目語言的 Claude API 參考 |
| `/debug [description]` | 啓用 debug 日誌排查問題 |
| `/loop [interval] <prompt>` | 按間隔重複執行 prompt |
| `/simplify [focus]` | 審查改動文件的複用性、質量、效率 |

---

## 十四、跨平台說明

Skill 遵循 Agent Skills 開放標準（agentskills.io）。但**自定義 Skill 不跨平台同步**——Claude Code 的 Skill 基於文件系統，與 claude.ai 和 API 的 Skill 各自獨立管理。