進階篇 · 第 8 章
個人化設定與客製化
用了一陣子之後,你大概會開始想:「能不能讓它記住我的習慣?」「同一串指令我每次都要重打,好麻煩。」「這個顏色看得我好累,能換嗎?」這一章就是在教你把 Claude Code 調成「你的樣子」——設定檔放哪、怎麼做一個自己的 /指令、怎麼讓某些動作「鐵定」自動發生、怎麼挑模型控制花費,最後帶你把終端機的主題、狀態列,甚至它「說話的方式」都換成你喜歡的樣子。這些全部都是「非必須」的進階設定,看過知道有這回事就好,需要的時候再回來照著做。 還沒這些需求的話,跳過也完全不影響你日常使用。
8.1 設定檔放哪:settings.json
Claude Code 的各種設定,都記在一個叫 的檔案裡。你可以把它想成它的「個人設定面板」——只是長相是一份文字檔,不是有勾選框的視窗。
這個檔案其實分好幾個層級,差別在「影響範圍」:由廣到窄是「全公司層(Managed,由公司 IT 統一管)→ 個人層(管你所有專案)→ 專案層(只管這個專案)→ 個人本機層(你自己的覆蓋,不進 Git)」,越窄的層級會蓋過越廣的。新手最常用的是中間兩層;下面這張表幫你分清楚:
| 層級 | 位置 | 影響範圍 |
|---|---|---|
| 全公司層 (Managed) |
由公司 IT 部署的系統層設定檔 | 整台機器、所有人共用,優先權最高;個人通常不用碰,進企業環境才會遇到。 |
| 個人層 | 🍎 ~/.claude/settings.json 🪟 %USERPROFILE%\.claude\settings.json |
管你所有專案。 |
| 專案層 | .claude/settings.json |
只管「這個專案」;可以一起 commit 進 Git,跟團隊共用設定。 |
| 個人本機層 (Local) |
.claude/settings.local.json |
只管這個專案、且只屬於你自己,會蓋過上面的專案層;通常不進 Git,拿來放你個人的覆蓋設定。 |
完整的優先權順序其實還有一層沒放進表格裡:命令列參數(像啟動時加的 --model)優先權比全公司層低、但比其餘三層都高——不過它只在那一次啟動有效,關掉重開就沒了,不會被存下來,所以沒有對應的「檔案位置」可以列。還有一個例外要特別記住:放行規則(permissions)不是「窄層整個蓋過寬層」,而是「各層規則會合併」——你在個人層設的放行規則,不會因為專案層也設了規則就整批消失,兩邊是疊加生效,這跟其他大多數設定的邏輯不一樣,很容易搞混。
裡面可以設定:哪些動作要放行或擋下(權限)、自動化的 Hooks、環境變數、預設用哪個模型等等。改完大部分欄位會自動重新載入,不用重開 Claude Code——但有兩個例外,下面用提示框特別標出來。萬一改壞了、它行為怪怪的,下面這個指令會幫你體檢,告訴你哪裡設定錯了。
改了 model 或 outputStyle,怎麼好像沒生效?
多數設定改完就活(permissions、Hooks、環境變數都是熱重載),model 和 outputStyle 這兩個欄位卻是「啟動時才讀」的例外。想切模型,直接打 /model 指令就是即時生效;但如果是手動改 settings.json 裡的 model 欄位,或是切換了 outputStyle(8.8 會細講),要 /clear 或重開一個新對話,改動才會真的套進系統提示。踩過這個雷再回頭看就懂了:不是設定沒存到,是它還沒被「重新讀一次」。
建議執行:設定出問題時,用它找錯
/doctor
順帶一提,/doctor 能做的比「抓語法錯誤」更多:它會一次驗證全部四層的 settings.json,抓出哪個檔案、哪一條設定有問題(型別不對、路徑不存在等等);還會幫你估算目前載入的 skill 清單佔了多少 context token、揪出跑得特別慢的 hooks、標出裝了卻沒在用的 MCP 或 skills。定期跑一次,很多還沒惡化成「打不開」的小問題都能提早抓到。
settings.json 壞掉是真實會發生、後果也不小的踩雷,先認得下面三種症狀,之後真的遇到才不會慌:
| 症狀(你看到的) | 原因與解法 |
|---|---|
| 打開 Claude Code 就跳出看不懂的錯誤訊息,之後每次互動都卡在「Interaction interrupted by User」動彈不得 | 多半是 settings.json 裡有 JSON 語法錯誤(最常見是少打一個逗號)。跑 /doctor 讓它告訴你是哪個檔案、哪一條設定壞掉,改好存檔通常就能恢復。 |
| deny 清單好像設了,但 Claude 還是讀得到你想擋的檔案 | 兩種常見原因:規則的語法沒對到實際呼叫工具/路徑的寫法,或是被更高層的另一條 allow 規則蓋過。用 /permissions 或 /doctor 看一次「目前實際生效」的規則清單,別只看自己寫的那一條。 |
| 明明改了設定,Claude 的行為卻完全沒變、也沒有任何錯誤訊息 | 更麻煩的一種:格式錯誤的 JSON 有時候不會噴錯,而是被「靜默忽略」——整條設定形同沒寫。這也是為什麼建議在 settings.json 開頭加 $schema,讓編輯器先幫你抓一層語法錯誤,比事後用 /doctor 除錯更早發現問題。 |
最省力的預防針,是在 settings.json 最上面加一行 $schema,讓 VS Code 這類編輯器在你打錯之前就先標紅提醒,不用等到執行期才發現:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run lint)"],
"deny": ["Read(./.env)"]
},
"model": "sonnet"
}
8.2 內建指令快速導覽
Claude Code 內建了一堆「斜線指令」(就是用 / 開頭的那種)。你不用背——在對話裡打一個 /,它就會把所有能用的指令列出來給你看;再多打幾個字母,清單會跟著篩選,很快就找到你要的。下面挑幾個常用的先讓你認識。
| 指令 | 作用 |
|---|---|
/init |
生成起始的 CLAUDE.md |
/memory |
查看 / 編輯記憶 |
/permissions |
設定放行規則 |
/plan |
進入計畫模式 |
/model |
切換使用的模型(本章 8.6 細講) |
/effort |
調整推理力氣,省略時用模型預設(本章 8.6 細講) |
/mcp |
管理外部工具連線(第 9 章) |
/agents |
設定子代理人(高手篇) |
/context・/compact・/clear |
管理對話的上下文 |
/hooks |
瀏覽已設定的 Hooks |
/config |
開設定介面;也可以 /config key=value 直接改單一項 |
/statusline |
用一句人話描述想要的狀態列,自動生成腳本(8.7 細講) |
/output-style |
切換系統提示的整體風格(8.8 細講) |
/theme |
切換終端機主題(8.7 細講) |
/vim |
切換 Vim 編輯模式(8.7 細講) |
/keybindings |
開按鍵綁定設定檔(8.7 細講) |
/doctor |
診斷設定問題 |
/help |
求助 |
指令要放在最前面才有效
斜線指令只有放在你訊息的最前面才會被當成指令;放在中間或後面,它會被當成一般文字。指令後面接的文字,會變成那個指令的「參數」。
8.3 做一個自己的 /指令(用 Skills)
有沒有一串指令你常常重複下?例如「幫我把改動整理好、寫好說明、然後 commit」。與其每次重打,你可以把它打包成一個 /名字,一鍵呼叫。官方現在推薦的做法叫「」——說穿了,就是建一個小檔案,把你要它做的事寫進去。
順帶一提,Skill 並不是「只有 Claude Code 才吃得下」的功能。官方文件其實把它的規格拆成兩層:面向 API/Agent SDK 的通用規格只要求 name 和 description 兩個欄位,是跨介面共通的最小規格;Claude Code 專屬文件則在這之上疊加一整組 CLI 專屬擴充欄位(就是接下來要介紹的那些)。兩者共用同一份 SKILL.md 概念,只是後者多了本節後面會講到的那些欄位——換句話說,Skill 是一包能跨介面重複使用的能力,不是「只在終端機裡才成立」的東西。官方
下面用最常見的 /commit 當例子,帶你做一次。三步就好。
-
動手做
建一個檔案
在你的專案裡,建一個檔案,路徑是
.claude/skills/commit/SKILL.md。資料夾不存在的話一起建出來——commit這個資料夾名,之後就會變成你的指令名/commit。 -
動手做
把下面這段內容貼進去,存檔
打開剛建好的
SKILL.md,把下面這整段貼進去、存檔。最上面用兩條---框起來的部分叫「frontmatter」,是這個指令的基本資料;下面那行,就是你要它實際做的事。--- name: commit description: 把目前的改動整理並 commit,寫好說明 --- 請幫我 stage 所有改動,寫一個清楚的提交訊息,然後 commit。 -
在對話裡打 /commit 試試
回到 Claude Code 的對話框,打
/commit按 Enter。它就會照你寫的那行去做:把改動整理好、寫好提交訊息、commit。預期會看到打
/的時候,你新建的/commit會出現在指令清單裡;選它執行後,它會開始幫你 stage、寫訊息、commit。看到它動起來,就成功了。# 打 / 時,清單裡會多出你自己的指令 /commit 把目前的改動整理並 commit,寫好說明
Skill 的好處是:你可以手動用 /名字 叫它,Claude 也會在它覺得適合的時候自己用。
還有一個小技巧:如果你把這個檔案放在 ~/.claude/skills/(個人目錄)而不是專案裡,那它就會變成你所有專案都能用的個人指令。
舊的做法還能用,但不建議
以前是把指令放在 .claude/commands/ 資料夾裡(一個 .md 一個指令),目前還能用,但官方已經建議改用上面這種 Skills 格式。新做的話,直接照上面三步走就好。
進階:SKILL.md 還能寫更多東西
剛剛那個 /commit 例子,frontmatter 裡只寫了 name 和 description,這是最精簡的可用版本。實際上 frontmatter 裡只有 description 算「建議一定要寫」(讓 Claude 判斷什麼時候該用它),其餘全部是 optional,看你需不需要再加官方。常用的幾個欄位:
| 欄位 | 作用 |
|---|---|
when_to_use |
補充觸發語句,把使用者實際會講的話寫進去,讓 Claude 判斷更準。 |
disable-model-invocation: true |
只有人能手動用 /名字 叫用,Claude 不會自己主動觸發——適合有副作用的動作,像部署、送出訊息。 |
user-invocable: false |
反過來,只有 Claude 能觸發,不會出現在 / 選單裡,適合純粹當背景知識用的 skill。 |
allowed-tools / disallowed-tools |
這個 skill 啟用時,預先核准或移除哪些工具。 |
model / effort |
這個 skill 執行時,覆蓋要用的模型或推理力氣(8.6 細講這兩個概念)。 |
context: fork + agent |
讓這個 skill 在獨立的子代理人裡跑,不佔用主對話的 context,適合「調查、研究」類、只需要回傳結果摘要的 skill。 |
paths |
限定只有目前處理的檔案符合這個路徑規則時,才自動載入這個 skill。 |
這組欄位清單、以及 disable-model-invocation/user-invocable 兩者的精確行為、還有 context: fork 搭配 agent 讓 skill 整個丟進子代理人執行的機制,都直接對照官方文件的 Frontmatter reference官方。(context: fork 也有反向鏡射:子代理人自己的 frontmatter 也能用 skills 欄位預先載入某些 skill 內容,兩者是同一組機制的一體兩面。)
還有一件事現在就先記住:description 本身在 frontmatter 規格層有個硬性上限——最多 1,024 字元官方。這跟本節後面「放在哪裡,就管多大範圍」那節會提到的 1,536 字元是兩個不同層次的數字,那邊再細講怎麼分。
description 怎麼寫,才會在對的時機被準確觸發
前面提過 description 是唯一「建議一定要寫」的欄位,因為 Claude 就是靠這幾句話判斷「現在該不該用這個 skill」。它值得你多花點心思寫好,下面是幾個官方與社群都認同的具體做法。
第一個原則:同時講清楚「做什麼」和「什麼時候用」,而且要用使用者實際會講的話,不是抽象的功能摘要官方。兩種寫法差在哪,看下面對照:
# ❌ 太抽象:只講做什麼,沒講什麼時候用
description: 處理 PDF 文件
# ✅ 具體:做什麼 + 什麼時候用,貼近使用者真的會講的話
description: 從 PDF 擷取表格與文字並轉成 Markdown。當使用者要求「把這份 PDF 整理成文字」「這份 PDF 的表格轉一下」時使用。
第二個原則:一律用第三人稱撰寫(像「Processes and validates PDF files」),不要寫成「I can help you...」這種第一人稱口吻——因為 description 最後會被原樣塞進系統提示,第一人稱讀起來會很奇怪,也不是寫給使用者看的文案官方。
想知道原理:為什麼 description 要故意寫得有點雞婆?
官方自己在 skill-creator(協助你建立 skill 的官方工具)原始碼裡承認一件事:模型本身有一種系統性的傾向——該觸發卻沒觸發,寧可保守不用,也不會主動幫你套。所以官方給的建議是,description 可以故意寫得有點「雞婆」,像是「Make sure to use this skill whenever the user mentions...」(只要使用者提到……務必使用這個 skill)這種語氣肯定、近乎催促的寫法,而不是含糊帶過的建議語氣。寫得肯定一點,觸發率反而更接近你的預期。官方
第三個原則:加一句「不處理什麼」的邊界說明,避免跟其他相近的 skill 搶觸發、彼此誤會對方的地盤社群。例如同時有處理 PDF 和處理 Word 文件的兩個 skill,各自在 description 補一句「不處理 .docx」「不處理 .pdf」,能明顯降低兩邊互相搶著跳出來的機率。
想知道原理:怎麼系統化驗證 description 寫得夠不夠準?
官方文件推薦一套「先評測、再寫」的流程(evaluation-driven development):① 先跑一次沒有這個 skill 的版本,看 Claude 到底卡在哪裡;② 針對那些卡點,寫至少 3 個「應該觸發」與「不應該觸發」的測試案例;③ 拿這些案例建一份 baseline(沒有 skill 時的表現);④ 只補寫剛好能讓案例通過的最小指令,不要一次塞一大堆你以為有用的內容;⑤ 反覆跑測試、反覆修正。官方的 skill-creator 外掛可以幫你自動跑完這整套迴圈——包含各準備 8~10 條「應該觸發」與「不應該觸發」的案例,並自動切成 60/40 的訓練/驗證集。官方
最後是命名慣例:skill 名稱優先用動名詞形式(像 processing-pdfs),避免取 helper、utils 這種模糊到看不出用途的名字,也避免用到保留字官方。
進階:SKILL.md 可以只當索引,額外檔案才是真正的血肉
目前為止的例子,SKILL.md 都是「唯一的一份檔案」。但 skill 其實可以綁定額外檔案,不用把所有東西塞進同一份文件裡——官方稱這是漸進式載入(progressive disclosure),分三層官方:
Level 1:metadata
name 和 description。Claude Code 一開機就把它塞進系統提示,每個 skill 大概只佔 ~100 token,不管你用不用得到,這筆固定成本都在。
Level 2:SKILL.md 本文
只有真的被觸發時才會被讀進 context,建議控制在 5,000 token 以下。
Level 3:綁定檔案
scripts/、references/、assets/ 這些額外檔案完全不佔 context,直到被實際讀取或執行才耗費 token;如果是腳本,Claude 只會看到執行後的輸出,程式碼本身不會進 context。
想知道原理:為什麼綁定檔案可以「無上限」?
官方工程部落格的原話大意是:「有檔案系統和程式碼執行能力的代理人,不需要一次讀完整份 skill」——Claude 本來就能自己選擇性地讀取、執行檔案,所以 skill 能綁定的內容量實質上沒有上限。官方舉的例子是:把填表單的詳細步驟搬去一份獨立的 forms.md,核心的 SKILL.md 保持精簡,只在真的要填表單時才指示 Claude 去讀那份細節文件。官方
實際動手時,三個目錄各自的角色是官方:scripts/ 放可執行的腳本(Claude 用 bash 直接跑);references/ 放唯讀的參考文件;assets/ 或 templates/ 放會被複製進最終產出成品的範本檔案,三者用途不同,別混用。
官方文件與社群整理出幾條撰寫紀律,養成習慣能少踩很多坑:
SKILL.md 本文 500 行以內
超過就拆到獨立檔案,別讓核心檔案越養越肥。官方
引用只能一層深
別寫成 SKILL.md → advanced.md → details.md 這種巢狀連結——Claude 有時只用 head -100 讀部分內容,巢狀太深容易讀到一半就斷了脈絡。官方
100 行以上的參考檔案,附目錄
讓 Claude 不用整份讀完,先看目錄就能判斷要不要往下讀、該讀哪一段。官方
多領域內容依領域分檔
像 reference/finance.md、reference/legal.md 這樣依主題命名,不要用 part1.md、part2.md 這種流水編號,看名字才猜得到裡面寫什麼。官方
引用要寫「指令句」,不要寫「建議句」
寫「Read forms.md before proceeding」(先讀過 forms.md 再繼續),而不是「See forms.md」(參見 forms.md)——官方把後面這種容易被忽略的引用稱為「missed connections」。官方
templates/ 和 references/ 別混著放
一個常見的錯誤:把該給使用者複製使用的範本檔(templates/)跟純粹給 Claude 讀的參考文件(references/)放進同一個資料夾,結果不是範本被當成唯讀文件晾在那裡沒被用上,就是不該出現的檔案跑進了使用者的專案裡。動手前先想清楚這份檔案是「要被複製出去」還是「只給 Claude 參考」,放對資料夾。達人
不想從零開始寫?官方在 github.com/anthropics/skills 放了一批現成範例(處理 pdf/xlsx/pptx/docx 等常見格式),另外還有一個專門協助 scaffold 新 skill 的 skill-creator 外掛,裝上之後跟著它的引導走一遍就能生出一份骨架完整的 SKILL.md官方。
動態注入與參數:讓 Skill 更聰明
Skill 內容裡可以直接放參數,也可以先跑一段指令、把結果塞進去再交給 Claude 看。先看參數:$ARGUMENTS 代表呼叫時你在指令後面接的全部文字,例如:
---
name: fix-issue
description: 依 GitHub issue 編號修 bug
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit
存好之後打 /fix-issue 123,$ARGUMENTS 就會被換成 123。如果參數不只一個,也可以用位置取值($1、$2……)或在 frontmatter 用 arguments 清單把每個位置命名成好記的名字。
另一招是動態內容注入:在 Skill 內容裡用 !`指令` 這種語法(反引號包住一行 shell 指令),Claude Code 會先真的去執行它,把輸出結果替換進去——Claude 讀到的是「已經跑好的實際資料」,不是指令本身。舉例,如果你想讓一個 skill 一開始就看到目前改了哪些檔案:
目前的改動:
!`git diff --stat`
請根據上面的改動整理一份簡短的變更摘要。
這樣少了一輪「Claude 自己再去跑一次指令」的來回,行為也更可預期。想全域關掉這個機制(例如企業環境不想讓 skill 檔案夾帶 shell 執行),可以設 disableSkillShellExecution: true。
裝別人寫的 Skill 之前,先做這些檢查
上一節提到 Skill 可以綁定 scripts/ 這類可執行檔案,前面也講過 !`指令` 這種動態注入語法會真的去執行 shell 指令——也就是說,一個 skill 本質上就是「一包能讓 Claude 取得新能力的指令加程式碼」。官方明講:只用你自己寫的、或 Anthropic 官方提供的 skill;來路不明的 skill 可能會讓 Claude 做出跟它宣稱用途完全不符的操作官方。
要裝別人寫的 skill,先逐一檢查這幾點
把 SKILL.md、綁定的腳本、圖片這些檔案都讀過一遍,別直接裝了就用;特別留意有沒有不尋常的網路呼叫或檔案存取行為。會去抓外部網址內容的 skill 風險更高——抓回來的內容有可能夾帶惡意指令,就算原本是可信的 skill,也可能因為它依賴的外部來源被竄改而跟著變質。官方
專案層 .claude/skills/ 裡設定的 allowed-tools,並不是你 clone 下來就自動生效——它要等你在工作區信任(workspace trust)對話框裡按下接受,才會真的套用。官方的提醒是:信任一個 repo 之前,先把裡面的 project skill 看過一遍,因為一個 skill 可以自己把自己的工具權限開得很寬官方。
這其實跟高手篇會講的子代理人 tools 欄位「省略等於給全部工具,最小權限一定要明寫」是同一套紀律,只是這裡換成 Skill 版本:別人寫的 skill 拿到的能力,可能比它宣稱的還要多。
放在哪裡,就管多大範圍
跟 8.1 的 settings.json 很像,Skill 存放的位置也分層級,越廣(層級越高)的蓋過越窄的官方:
| 層級 | 位置 | 管多大範圍 |
|---|---|---|
| 全公司層 | 企業 managed 設定內 | 蓋過以下所有層;個人通常不用碰。 |
| 個人層 | ~/.claude/skills/<名字>/SKILL.md |
你所有專案都能用。 |
| 專案層 | .claude/skills/<名字>/SKILL.md |
只有這個專案能用;跟團隊共用就進 Git。 |
| 外掛層 | <外掛>/skills/<名字>/SKILL.md |
該外掛啟用時可用。 |
同名衝突時,全公司層蓋過個人層、個人層蓋過專案層;任一層的 skill 也會蓋過同名的內建 skill官方。外掛層則不在這個優先序裡搶位置——它強制帶 <外掛名>:<skill 名> 這種命名空間前綴,結構上就不可能跟其他三層的裸名稱撞名,不是「排第幾順位」的問題,是根本不會撞官方。如果你的專案是 monorepo,不同套件資料夾底下也可以各自放 .claude/skills/,Claude 處理該目錄下的檔案時會一併載入;真的撞名,可以用「路徑:skill 名」明確指定要叫哪一個,例如 /apps/web:deploy官方。
寫了 Skill 卻沒照預期運作,多半是下面三種狀況,對照著調整就好:
Skill 寫了,但 Claude 都不會自動觸發
最常見原因是 description 寫太籠統,沒把使用者實際會講的話寫進去。把「使用情境」寫具體一點(例如「當使用者問『這次改了什麼』或要求 commit 訊息時使用」),或直接問 Claude「目前有哪些 skills 可以用」,確認它真的讀到了。想寫得更準,可以參考前面「description 怎麼寫,才會在對的時機被準確觸發」那節的具體做法。官方
Skill 太雞婆,常常在不該出現時被觸發
description 寫太寬鬆,什麼情境都覺得自己該出場。把敘述寫精確一點;不放心的話乾脆加 disable-model-invocation: true,改成只能你手動 /名字 呼叫,不讓 Claude 自己決定要不要用。官方
Skill 一多,description 常常被砍到只剩片段
單一 skill 的 description 上限 1536 字元。這裡的 1,536 字元是 Claude Code 在 / 清單裡顯示 skill 時的預算上限,跟前面 frontmatter 規格層那個 1,024 字元硬上限是不同層次的兩個數字,注意別搞混。官方全部 skill 清單另外還有以模型 context window 1% 為總預算的上限,關鍵字被截掉會讓觸發判斷失準——這個 1% 動態預算數字是社群逆向工程比對出來的結果,並非 Anthropic 官方文件證實的保證行為。社群
想知道原理:Skill 用過一次,之後每回合都要重新讀一次嗎?
不用。Skill 一旦被叫用,整段內容就會留在這輪對話的 context 裡,後面的回合不會重新讀檔;如果你重複呼叫同一個沒改過的 skill,Claude Code 只會提示「這個已經載入過了」,不會再貼一次完整內容,省得佔位置官方。比較需要注意的是 /compact 壓縮對話的時候:最近呼叫過的 skill 內容會被優先保留(每個最多留 5000 token,全部 skill 加起來共用 25000 token 的預算),比較舊的呼叫紀錄則可能被直接丟掉——這也是為什麼 description 要寫精準,讓 Claude 真的需要的時候才去叫它,不是「先叫再說」。
想知道原理:1,536 這個數字是哪來的?
這串數字背後其實有一段版本演進史:250 字元 → 1,536 字元 → 以 context window 1% 為動態預算,對應大概 v2.1.86、v2.1.105、v2.1.129 三個版本點——這是社群逆向工程比對出來的結果,不是 Anthropic 官方文件白紙黑字寫下的保證行為,連官方文件自己都有 issue 在反映「文件沒跟上,還寫著舊的 250 字元」。這段機制很可能會隨版本再變,看到具體數字時心裡有個底就好,別當成永久不變的規格。社群
這個功能包,到底該用 Skill、subagent,還是舊的 slash-command?
官方文件講得很直白:舊的 .claude/commands/ 自訂指令已經併入 Skills——.claude/commands/deploy.md 跟 .claude/skills/deploy/SKILL.md 建立的其實是同一個 /deploy,行為完全相同。舊格式現在仍然能用,但官方建議新做的都改用 Skills,因為 Skills 多支援綁定檔案、觸發控制、丟進子代理人執行這些能力,是舊格式做不到的官方。
那如果選項是「留在主對話(用 Skill)」還是「切給高手篇會細講的子代理人()」呢?官方給了一組判準官方:
| 情境 | 比較適合 |
|---|---|
| 需要跟你頻繁來回討論、邊做邊調整 | 留在主對話(Skill) |
| 多個階段都要共用同一批大量 context | 留在主對話(Skill) |
| 想快速修改、迭代很頻繁 | 留在主對話(Skill) |
| 很在意回應延遲,不想多繞一手 | 留在主對話(Skill) |
| 過程會產生一大堆你最後用不到的中間輸出 | 切給子代理人 |
| 想限制工具/權限範圍,只給它做這件事需要的最小權限 | 切給子代理人 |
| 任務本身獨立自足,回傳一份摘要就好 | 切給子代理人 |
官方原句是這樣寫的:「Consider Skills instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.」(想要能重複使用、而且是在主對話 context 裡跑、不是隔離在子代理人 context 裡的流程時,考慮改用 Skills)——這句話正好點出兩者的分界線:要不要留在主對話的脈絡裡。
兩者也不是二選一、互斥的關係:回顧前面 context: fork 那個欄位,Skill 本身就能設定成丟進子代理人執行;反過來,子代理人的 frontmatter 也能用 skills 欄位預先載入某些 skill 內容——需要的時候可以搭著用,不用堅持只選一邊。
8.4 Hooks:讓某些動作「鐵定」自動發生
先講一個關鍵差別,這也是 Hook 存在的理由。你在第 5 章寫的 CLAUDE.md,裡面那些規則比較像「建議」——Claude 多半會照做,但偶爾可能跳過。Hook 不一樣,它是「鐵則」:只要到了你設定的那個時機,它一定會執行,沒有例外。
「建議」和「鐵則」差在哪——別搞混
第 5 章的 CLAUDE.md 是寫給 Claude 看的建議,它會盡量遵守,但不保證每次都做。如果某件事「非做不可、不能漏」——例如「每次改完檔案一定要排版」「絕對不准動到某個資料夾」——那就不能只靠 CLAUDE.md,要用 。Hook 到了時機一定會跑,這就是它和 CLAUDE.md 最大的差別。
Hook 常見的用途有:每次改完檔案自動排版、commit 前自動跑一次檢查、Claude 要動手前先攔下危險操作、需要你回應時發個通知。
聽起來很技術?好消息是:你不用自己學怎麼寫,直接叫 Claude 幫你寫就好。
-
動手做
直接用白話跟 Claude 說你要什麼
在對話框裡,用一句白話描述你要的自動化動作就好。不用懂語法,講清楚「什麼時候、做什麼」即可。例如下面這兩句,照著打都可以:
寫一個 hook,每次編輯檔案後自動跑 eslint。 寫一個 hook,擋掉任何對 migrations 資料夾的寫入。 -
讓它寫好,之後用 /hooks 檢查
Claude 會幫你把設定寫進
.claude/settings.json。寫好之後,你隨時可以用/hooks看看目前裝了哪些 hook。預期會看到Claude 會回報它建好了哪個 hook、在什麼時機觸發;之後打
/hooks,就會列出你目前所有已設定的 hook。
實際長怎樣:一個排版 Hook 的設定範例
如果你不只想「叫 Claude 幫你寫」,也想知道它實際寫出來的東西長什麼樣子——這裡直接攤開看。假設你要的是「每次改完檔案,自動跑一次排版檢查」,寫進 .claude/settings.json 的內容大概會是這樣:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "/path/to/lint-check.sh" }
]
}
]
}
}
matcher 欄位是拿來比對「哪些工具會觸發這個 hook」——這裡的 Edit|Write 代表「只要是 Edit 或 Write 這兩種改檔動作就觸發」,也可以寫 * 比對全部工具。command 欄位就是真正會被執行的那行 shell 指令,這裡指向一支排版檢查腳本。
如果反過來,你要的是「動手前先攔下來」——像本節一開始「擋掉對 migrations 資料夾的寫入」那個例子——寫法會落在 PreToolUse 那組,效果也不同:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "if": "Bash(rm *)", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
]
}
]
}
}
這裡多了一個 if 欄位:只有指令真的符合 Bash(rm *) 這個模式時才會觸發攔截,不是每次跑 Bash 都擋。command 型是目前最常見的 hook 類型;官方還支援 http(送去某個網址)、mcp_tool(呼叫已連線的 MCP 工具)、prompt / agent(丟給模型自己判斷是非)等進階類型,這些留到大師篇的〈Hooks 自動化〉章節細講。
退出碼在說什麼:一定要懂的三種結果
Hook 腳本執行完,用「退出碼」(exit code)告訴 Claude Code 結果怎樣,這個規則值得記住:exit 0 是「放行」,一切正常繼續;exit 2 是「攔下來」——腳本印在錯誤輸出(stderr)的內容,會被回饋給 Claude 當作「為什麼被擋」的理由;其他退出碼代表「這個 hook 本身出錯了」,動作不會被攔,但畫面上會顯示一句「<hook 名> hook error」提醒你去看。要特別提醒:只有像 PreToolUse 這類「動手前」的事件才擋得住動作,PostToolUse 這類「事後觀察」的事件就算 exit 2,也沒辦法讓已經發生的事情復原,只能把 stderr 的內容顯示給 Claude 看。
Hook 用的是你本人的完整權限,沒有沙盒
這點官方和社群都反覆提醒:Hook 是拿你目前登入的使用者權限直接跑 shell 指令,自動執行、沒有像其他危險操作那樣跳出來讓你逐次核准,也沒有任何沙盒隔離。如果你是從網路上複製別人的 hook 設定來用,動手前務必自己先讀過腳本內容再套進去——你不會希望一個來路不明的腳本用你的權限亂動你的檔案。(企業帳號另有 allowManagedHooksOnly 這道開關,可以只允許 IT 部署的 hooks,個人/專案/外掛層一律擋掉,但那是團隊管理者才需要煩惱的設定。)
還有一個容易忽略的小地方:如果你的 PostToolUse hook 是「自動排版」這類會真的改到檔案的動作,Claude 每次都會收到一則「這個檔案被改了」的系統提醒——次數一多,會慢慢吃掉不少 context。也因為每個專案慣用的排版工具、規則常常不一樣,社群普遍建議把這類 hook 放在專案層(複習 8.1 的四層設定檔)而不是個人層,讓它只在真的需要的專案裡發生。
想知道原理:hook 是在「什麼時機」觸發的?
Hook 是綁在「特定時機」上自動跑的。最常用的三個時機是:(Claude 動手用工具之前)、(動手之後)、(每次開始一段新對話時)。舉例:把「擋危險操作」綁在 PreToolUse,它就會趕在 Claude 真的動手前先攔下來;把「自動排版」綁在 PostToolUse,它就會在每次改完檔案後才跑。你不用記這些代號,叫 Claude 寫的時候它會自己選對時機——這裡列出來,只是讓你知道背後是怎麼運作的。
8.5 五個積木怎麼搭(官方的心智模型)
到這裡你已經碰過好幾種「客製化」的工具了。官方把 Claude Code 能客製的部分,歸納成五塊積木,各自解決不同的問題。先有個整體印象,之後要用哪一塊就比較不會混。
五個積木,各管一件事
CLAUDE.md= 每次都要讓它知道的「常態脈絡」(專案規範、你的習慣)。- Skills = 隨選的知識、可一鍵呼叫的流程(就是 8.3 做的那種)。
- MCP = 連接外部服務(下一章專講)。
- 子代理人() = 把工作隔離分工出去(高手篇會講)。
- Hooks = 自動化的鐵則(就是 8.4 做的那種)。
實際上它們常常搭在一起用。一個典型組合是:用 CLAUDE.md 放專案規範、用 Skill 放部署流程、用 MCP 連資料庫、用 Hook 在每次編輯後自動跑檢查。不用一次學會全部,需要哪塊再回來看哪塊就好。
官方部落格另外給了一個更實用的判斷角度:與其想「這五塊各自解決什麼問題」,不如想「養它要花多少 context 成本、指令的權威性有多高」。把這兩個維度放一起看,你會更清楚該把某條規則放進哪一塊:
| 積木 | 什麼時候用 | Context 成本 |
|---|---|---|
CLAUDE.md |
每次都要讓它知道的事實(build 指令、目錄結構、程式碼慣例)。 | 常駐載入,會持續吃 token。 |
| Skills | 有步驟的流程,隨選才用。 | 只在被呼叫時才載入,不用時幾乎零成本。 |
| MCP | 連接外部服務(資料庫、第三方工具)。 | 依連線的伺服器而定。 |
| 子代理人 | 會弄亂主對話、想隔離出去的旁支任務。 | 隔離執行,只把結果摘要傳回主對話。 |
| Hooks | 必須保證發生的事,不能只是「建議」。 | 純機械化執行,幾乎不佔對話 context。 |
| Output Style(第六塊) | 角色、語氣類、希望整段對話貫徹到底的長期改變。 | 直接改系統提示,權威性最高,且不受 /compact 壓縮影響。 |
表格最後多列的「Output Style」是第六塊,8.8 會專門帶你設定,這裡先知道它站在這張表的哪個位置就好。
一個好用的判斷訊號:CLAUDE.md 出現「每次都要」,通常代表該換 Hook
官方部落格點出一個很實用的反面訊號:如果你發現自己在 CLAUDE.md 裡寫「每次都要 lint」「絕對不要動這個資料夾」這種句子,多半代表這條規則要的「保證程度」已經超過 CLAUDE.md 能給的——它終究只是建議,Claude 大多數時候會照做,但不是每次。真的要「保證發生」,該搬進 8.4 教的 Hook,而不是繼續加強 CLAUDE.md 裡的措辭。
想知道原理:這五塊積木,各自在解決什麼問題?
它們的分工,其實對應五種不同的需求:CLAUDE.md 解決「有些事我每次都要它知道」(所以它常駐、每次載入);Skill 解決「有些流程我偶爾才用,但用的時候要完整」(所以它隨選、可一鍵叫);MCP 解決「我要它能碰到外部世界的服務」(資料庫、第三方工具);子代理人解決「這件事我想隔離出去讓另一個分身專心做」(不佔用主對話的脈絡);Hook 解決「這件事絕對不能漏」(所以做成鐵則,到時機一定跑)。看懂這五種需求,你就會知道下次該抓哪塊積木。
8.6 選模型與用量
這一節完全是「進階、非必須」的。 多數人用預設就很好,不用碰模型設定。等到你「想要更聰明一點」或「想省一點花費」的時候,再回來這裡照著挑就好。
Claude Code 背後其實有好幾種「模型」可以選,差別大致是「越聰明的,跑得越慢、花費越高」。你可以隨時切換,依當下任務挑剛剛好的那一個。切換的指令是 /model:在對話裡打它,就會讓你選要用哪個模型。
那要怎麼挑?用一張表記住「什麼時候用哪個」最快:
| 模型 | 個性 | 什麼時候用 |
|---|---|---|
| Opus | 最聰明、最會自己想 | 難的、要長時間規劃的任務:大改一段程式、複雜的除錯、需要它自己拆解步驟的工作。 |
| Sonnet | 速度和聰明的平衡 | 日常大多數工作的好選擇:一般的讀檔改檔、寫功能、整理內容,又快又夠用。 |
| Haiku | 最快、最省 | 簡單又重複的小事:分類、快速問答、瑣碎的小任務。便宜又快,適合量大的活。 |
除了換模型,還有一個 指令,可以調整 Claude 在「想」這件事上投入多少力氣——願意多花一點時間想得更周全,或是快一點給答案。一樣是「需要再用」,平常不用特別管。這兩個(/model、/effort)你都不設也能正常用,它們是給你「想再調細一點」時的工具。
範例:實際切換時可以這樣打
# 啟動時直接指定,只影響這一個 session
claude --model opus
# 對話中隨時切換,按 Enter 會存成新的預設值
/model sonnet
# 混合模式:規劃階段用 Opus 仔細想,動手改檔自動切回 Sonnet
/model opusplan
# 調整這個 session 的推理力氣
/effort high
# 想恢復模型的預設力氣
/effort auto
上面的 /model opusplan 值得多說一句:它是專門為「規劃要仔細、執行要快」設計的混合模式——進入計畫模式(第 7 章教過的 /plan)時自動用 Opus 做架構思考,一旦離開計畫模式開始實際改檔,又自動切回 Sonnet,你不用自己手動切兩次。
還有一個更輕量的技巧:不想切 /effort、只是這一輪想讓它多想一點,直接在你的訊息裡打 ultrathink 這個關鍵字(不是指令,就是打在句子裡的一般文字),Claude Code 會辨識並加深這一輪的推理,用完就恢復,不會動到這個 session 存下來的 effort 設定。如果你是團隊或企業帳號、想把「別人的 opus 到底指的是哪一版」鎖死,官方還提供 ANTHROPIC_DEFAULT_OPUS_MODEL 之類的環境變數,可以把模型別名釘死在特定版本號,避免它跟著官方更新自動漂移——這是團隊管理者才需要煩惱的細節,個人使用不用管。
關於花費:腳本化用法的用量怎麼算
有一種進階用法叫 claude -p(高手篇會講的腳本化、非互動式跑法),還有官方的「Agent SDK」。它們也會耗用量,但怎麼計費、是否跟你平常互動式對話的額度分開算,會依你的方案而定,這部分以官方公告為準(待官方確認)——本書不就具體額度或計費規則下定論,以免誤導。
現在你只要知道有這回事就好——日常一般對話照常使用即可。等之後(第 10 章、第 12 章)真的用到 claude -p 或 Agent SDK 時,再回官方文件確認當時的計費方式。
切了模型,隔天卻「自動變回原本的」?
先別懷疑自己設定失敗。如果你是公司或團隊帳號,個人的 /model 選擇有可能被組織層的預設模型、或允許使用的模型白名單蓋過去——複習 8.1 提過的「全公司層」設定,它的優先權比你的個人選擇高。遇到這種狀況,先確認是不是公司層的 managed 設定在跑,而不是你哪裡設錯了。
8.7 終端機的門面:主題、狀態列、Vim 模式與按鍵綁定
前面幾節都在講「Claude 怎麼做事」,這一節換個角度,講「畫面長什麼樣子、打字手感怎麼調」。這些全部是外觀類的個人化,改了不會影響它幫你做事的能力,純粹是讓你自己盯著螢幕的時候更順眼、打指令更順手。挑你在意的挑著看就好。
切換主題
覺得目前的顏色看不順眼,或想要更高對比?打 /theme(也可以從 /config 的選單裡找到主題那一項)叫出主題選單。內建六種:
| 主題 | 說明 |
|---|---|
dark / light |
標準深色/淺色,多數人預設用這組。 |
dark-daltonized / light-daltonized |
為色盲/色弱調整過的色版,紅綠對比更好分辨。 |
dark-ansi / light-ansi |
改用終端機軟體自己的 16 色調色盤,適合你已經在終端機裡自訂過配色、想讓 Claude Code 跟著用同一套。 |
還有一個 auto 選項:不自己挑顏色,而是跟著作業系統目前的深色/淺色模式自動切換,系統換你就跟著換,不用自己盯著手動改。
對紅綠對比不敏感?直接選 daltonized 版
dark-daltonized / light-daltonized 這兩組是特別調過的版本,不用等別人提醒,自己先試試看合不合適。
Vim 編輯模式
習慣 Vim 那套「按鍵移動、按鍵編輯」手感的人,可以打 /vim 開啟 Vim 風格編輯模式(也可以直接在 settings.json 裡設 "editorMode": "vim",讓它一開始就是這個模式)。開了之後,打字輸入框支援 hjkl 移動游標、v / V 進入選取、d / c / y 搭文字物件做刪除/修改/複製,這些都是 NORMAL/VISUAL 模式下最常用的操作。
是「常用子集合」,不是完整版 Vim
別誤會成整個編輯器都變成 Vim——這裡支援的是輸入框裡最常用的那部分操作,不是巨集、暫存器這類進階功能全都有。習慣了基本的 hjkl/dd/yy 已經很夠用;真的碰到某個 Vim 招式不支援,屬於正常範圍,別懷疑自己打錯。
重新綁定按鍵
對某個快捷鍵的位置不順手?打 /keybindings 會打開按鍵綁定的設定檔,裡面任何一個按鍵都能重新綁定成你要的組合。這個功能比較小眾,用到再回來查就好,不用特別背。
狀態列客製化:statusLine
畫面最下面那一行,可以放你想看到的即時資訊——目前用哪個模型、context 用了多少百分比、這輪對話花了多少錢,都能顯示在這裡。這是所有客製化裡「效果最直接看得到」的一個,跟著做一次就懂了。
-
動手做
打 /statusline,用人話描述你想看到什麼
不用自己寫程式、不用懂
jq怎麼用。直接打/statusline加上一句白話描述,Claude 會自動幫你生成腳本、寫進設定:/statusline 顯示目前的模型名稱和 context 使用百分比,用一個小進度條表示 -
畫面最下面那一行,就會照你說的樣子更新
Claude 會把腳本寫進
settings.json的statusLine欄位,運作方式是:每次要顯示前,Claude Code 把這個 session 的資料(模型名稱、目前目錄、context 用量、花費等)用 JSON 格式透過標準輸入傳給你的腳本,腳本印到標準輸出的內容,就是畫面上看到的那一行。預期會看到畫面最下方多出一行,內容照你描述的樣子顯示;之後每次 Claude 回完一則新訊息、每次
/compact完成、切換權限模式或 Vim 模式,這一行都會跟著刷新一次。
想自己動手寫也可以。statusLine 支援多行輸出、ANSI 顏色碼、甚至 OSC 8 超連結。下面是一個最簡單的手動範例:在 settings.json 裡指定一行 jq 指令,解析從標準輸入送進來的 session JSON,抓出模型名稱和 context 使用率:
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}
如果你希望這行內容會自己跳動(例如放個時鐘),可以另外設 refreshInterval 讓它定時重新整理,不用等有新訊息才刷新。
8.8 換一套系統提示:Output Style
前面幾節都是「它做什麼」,這一節是「它怎麼跟你互動」。 直接改寫 Claude 的系統提示,換一套「說話的方式」——不只是語氣,連它主動教不教你、要不要留步驟給你自己動手,都可以整套換掉。
除了預設風格,內建還有兩種:Explanatory(講解型)會在完成任務的同時,穿插幾則「Insights」小提示,邊做邊教你背後的原理;Learning(協作學習型)走得更遠,它會主動在關鍵的地方停下來,請你自己動手寫一小段程式碼,而不是全部代勞。想練功、不只想要成品的話,Learning 這個模式值得一試。
切換方式
# 不加參數:打開選擇清單自己選
/output-style
# 直接指名切換
/output-style Explanatory
切換的結果會存進個人本機層(.claude/settings.local.json,複習 8.1 的那張層級表)——只影響你自己、只影響這個專案。
也可以自己描述一套風格,讓 Claude 幫你寫
打 /output-style:new,用白話描述你想要的風格(例如「回答前一定先列出風險,語氣正式一點」),Claude 會幫你在 ~/.claude/output-styles(個人層,跨專案通用)產生一份新的 markdown 設定檔。跟 8.3 做 Skill 一樣,不用自己懂語法,講清楚就好。
回頭對照 8.5 那張表:Output Style 是六塊積木裡權威性最高的一塊——它直接改寫系統提示本身,而且不受 /compact 壓縮影響,適合放「角色、語氣」這種你希望整個對話從頭到尾都貫徹的長期設定,不像 CLAUDE.md 那樣可能在對話很長之後被稀釋。