Zilmac 博客
← 返回技術實踐

如何為 Claude Code 建立自訂 Skills?從 SKILL.md 撰寫、目錄配置到實際呼叫的完整教學

AIDevelopment ·約 9 分鐘閱讀

依照 Agent Skills 格式規範,SKILL.md 的 frontmatter 至少要有 name 和 description 兩個欄位。因此,建立 Claude Code 自訂 Skills 的做法很明確:先依官方規則撰寫 SKILL.md,放進 Claude Code 支援的 Skills 目錄,再用實際任務確認它能被識別、呼叫,且輸出符合指令;目錄、欄位及呼叫規則可能調整,開始前應核對 Claude Code Skills 官方文件。

適合正在使用 Claude Code、想把重複開發任務整理成可重用流程的開發者。
如果您正在配置個人或專案級 Skills,或需驗證 AI Agent 工作流程能否穩定呼叫,也可依步驟操作。

先確認 Claude Code 自訂 Skills 的完成標準

>

完成建立,不等於只存下一個 Markdown 檔。建議以三項檢查作為驗收:

  • 檔案存在且格式有效:SKILL.md 位於支援的 Skills 目錄,檔名與必要 frontmatter 符合規則。
  • 範圍符合預期:專案成員需要共用的 Skill 放在專案級目錄;個人工作流程則放在使用者級目錄。
  • 透過任務驗證:確認 Claude Code 能辨識該 Skill,並觀察它是否按照正文中的條件和步驟處理測試任務。

前兩項只能確認設定看起來正確,不能證明呼叫行為符合預期。最後一項應使用可檢查的輸出,例如指定檔案清單、固定格式的摘要或明確的檢查步驟,而不是只問「有沒有成功」。

Claude Code 自訂 Skills 的 SKILL.md 應該怎麼寫?先交代 Skill 要做什麼、何種任務適用,以及遇到什麼條件時應停止或詢問;正文再寫操作步驟和輸出要求。只寫寬泛用途,模型便缺少判斷何時使用、如何完成的依據。

第一步:選好 Skills 目錄,再建立檔案

>

Claude Code 官方文件區分專案級與使用者級 Skills。專案級路徑是 .claude/skills/<skill-name>/SKILL.md,適合與程式碼一同管理、供該專案工作流程使用;使用者級路徑是 ~/.claude/skills/<skill-name>/SKILL.md,適合在不同專案重用的個人設定。路徑應以官方文件列出的目錄規則為準。

建立時要確認目錄層級:SKILL.md 放在 Skill 自己的資料夾內,而不是直接放在 .claude/skills/ 根目錄。以下是專案級的示意結構:

my-project/
└── .claude/
    └── skills/
        └── review-change/
            └── SKILL.md

命名也會影響辨識和呼叫。官方規則要求 Skill 名稱使用小寫字母、數字與連字號;名稱長度上限為 64 個字元。不要以空格、底線或大寫字母取代這些格式,細節可對照官方命名及目錄說明。

Claude Code Skills 的目錄應該如何配置?若工作流程只服務目前專案,放專案級目錄;若要在不同專案沿用,放使用者級目錄。若內容涉及團隊共用、需要隨程式碼審查或版本管理,優先考慮專案級設定;若流程包含個人偏好或不應提交至專案的指令,則放在使用者級目錄。

第二步:用清楚的 frontmatter 和正文定義 Skill

>

name 是識別名稱,description 則應說明用途與適用情境;後者會影響自動匹配,因此不要只寫「協助開發」這種泛用描述。官方格式要求和欄位說明請以Claude Code Skills 文件為準。

以下是示意範例,目標是檢查變更摘要,不代表在任何專案中都能保證得到相同結果:

---
name: review-change
description: 檢查目前程式碼變更的風險與測試缺口。當使用者要求檢視變更、提交前檢查,或要求整理差異時使用。
---

# 變更檢查

1. 先查看目前的程式碼差異,不要修改檔案。
2. 按影響範圍整理可能的錯誤與相容性風險。
3. 檢查是否缺少能驗證變更的測試。
4. 以「發現事項、影響、建議驗證」列出結果。
5. 如果沒有發現問題,明確說明已檢查的範圍;不要宣稱整個專案沒有缺陷。

這個例子把用途、適用條件、執行順序和輸出格式拆開,並將「不修改檔案」列為邊界。若任務還需補充參考資料或輔助指令,可按官方支援的檔案結構擴充;不要假設任意檔案都會自動載入。想參照完整寫法,可閱讀官方 Skill 建立範例。

提醒:frontmatter 是 YAML 格式,冒號、縮排與引號錯誤都可能讓欄位無法正確解析。新增選用欄位前,先查閱目前文件確認欄位名稱及值的格式,不要直接套用舊範例。

第三步:檢查配置範圍與載入條件

>

