Skip to content

zeuikli/claude-code-workspace / .claude/skills/add-skill

add-skill

Verified

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

FileKindSize
SKILL.mdskill md6.6 KB
---
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`
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall