---
title: "07 - Skills 與斜線指令"
type: note
specialty: Programming
tags: [claude-code-cli從0開始使用教學, 07-skills, slash-commands]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 07 - Skills 與斜線指令

← [[06-CLAUDE-md與記憶系統]] | [[00-Index]] | 下一篇 → [[08-Subagents與平行工作]]

---

## Skill 是什麼

**寫一個 `SKILL.md` 檔案放指示，Claude 就把它加進工具箱。** 相關時它自己會用，你也可以用 `/skill-name` 直接叫。

**什麼時候該做成 skill**：
- 你一直把同一段指示 / 檢查清單 / 多步驟流程貼進對話
- CLAUDE.md 裡某一段已經從「事實」長成了「程序」

> 🔑 **最關鍵的差別**：跟 CLAUDE.md 不同，**skill 的內容只有在用到時才載入**。所以很長的參考資料放在 skill 裡，平常幾乎不花 context。
>
> 你的 12 個 skill（`note-orchestrator`、`neizhan-solver`、`google-med`…）就是這個設計的正確用法。

Claude Code 的 skill 遵循 [Agent Skills](https://agentskills.io) 開放標準，可跨工具使用；Claude Code 在標準之上加了 invocation control、subagent execution、dynamic context injection 等功能。

> 📌 **自訂指令已經併進 skill 了。** `.claude/commands/deploy.md` 和 `.claude/skills/deploy/SKILL.md` 都會產生 `/deploy`，行為一樣。舊的 `commands/` 檔案照樣可用，但 skill 多了：一個放輔助檔案的目錄、控制誰能觸發的 frontmatter、以及讓 Claude 自動判斷相關性載入的能力。

---

## Skill 放哪裡

| 層級 | 路徑 | 範圍 |
|---|---|---|
| **Personal** | `~/.claude/skills/<skill-name>/SKILL.md` | 你所有專案 |
| **Project** | `.claude/skills/<skill-name>/SKILL.md` | 只有這個專案 |
| **Plugin** | `<plugin>/skills/<skill-name>/SKILL.md` | plugin 啟用處 |

同名時：**enterprise > personal > project**。任一層的 skill 都會蓋掉同名的內建 skill。Plugin skill 用 `plugin-name:skill-name` 命名空間，不會衝突。

**Nested skills**：工作目錄底下的 `.claude/skills/` 也會載入——但**不是啟動時**，而是 Claude 第一次讀 / 改那個子目錄的檔案時。所以 monorepo 的子套件可以有自己的 skill。

**Live reload**：Claude Code 會監看 skill 目錄，你新增 / 修改 / 刪除 skill **當下 session 就會生效，不用重開**。⚠️ 但如果你建了一個「session 開始時還不存在」的頂層 skills 目錄，要重開 Claude Code 才會監看它。

> ⚠️ **雲端 / Routine session 讀不到你機器上的 `~/.claude/skills/`。** 你的個人 skill 要在雲端 session 用，得放進 repo 的 `.claude/skills/` 或做成 plugin。**這解釋了為什麼你的 vault 把 skill pipeline 放在 repo 的 `.claude/skills/` 裡——那是對的做法。**

---

## SKILL.md 長什麼樣

最小版本：

```markdown
---
name: summarize-changes
description: 總結目前 git diff 的變更，依風險分級。當使用者要求「總結變更」「這次改了什麼」時使用。
---

# 總結變更

1. 跑 `git diff --stat` 和 `git diff`
2. 依「行為改變 / 純重構 / 文件」三類分組
3. 標出任何會影響使用者的變更
4. 用條列輸出，不超過 15 行
```

存到 `~/.claude/skills/summarize-changes/SKILL.md`，然後 `/summarize-changes` 就能用。

---

## Frontmatter 完整欄位

| 欄位 | 必填 | 說明 |
|---|---|---|
| `name` | 否 | 顯示名稱，預設用目錄名 |
| `description` | **建議** | 這個 skill 做什麼、什麼時候用。**Claude 靠這個決定要不要用。把關鍵使用情境寫在最前面**——`description` + `when_to_use` 合起來在列表中會被截在 1,536 字元 |
| `when_to_use` | 否 | 補充觸發情境，例如觸發詞或範例請求。接在 `description` 後面，同樣算進 1,536 字元上限 |
| `argument-hint` | 否 | 自動補完時顯示的參數提示，例如 `[issue-number]` |
| `arguments` | 否 | 具名位置參數，供 `$name` 代換 |
| `disable-model-invocation` | 否 | `true` = **禁止 Claude 自動載入**，只能你手動 `/name` 叫 |
| `user-invocable` | 否 | `false` = 從 `/` 選單隱藏（給背景知識用，不讓人直接叫）|
| `allowed-tools` | 否 | 這個 skill 觸發的那一輪裡，可以不用問就用的工具。**下一則訊息就失效** |
| `disallowed-tools` | 否 | 這個 skill 生效時移除的工具。例如背景 loop 用的 skill 移掉 `AskUserQuestion` |
| `model` | 否 | 這個 skill 生效時用哪個模型（本輪有效，不寫進設定）|
| `effort` | 否 | `low` / `medium` / `high` / `xhigh` / `max` |
| `context` | 否 | 設 `fork` = 在 forked subagent context 裡跑 |
| `agent` | 否 | `context: fork` 時用哪種 subagent |
| `background` | 否 | 只在 `context: fork` 時有用。`false` = 在觸發那一輪等結果 |
| `hooks` | 否 | 綁在這個 skill 生命週期的 hook |
| `paths` | 否 | **限制何時自動啟用**的 glob，跟 path-scoped rules 同格式 |
| `shell` | 否 | `bash`（預設）或 `powershell` |

### 字串代換

| 代換 | 說明 |
|---|---|
| `$ARGUMENTS` | 全部參數。內容裡沒有這個變數時，參數會以 `ARGUMENTS: <值>` 附在後面 |
| `$ARGUMENTS[N]` / `$N` | 第 N 個參數（0 起算）|
| `$name` | frontmatter 的 `arguments` 宣告的具名參數 |
| `${CLAUDE_SESSION_ID}` | 目前 session ID |

---

## 兩個對你有用的模式

### 1. `disable-model-invocation: true`

**你不想它自己亂觸發的 skill 應該加這個。** 例如 `push-skill`——你不希望 Claude 「覺得該推一下」就自己推。

```yaml
---
name: push-skill
description: 把指定的 skill 推送到 GitHub 的 claude-skills repo
disable-model-invocation: true
---
```

### 2. `paths:` 限定自動觸發範圍

```yaml
---
name: finance-note
description: 撰寫或更新理財個股 / ETF 分析筆記
paths:
  - "理財(FIN)/**"
---
```

這樣 Claude 只有在碰理財資料夾時才會自動考慮這個 skill，不會在你寫腎臟科筆記時跳出來。

---

## 內建指令表

| 指令 | 用途 |
|---|---|
| `/add-dir <path>` | 加一個可存取的工作目錄 |
| `/advisor [model\|off]` | 開關 advisor 工具（用更強的模型輔助關鍵決策）|
| `/agents` | 管理 subagent 設定 |
| `/autofix-pr [prompt]` | 監看 PR，CI 失敗或有人 review 時推修正 |
| `/background [prompt]` | 把 session 轉成背景 agent |
| `/batch <instruction>` | **[Skill]** 把大規模變更拆成平行單位 |
| `/branch [name]` | 從目前對話分支出去試別的方向 |
| `/btw [question]` | 問個小問題，**不加進對話** |
| `/bug [report]` | 回報 bug / 分享對話（別名 `/share`）|
| `/cd <path>` | 換工作目錄 |
| `/clear [name]` | 清空開新的（別名 `/reset`、`/new`）|
| `/code-review [level] [--fix] [--comment] [target]` | **[Skill]** 審 diff 找正確性 bug |
| `/compact [instructions]` | 壓縮對話釋放 context |
| `/config [key=value]` | 設定介面（別名 `/settings`）|
| `/context [all]` | **視覺化目前 context 用量** |
| `/copy [N]` | 複製最後一則回覆 |
| `/dataviz [request]` | **[Skill]** 圖表 / 儀表板設計指引 |
| `/debug [description]` | **[Skill]** 開 debug log 並排錯 |
| `/deep-research <question>` | **[Workflow]** 展開多路搜尋並產出附引用的報告 |
| `/desktop` | 接到桌面 app 繼續（別名 `/app`）|
| `/diff` | 互動式 diff viewer 看未 commit 的變更 |
| `/doctor` | **[Skill]** setup 檢查與診斷（別名 `/checkup`）|
| `/effort [level\|auto]` | 設思考力度 |
| `/export [filename]` | 匯出對話成純文字 |
| `/fast [on\|off]` | 開關 fast mode |
| `/fewer-permission-prompts` | **[Skill]** 掃 transcript 幫你減少權限詢問 |
| `/focus` | 只顯示最後一個 prompt 和最終回覆 |
| `/fork [prompt]` | 把目前對話複製成一個新的背景 session |
| `/goal [condition\|clear]` | 設一個完成條件，讓 Claude 一直做到達成 |
| `/help` | 說明 |
| `/hooks` | 看 hook 設定 |
| `/init` | 產生 `CLAUDE.md` |
| `/insights` | 分析你的 Claude Code session 產生報告 |
| `/keybindings` | 開快捷鍵設定檔 |
| `/login` `/logout` | 登入 / 登出 |
| `/loop [interval] [prompt]` | **[Skill]** 定期重複執行一個 prompt |
| `/mcp` | 管理 MCP server 連線與 OAuth |
| `/memory` | 編輯記憶檔、管理 auto memory |
| `/model [model]` | 切模型並存成預設 |
| `/permissions` | 管理 allow / ask / deny 規則 |
| `/plan [description]` | 進入 plan mode |
| `/usage` | 看用量（`/cost` 是別名）|
| `/exit` | 離開（別名 `/quit`）|

打 `/` 之後可以接著打字母過濾。

---

## 內建 skill（會自動判斷相關性）

`/batch`、`/claude-api`、`/code-review`、`/dataviz`、`/debug`、`/design-sync`、`/doctor`、`/fewer-permission-prompts`、`/loop`、`/verify`、`/run`、`/run-skill-generator`

其中 `/code-review` 和 `/verify` 需要**明確叫它**才會跑。

> 💡 **`/fewer-permission-prompts` 值得跑一次**：它掃你的 transcript，找出常見的唯讀 bash / MCP 呼叫，然後幫你在 `.claude/settings.json` 加一份排好優先序的 allowlist。你每天被問「可以跑 `git status` 嗎」的次數會明顯下降。

---

## 🔗 相關筆記

- [[06-CLAUDE-md與記憶系統]] — 上一步（skill vs CLAUDE.md 的取捨）
- [[08-Subagents與平行工作]] — 下一步
- [[09-Hooks自動化]] — skill 裡也可以綁 hook
- [[13-實戰-套用在兩個repo]] — 你現有 12 個 skill 的檢視

---

*最後更新：2026-08-04*