Skills：如何為代理裝上現成的技能

您總在重複同一個要求：看一下改動、檢查這些檔案、按這樣的方式排版、別改這個地方。每次您都得從頭解釋一遍流程，而且每次都稍微不一樣。

結果隨著措詞起伏不定。今天做得很好，明天您忘了一半的條件，代理就老老實實照它聽到的去做。

解決這個問題的不是代理的記憶力，而是一個放著指示的資料夾。Skill 是只需寫下一次的流程，Claude Code 可以自行載入它，也可以依您的指令載入。我們來看看這個資料夾放在哪裡、怎樣確認 skill 已經裝好，以及第一次執行前要檢查什麼。

什麼是 skill

在開始看檔案和欄位之前，先建立一點直覺。

想像一個木匠。他把自己習慣的工作順序寫下來一次，準備好備忘、模板和機床程式。現在只要簡短地說："收拾乾淨、磨好鑽頭，接著做貓椅 - 啟動 CNC 模板"。一啟動，就開工了。

寫下來的流程把整套工作串在一起：

• 按您的規則整理。收拾工作台、擺好工具 - 每次都一樣，完全照您習慣的方式。
• 遵守寫下來的邊界。鋸子還在轉 - 不伸手。安全的部分馬上做，不多問。
• 需要時翻看備忘。要磨鑽頭了 - 就翻開磨削規則。不必事先記在腦子裡，用到時再拿出來。
• 為不同工作備好模板。從桌子換做椅子 - 拿出現成的準備方案。
• 一條指令啟動複雜的工作。重複鋸切的程式已經放在旁邊了。只要說："找出貓椅模板，送去 CNC" - 機床就會照著間隙和工序加工。

Skill 也是這樣運作的。它不是代理手上又多一個工具，而是一套打包好的流程。主要指示記下順序和邊界，參考資料在需要時補上細節，模板裝著半成品，腳本負責跑重複的機械步驟。寫一次，之後直接呼叫就行。

Skill 格式本身不會隔離任何東西。指示可以把工作限定在排版範圍內，但 CSS 和邏輯之間並沒有技術上的隔牆。好的 skill 會明確寫出工作範圍；執行後，您要查看改動的檔案，並檢查頁面的行為。"能運作"和"好看"是不同的層面，保證來自檢查，而不是格式。

Skill 放在哪裡

這裡沒有什麼雲端魔法。Skill 就是磁碟上的一個資料夾，就在您自己的專案裡：

.claude/skills/web-design/SKILL.md

路徑一段一段來看：系統資料夾 .claude，裡面是 skills，再裡面是 skill 本身的資料夾（名稱由您決定），其中有檔案 SKILL.md。就是普通的文字檔，用什麼都能打開。

對於專案裡和主資料夾裡的 skill，只要檔案本身沒有另外設定名稱（後面會說明），資料夾名稱就是斜線指令的名稱。所以取名時就要想好它在聊天裡看起來是什麼樣子。

接著修正一個最常見的印象：skill 不是單一檔案，而是一個資料夾。SKILL.md 旁邊可以放任何東西。

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # 主要檔案：描述和指示
        ├── palettes.md   # 參考資料，代理在需要時會打開它
        └── scripts/
            └── check.py  # 可以執行的腳本

在自動選擇時，代理能看到的是 skill 的名稱和簡短描述，而不是全部內容。SKILL.md 在執行時才載入，旁邊的參考資料則是需要時才載入。所以長篇備忘不會事先佔滿上下文。

一般在本機工作時，重要的 skill 來源有三個：

~ 符號代表使用者的主資料夾。在指令中照原樣寫；如果要手動打開資料夾，請到您自己的主目錄。

前兩個位置的差別很簡單，值得馬上弄清楚。

把資料夾放進專案 - skill 就只在這個專案裡有效。打開隔壁的專案，那裡就沒有它。

主資料夾裡的 skill 在所有專案都能用。這對通用流程很方便，但它也可能在您沒料到的地方啟動。通用的放在主資料夾，專案專用的留在專案裡。

如果 Claude Code 使用獨立的課程設定檔 ~/.claude-codegym/ 執行，個人 skill 就放在該設定檔的 skills/ 資料夾。專案路徑 .claude/skills/ 不會因設定檔而改變。

Description 決定 skill 何時啟動

常見的情況：資料夾放好了，檔案也在，代理卻跟以前一模一樣。沒有東西壞掉 - 它只是沒看出這個 skill 適用於這裡。

看看代理在做選擇的那一刻手上有什麼。skill 的正文它還沒讀過：載入的只有名稱和描述的清單。也就是說，判斷只能依據描述，沒有別的依據。

我們從頭到尾做一個專案用的最小 skill。它的名稱是 web-design - 資料夾就叫這個名字，指令 /web-design 也由此而來。這裡我們不在檔案裡另外寫名稱，資料夾已經定好了：

.claude/skills/web-design/SKILL.md

內容就是這樣，其他都不需要：

---
description: 整理網頁介面 - 現代 CSS、流暢的轉場、協調的配色。
  當使用者要求做得漂亮或有風格時使用。
---

# 網頁設計

使用柔和的陰影、流暢的轉場和講究的字體排印。
配色保持協調，動畫用在滑鼠懸停和元素出現時。

上方兩行三個連字號之間是設定區塊，下方是一般的指示文字。沒有必填欄位，但 description 一定要寫：少了它，代理只能根據正文第一段猜 skill 的用途，那就是碰運氣了。

好的描述回答兩個問題：skill 做什麼、什麼時候用。而且要用您實際寫請求時會用的字詞。

# 沒反應：不知道什麼時候該用
description: 協助排版

# 會啟動：寫清楚做什麼、什麼時候用
description: 整理介面 - CSS、字體排印、配色。
  當使用者要求做得漂亮、有風格或修正版面時使用。

描述決定的是 skill 什麼時候自動啟動。但這不是唯一的入口：skill 有名稱，可以用名稱手動呼叫。輸入 /web-design - 這時描述完全不相干，檔案會被讀取並執行。

現成的 skill 常常有 name 欄位。對於專案和主資料夾中的 skill，它決定了 / 選單中顯示的指令：資料夾 deploy-staging 裡寫了 name: deploy，就要用 /deploy 呼叫。資料夾名稱也仍然可以使用。在外掛中，name 可以決定指令中外掛名稱後面的最後一段。

所以啟動的路有兩條，之後的步驟完全相同。

左邊的分支是自動的：請求與描述相符，代理選用了 skill。右邊是手動的：輸入 /web-design，不管描述寫什麼，skill 都會執行。

Skill 和內建指令出現在同一個 / 選單中。檔案 .claude/commands/deploy.md 和 skill .claude/skills/deploy/SKILL.md 會建立同一個指令 /deploy；如果兩者都存在，以 skill 為準。

安裝與檢查

資料夾放好了。怎麼知道代理真的看到了它，而不只是檔案躺在磁碟上？

/skills

這個指令會打開 skill 清單，並顯示各自的來源。輸入幾個字母，清單就會篩選。找到您的資料夾名稱和狀態 on - 代表 Claude Code 看得到這個 skill，也允許執行它。

名稱、來源和狀態 on 確認 skill 可以使用

通常 Claude Code 會即時讀到新增或修改過的 SKILL.md。如果清單裡沒有這個名稱，請依序嘗試：

Skill 在清單裡，卻不會自動啟動？這跟重新載入無關。請檢查 description 和 disable-model-invocation: true 欄位 - 它會讓 skill 只能手動執行。換個說法重新提出請求，或直接用名稱呼叫 skill。手動呼叫能用，就代表安裝沒問題。

信任之前要檢查什麼

這裡得先冷靜一下。Skill 不是佈景主題，也不是一張圖片，可以隨手裝上又拿掉。它是一組指示，您的代理會在您的專案裡照著執行。

要檢查的不只是主要檔案，而是整個資料夾。先從四件事開始：

• 描述 - 是否符合您對 skill 的期待，會不會啟動得太廣泛；
• 正文和其中的連結 - skill 要代理做什麼、要求打開哪些相鄰檔案；
• scripts/ 資料夾（如果有的話）- 裡面會執行哪些指令、會動到哪些檔案和網路位址；
• allowed-tools 欄位 - skill 預先允許哪些工具不必另外詢問就能使用。

---
name: pre-commit-style
description: commit 前把專案統一成共同的風格
allowed-tools: Read, Write, Edit, Glob
---

這裡的 allowed-tools 不是在描述工作計畫，也不會限制代理完整的能力範圍。這個欄位只是在呼叫 skill 的那一回合，預先核准列出的工具。這些名稱很好懂：

• Read - 讀取檔案；
• Write - 建立新檔案，或整個覆寫現有檔案；
• Edit - 在現有檔案內部做修改；
• Glob - 依模式搜尋檔案，也就是在專案裡四處看看到底有哪些東西。

第一個和最後一個只是查看。Write 和 Edit 能修改檔案：如果指示導向這類動作，這一回合可能就不會另外詢問您。但有權限不代表代理一定會用。專案一般的存取規則同樣繼續有效。

這個欄位本身不是壞東西：它能在您本來就希望的地方省掉多餘的確認。但工具組合是 skill 作者選的，所以值得在第一次執行前看一下。

最後一點沒那麼嚇人，但常見得多。Skill 是在引導代理，而不是保證結果。執行後請查看改動的檔案並檢查結果：排版用的 skill 可能讓頁面更好看，但按鈕能不能用，沒有人替它擔保。

去哪裡找現成的

想試試看的話，完全不必從零開始寫 SKILL.md。現成的 skill 大多來自公開的儲存庫，或是隨外掛一起取得。

最快的方法是請代理找一個合適的版本，但不要閉著眼睛安裝。請求可以這樣寫：

找一個介面排版用的 skill。給我看來源、SKILL.md 和腳本，
說明它會用到哪些檔案和工具。在我確認之前
什麼都不要安裝。

看過來源和內容之後，再請代理把資料夾放進專案的 .claude/skills/，並用 /skills 檢查結果。

如果想自己找，可以搜尋 Claude skills marketplace。目錄能幫您找到選項，但不代表安全：安裝前一樣要先讀過內容。

SKILL.md 遵循開放的 Agent Skills 標準，所以基本結構可以在不同代理之間通用。但 Claude Code 另外加了自己的欄位和啟動方式。把 skill 搬到另一個工具時，請確認那邊實際支援哪些功能。

自己的 skill 可以和代理一起做

什麼時候該做一個自己的 skill，不需要任何理論就看得出來：同一個流程您已經解釋第三次了。不是任務本身，而是步驟順序 - 看一下那個、檢查這個、照這樣排版、這裡別動。一再重複，就表示時機成熟了。

好消息是：不必從空白頁開始寫 SKILL.md。代理可以幫您做出草稿，您只要說明這是什麼流程、希望它做到什麼。看起來就像一般的對話：

幫我做一個準備 commit 用的 skill。它要查看改了什麼、
檢查有沒有多餘的檔案混進 commit，並照我們的模板
寫 commit 訊息。我會在想用的時候手動執行。
如果需求不夠清楚，先問我問題。

請注意，您一個欄位都沒提到，也沒去研究檔案結構。需求用一般的話說清楚，把它們轉成欄位是代理的工作。

資訊不夠時，代理會提出問題。沒有這句請求，它可能直接自行假設，所以範例裡已經放了這一行。拿到草稿後，檢查檔案，用 /skills 找到這個 skill，再試跑一次。

如果這個流程能手動走一遍，就在打包前先和代理一起做一次。一個照步驟完成的 commit 會讓您看到哪裡需要修正、說明裡缺了什麼。根據實際操作寫出的 skill，比憑記憶寫的更準確。

當 SKILL.md 越長越大

您的第一個 skill 幾乎都只有一個檔案，這很正常。之後才會開始擠：流程的細節越來越多，對照表、規則清單、三個長範例都搬了進來，某天您打開檔案，發現它有四個螢幕那麼長。

沒必要把所有東西都塞在同一個地方，原因前面已經提過：skill 一開始執行，正文就會整個載入。即使只需要其中一行，四個螢幕的參考資料也會一起進入工作。

所以細節要移到相鄰的檔案，在 SKILL.md 裡只留下指引：遇到某種情況，就打開某個檔案。放著 palettes.md 和 scripts/ 的資料夾您已經看過了，它的內部是這樣的：

## 參考資料

- 配色和顏色搭配 - 見 [palettes.md](palettes.md)
- 現成的標記範例 - 見 [examples.md](examples.md)
- 檢查對比度：執行 scripts/check.py

參考資料由代理在需要時打開。腳本可以直接執行，不會把整份原始碼自動載入對話，所以檔案大小幾乎不佔上下文。但別人寫的腳本，第一次執行前還是要先讀：它是可執行的程式碼，而它的輸出會進入代理的工作中。

依用途來分類會比較方便：

• SKILL.md - 流程本身：做什麼、按什麼順序、什麼不要做。呼叫之前代理看到的是描述，正文在執行時才載入；
• 參考資料 - 表格、規則、長範例，以及所有不是每次執行都需要的內容；
• scripts/ - 直接執行比用文字描述更簡單的部分。在別人的 skill 裡，這些檔案要在執行前檢查；
• 模板 - skill 拿來當基礎、再依任務修改的檔案。

由此也能得出反過來的結論，這次是關於別人的 skill。SKILL.md 很短，不代表這是"簡單的 skill"。看看資料夾裡它旁邊還放了什麼。

這對工作有什麼改變

如果濃縮成幾行：

• 重複的請求變成一個資料夾。工作順序只寫一次，之後在任何工作階段、任何一天都能以同樣方式重現；
• 自己的 skill 不必從空白頁寫起。用一般的話說明流程，請代理補問缺少的部分，再檢查它做好的草稿；
• 自動啟動時，skill 是依 description 選出的；手動啟動則是用斜線加名稱。如果它沒反應，先確認它有沒有出現在清單裡、是否允許自動啟動；
• /skills 回答的是"它到底裝好了沒有"。花半分鐘檢查，省下半小時的猜測；
• 別人的 skill 要在安裝和執行前讀過，連同相關的檔案和腳本；
• Skill 改變的是代理做事的方式，但它不會隔離修改範圍，也不能取代對結果的檢查。