---
name: add-skill
description: 建立符合官方規格的 Claude Code skill：蒐集需求、產出正確格式的 SKILL.md、驗證命名與描述規則、套用 Progressive Disclosure 結構。適合在新增 skill 或 slash command 時使用。
disable-model-invocation: true
context: fork
---

# Add Skill — 建立新 Skill

## 執行流程

### Step 1：取得最新官方規格

優先抓取官方文件，確保符合目前規格：

```
WebFetch: https://docs.anthropic.com/en/claude-code/skills
```

若失敗，用 WebSearch：`Claude Code skills SKILL.md format site:docs.anthropic.com`

### Step 2：確認基本資訊

從使用者取得（或直接從 prompt 解析）：

1. **範圍**：全域 skill 或 repo-local skill？
   - **全域** → `~/.claude/skills/{skill-name}/`（所有專案可用）
   - **Repo-local** → `.claude/skills/{skill-name}/`（僅此 repo，git 版控）
2. **名稱**：小寫、僅用連字號（優先動名詞形式：`processing-pdfs`、`testing-code`）
3. **用途**：做什麼？（1-2 句）
4. **觸發條件**：什麼時候用？（關鍵字、場景）
5. **複雜度**：純指令型，還是需要 scripts / references？
6. **自由度**：嚴格步驟型，還是原則指引型？

### Step 3：建立目錄結構

```
{base-path}/skills/{skill-name}/
├── SKILL.md           # 必要：主指令（<500 行）
├── config.json        # 可選：使用者設定（首次啟動時填寫）
├── scripts/           # 可選：給 Claude 組合用的腳本與函式庫
│   └── main.py
└── references/        # 可選：詳細文件（只能一層）
    └── examples.md
```

> **Thariq 原則（T3）**：Skill 是**資料夾**，不只是 markdown 檔案。SKILL.md 告訴 Claude「這個資料夾裡有什麼」，Claude 會在適當時機讀取子檔案。把 API 參考、範例、腳本放進資料夾，讓 SKILL.md 保持精簡 — 這就是 Progressive Disclosure。

> **Thariq 原則（T8）**：在 `scripts/` 放好腳本讓 Claude 組合使用，Claude 的每個 turn 就能專注在「該做什麼」，不必從頭重寫 boilerplate。

> **Thariq 原則（T7）**：需要跨 session 儲存 skill 資料時，用 `${CLAUDE_PLUGIN_DATA}` 路徑，而非 skill 目錄本身（skill 升級時目錄可能被覆蓋）。

### Step 4：產出 SKILL.md

**必要 frontmatter**（與本 workspace 慣例一致）：

```yaml
---
name: {skill-name}
description: {第三人稱說明，包含「做什麼」和「何時用」}
disable-model-invocation: true
context: fork
---
```

**正文結構**：
```markdown
# {Skill 標題}

## 觸發條件
...

## 執行步驟
...

## 輸出格式
...

## Gotcha（注意事項）
...
```

### Step 5：檢查行數 + Progressive Disclosure

草稿完成後計算行數，若超過 **500 行**：

1. 通知使用者
2. 識別可拆分段落（詳細 reference、長範例、進階功能）
3. 移至 `references/{topic}.md`（只能一層，不能再嵌套）
4. 在 SKILL.md 用摘要 + 連結取代
5. 超過 100 行的 reference 文件加目錄

### Step 6：驗證（見檢查清單）

### Step 7：確認寫入

```bash
ls -la .claude/skills/{skill-name}/
```

---

## 命名規則

- **長度**：1-64 字元
- **格式**：只能用小寫英文、數字、連字號
- **優先動名詞**：`processing-pdfs`、`testing-code`
- **不允許**：以 `-` 開頭/結尾、連續 `--`、保留字（`anthropic`、`claude`）
- **避免**：模糊名稱（`helper`、`utils`、`tools`）
- **必須與資料夾名稱一致**

## 描述規則

- **上限**：1024 字元，不能包含 XML 標籤
- **第三人稱**：「處理 PDF 檔案」，不要「我可以幫你」
- **同時包含**：做什麼 + 何時用
- **具體**：Claude 從 100+ skills 中選擇時靠 description

**好的範例**：
```yaml
description: 從 PDF 提取文字和表格、填寫表單、合併文件。適合在處理 PDF 檔案或使用者提到 PDF、表單、文件提取時使用。
```

**差的範例**：「幫助處理文件」、「處理資料」

> **Thariq 原則（T6）**：description 欄位是**給模型看的**，不是給人看的說明文字。Claude Code 啟動時掃描所有 skill 的 description 來決定「現在要用哪個 skill？」— 寫觸發條件，不要寫功能摘要。

---

## 自由度選擇

| 自由度 | 適用時機 | 範例 |
|-------|---------|------|
| **高**（文字指引） | 多種有效做法都可接受 | Code review 指引 |
| **中**（虛擬碼/參數） | 有偏好模式但有彈性 | 報告產出模板 |
| **低**（精確腳本） | 操作脆弱、需一致性 | 資料庫遷移 |

---

## On-demand Hooks（Thariq 原則 T9）

Skill 可以在 SKILL.md 中宣告 hook，這些 hook **只在 skill 被呼叫時啟用，session 結束後自動移除**。適合「只在特定情境需要的強烈限制」：

**範例**：
```markdown
## Hooks（本 Skill 啟動時自動生效）

- PreToolUse(Bash): 阻擋 rm -rf、DROP TABLE、force push、kubectl delete
  → 保護性模式，適合生產環境操作

- PreToolUse(Edit): 只允許修改 /docs/** 目錄
  → 文件限制模式，防止誤改程式碼
```

這讓你可以有 `/careful`、`/freeze` 等「安全模式 skill」，平時不影響日常工作，呼叫時才啟用防護。

## 反模式

- 解釋 Claude 本來就懂的事（Thariq T1：別說廢話）
- 提供太多工具/函式庫選項（給預設選項加逃生門即可）
- 時效性資訊（舊 API 等）— 用 `<details>` 折疊
- 超過一層的 reference 嵌套
- 假設套件已安裝但不給安裝指令
- 硬規定每一步（Thariq T4：給目標與限制，讓 Claude 靈活）

---

## 驗證清單

### 核心品質
- [ ] 名稱：小寫、只用數字和連字號、1-64 字元、無保留字
- [ ] 描述：第三人稱、具體、包含做什麼和何時用、不超過 1024 字元
- [ ] SKILL.md 本體不超過 500 行
- [ ] 細節放獨立 reference 文件（只能一層）
- [ ] 無時效性資訊
- [ ] 全文術語一致
- [ ] 有具體範例（非抽象說明）
- [ ] Frontmatter 含 `disable-model-invocation: true` 和 `context: fork`

### 腳本（若有）
- [ ] 明確處理錯誤，不把錯誤丟給 Claude
- [ ] 無魔術數字（所有數值都有說明）
- [ ] 列出依賴套件與安裝指令
- [ ] 路徑使用正斜線

### 測試
- [ ] 已在真實場景測試
- [ ] 不同複雜度的 prompt 都能正確觸發

---

## 參考資料

- **官方文件**：[docs.anthropic.com/en/claude-code/skills](https://docs.anthropic.com/en/claude-code/skills)
- **本 workspace 範例**：`.claude/skills/deep-review/SKILL.md`、`.claude/skills/research-best-practices/SKILL.md`