儲存後,先逐項核對,而不是立刻假設 Claude Code 一定已載入:

  • 路徑:檔案是否位於專案級或使用者級支援目錄?有沒有多建一層子資料夾?
  • 檔名:名稱是否精確為 SKILL.md,而不是大小寫不同或副檔名重複?
  • frontmatter:name、description 是否存在並採用合法格式?有沒有 YAML 語法錯誤?
  • 描述:是否指出要處理的任務類型,讓適用情境和一般對話需求有所區別?
  • 設定影響:是否有專案設定或其他指令限制 Skill 的使用?需要時查閱官方設定文件,不要把設定檔的規則和 Skill 正文混為一談。

不同版本的載入與欄位支援可能有差異。尤其是 frontmatter 選用欄位、呼叫控制方式和重新載入行為,應以正在使用版本的官方說明核對;專案記憶文件和 Skills 的用途不同,可另參考官方記憶功能文件,不要把 CLAUDE.md 當作 SKILL.md 的替代品。

目錄已設好,Claude Code 如何識別並呼叫自訂 Skills?先確認檔案路徑和描述,再分開測試明確呼叫與自動匹配。兩種方式適用條件不同,是否可用也可能受 frontmatter 設定影響,不能只靠一次對話就判定整個設定正確。

第四步:明確呼叫,再測自動匹配

>

可先嘗試使用 /技能名稱 明確呼叫,例如 /review-change,並提出一個範圍清楚的檢查任務。若 Skill 設定不允許使用者明確呼叫,或目前版本對呼叫方式有差異,應以官方文件為準;官方命令參考可協助確認命令相關行為。

接著獨立測試自動匹配:在新對話描述一項與 description 相符的任務,不輸入 Skill 名稱,觀察 Claude Code 是否採用該 Skill 的步驟。不要把明確呼叫成功當成自動匹配也有效;測試時分開記錄兩種結果。

可用以下任務檢查示意 Skill:

  1. 確認目前目錄是預期專案,並準備一組可檢視的程式碼差異。
  2. 明確呼叫 /review-change,要求只檢查差異、不修改檔案。
  3. 記錄輸出是否包含發現事項、影響和建議驗證,以及是否遵守不修改檔案的要求。
  4. 開啟新對話,以相同目的但不同措辭提出請求,測試自動匹配。
  5. 比較兩次結果;若漏掉步驟、輸出格式不同或沒有採用 Skill,返回調整 description、正文條件或路徑,再重跑兩項測試。

評估時應看可觀察的行為,不要只看模型是否提到 Skill 名稱。若要研究 Skill 與外掛的結構差異,可參考官方外掛文件;建立單一自訂 Skill 時,仍應先按 Skills 文件配置,避免把外掛打包規則誤認為必要條件。

Claude Code 自訂 Skills 沒有觸發時怎麼排查?依序檢查目錄層級、SKILL.md 檔名、frontmatter 格式與 description 的適用描述,再分別重試明確呼叫和自動匹配。若明確呼叫有效、但自動匹配不穩定,優先補足描述中的任務線索與不適用情況;若兩者都無效,先回頭核實路徑、名稱和版本規則,而不是先重寫整段工作流程。

用條件分支選擇目錄與驗證方式

>
  • 若 Skill 應隨專案共享、受版本管理,選擇專案級目錄;否則回到使用者級目錄,避免把個人流程提交給團隊。
  • 若要確認功能可用,先做明確呼叫;若要確認模型能自行選用,再以符合描述的自然語句單獨測試自動匹配。
  • 若輸出偏離預期,先修改最相關的適用描述或執行指令,再重複同一組測試;若檔案未被辨識,先檢查路徑與格式,不要把內容問題和載入問題混在一起。

建立 Claude Code Skills 的價值,在於把一次次口頭交代整理成可檢查的流程;能否可靠重用,仍取決於指令是否明確、目錄是否正確,以及團隊是否持續驗證。先挑一項真實、重複發生的開發任務,依本文範例建立 Skill,並用明確呼叫和自動匹配各測一次。

如果後續流程需要遠端環境,應再依工作負載評估:本機環境受個人裝置可用性限制,共用開發環境則需要確認權限與交付方式,而非所有任務都適合改用雲端 Mac。需要在 Mac 環境驗證工作流程時,可先查看 Zilmac 的雲端 Mac 使用資訊,再對照 Mac 遠端使用說明確認環境是否符合需求;若工作必須依賴手邊實體介面,或長期固定使用同一台裝置,自購或沿用本機往往更直接。

為你的開發流程配置一台專屬雲端 Mac

使用 Zilmac 租用 Apple M4 裸金屬雲端 Mac,在完整 macOS 環境中編寫、測試及執行自動化工作流程。

透過 SSH 或 VNC 遠端連線,按需要選擇記憶體配置與資料中心,讓開發環境更貼合你的工作節奏。 — 立即了解套餐方案

限時優惠

Zilmac

使用 Zilmac 租用 Apple M4 裸金屬雲端 Mac,在完整 macOS 環境中編寫、測試及執行自動化工作流程。

返回首頁
限時優惠 點擊查看套餐