Claude Code skill：如何建立，附範例與最佳實務

Claude Code skill 是什麼

如果你總是在對話裡反覆貼上同樣的指示、檢查清單或多步驟流程，或者 CLAUDE.md 裡某一部分已經從一條事實膨脹成一套流程，就該把它做成 skill。skill 遵循開放的 Agent Skills 標準（agentskills.io），其他 AI 工具也能讀取；Claude Code 在此之上加入了呼叫控制、以 subagent 執行，以及在提示詞裡嵌入即時 shell 輸出等功能。

• 兩種執行方式：當你的請求和它的 description 相符時由 Claude 載入，或是你輸入 /skill-name。
• 不用就幾乎不花錢：脈絡裡只放名稱和描述，skill 執行時才載入內文。設定為只能手動執行的 skill 連描述都不會列出。
• 自訂斜線指令現在就是 skill：.claude/commands/<name>.md 仍然可用，但 skill 資料夾還能放輔助檔案。參見 Claude Code 斜線指令。
• Claude Code 也有隨附的 skill，例如 /simplify、/loop、/batch 和 /debug。

skill、CLAUDE.md、subagent、外掛與 MCP 比較

如何建立 Claude Code skill

1. 選好存放位置

   ~/.claude/skills/<name>/ 供你自己在所有專案裡使用；儲存庫裡的 .claude/skills/<name>/ 提交後，所有在這個儲存庫工作的人都能用。資料夾名稱就是指令名稱，所以 summarize-changes 對應 /summarize-changes。

2. 撰寫 SKILL.md：先寫描述，再寫指示

   frontmatter 放在檔案最頂端的兩行 --- 之間。只有 description 是建議填寫的：把使用情境和大家實際會說的話放在最前面。下方用 Markdown 寫指示。以 ` !command ` 開頭的一行會先執行這條指令，再把輸出貼進去，讓 skill 能根據你的實際狀態運作。

   ---
   description: 摘要尚未提交的變更，並標出有風險的地方。當使用者問改了什麼、想要一則 commit message，或要求審查 diff 時使用。
   ---
   
   ## 目前的變更
   
   !`git diff HEAD`
   
   ## 指示
   
   用兩三個重點摘要上面的變更，然後列出風險，例如缺少錯誤處理、
   寫死的值，或需要更新的測試。

3. 兩種方式都測試看看

   在一個有未提交修改的 git 專案裡啟動 claude。先問「我改了什麼？」，看看 Claude 會不會自己用上這個 skill，再輸入 /summarize-changes 直接執行它。工作階段中新增的 skill 會自動載入；如果某個沒出現，執行 /reload-skills。

4. 決定誰可以執行它

   部署、傳送訊息這類有副作用的操作，加上 disable-model-invocation: true，這樣只有你能啟動它。只該由 Claude 載入的背景知識，加上 user-invocable: false。用 $ARGUMENTS 傳入輸入，用法見斜線指令指南。

5. 分享它

   把 .claude/skills/ 提交到儲存庫，或把 skill 打包成外掛，供多個儲存庫或團隊使用。

來源：Claude Code 文件，Extend Claude with skills

Claude Code skill 範例

1. 只對符合的檔案載入的參考型 skill

   參考型 skill 存放 Claude 工作時要遵守的慣例。paths 把自動載入限制在符合這些 glob 的檔案上。

   ---
   description: 這個程式碼庫的 API 設計慣例。撰寫或審查 HTTP 端點時使用。
   paths: ["src/api/**"]
   ---
   
   撰寫 API 端點時：
   - 使用 RESTful 命名，資源名稱用複數
   - 錯誤以 { error: { code, message } } 的形式回傳
   - 用 src/api/schemas/ 裡的 schema 驗證請求內容

2. 帶輔助檔案的任務型 skill

   讓 SKILL.md 保持簡短，其餘內容用指引帶過去。只有 SKILL.md 要 Claude 去讀時，它才會讀 checklist.md；bump.sh 則直接執行而不讀取，所以這些細節在用到之前不佔任何成本。

   release/
   ├── SKILL.md          # 步驟，以及什麼時候讀其他檔案
   ├── checklist.md      # 只有 SKILL.md 要 Claude 去讀時才載入
   └── scripts/
       └── bump.sh       # 直接執行，不讀進脈絡

3. 在獨立 subagent 中執行的 skill

   context: fork 會啟動一個 subagent（這裡是唯讀的 Explore 類型），以 skill 作為它的提示詞。它看不到你的對話，所以指示必須能獨立成立；除非設定 background: false，它會在背景執行。

   ---
   description: 稽核相依套件中的已知漏洞和落後的主要版本
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   執行套件管理工具的 audit，列出每個高風險或嚴重問題及其修正版本，
   並回報哪些套件落後了主要版本。不要修改任何檔案。

從外掛和外掛市集安裝 skill

別人寫的 skill 通常裝在外掛裡。第一次啟動互動式工作階段時，Claude Code 會註冊 Anthropic 的官方外掛市集（claude-plugins-official）；用 /plugin 瀏覽，或直接安裝，例如 /plugin install skill-creator@claude-plugins-official。團隊或社群的外掛市集，先用 /plugin marketplace add owner/repo 加入。

• 外掛裡的 skill 命名為 /plugin-name:skill-name。
• 官方外掛市集會顯示每個外掛每一輪以及被呼叫時的脈絡成本。
• skill-creator 外掛能幫你撰寫 skill，並執行評估，比較使用與不使用它時的結果。
• 信任一個儲存庫或外掛的 skill 之前先讀一讀：allowed-tools 可以在 skill 執行的那一輪預先核准工具。

最佳實務，以及 Claude 忽略 skill 時怎麼辦

• 描述要為比對而寫：先寫清楚要做的事和使用者會說的話。在清單裡，描述加上 when_to_use 超過 1,536 個字元的部分會被截掉。
• 最重要的指示放在前面：對話被壓縮後，Claude Code 可能只保留已呼叫 skill 的開頭部分。再呼叫一次就能恢復。
• 針對整個任務來寫指引（「每次編輯後都執行測試」），因為之後的輪次不會重新讀取 skill 檔案。絕對不能略過的規則應該放進 hook。
• 想減少 token 用量，就把流程從 CLAUDE.md 移到 skill 裡，替手動執行的 skill 設定 disable-model-invocation: true，再用 /skill-doctor 找出佔用脈絡卻很少使用的 skill。
• 沒有觸發？檢查描述裡有沒有對的關鍵字，問一句「有哪些可用的 skill？」，再執行 claude plugin validate .claude/skills 找出無法解析的 frontmatter。
• 觸發太頻繁？把描述寫得更窄，或用 disable-model-invocation: true 把 skill 改成手動執行。

skill 教會 Claude Code 怎麼做，Crewmark 讓它每小時都有事可做。

一套 skill 讓每個工作階段都更能幹，但它仍然要等你開口。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段變成有職位、目標和工作時間的 AI 員工，並依心跳喚醒它，從看板上接手下一個 issue，同時載入你專案裡的 skill。

1. 把 skill 留在儲存庫裡

   員工的工作階段會像你的一樣讀取 .claude/skills/ 和 CLAUDE.md，所以發佈 skill 或審查檢查清單都會一起帶過去。

2. 讓心跳啟動工作

   在工作時間內，員工每 15、30 或 60 分鐘在同一個對話中醒來一次，接手下一個 issue；參見如何讓 Claude Code 主動工作。

3. 指派 issue，回覆它的訊息

   把工作放到看板上；員工會邊做邊留言，需要你拍板時傳訊息給你。閱讀什麼是 AI 員工。

Claude Code skill 常見問題