疑難排解技能

疑難排解技能

重點整理

• 從技能驗證工具開始——它能在您花時間除錯其他問題之前，先找出結構性問題
• 如果技能無法觸發，原因幾乎總是出在描述上——加入符合您實際提出請求方式的觸發詞句
• 如果技能無法載入，請檢查 SKILL.md 是否位於具名目錄內（而非技能根目錄），且檔名是否完全為 SKILL.md
• 如果使用了錯誤的技能，表示您的描述過於相似——請讓它們更具區別性
• 對於執行階段錯誤，請檢查相依套件、檔案權限（chmod +x）以及路徑分隔符號（請一律使用正斜線）

當技能無法運作時，問題通常會落在以下幾個類別之一：技能無法觸發、無法載入、發生衝突，或在執行階段失敗。好消息是，大多數修正方法都相當直接。

使用技能驗證工具

首先要嘗試的是 claude plugin validate 指令。在您的 shell 中，針對個人技能執行 claude plugin validate ~/.claude/skills，或針對專案技能執行 claude plugin validate .claude/skills。此功能需要 Claude Code v2.1.233 或更新版本。

驗證工具會找出 frontmatter 無法解析的 SKILL.md 檔案，讓您在花時間除錯其他問題之前先發現這個問題。上方影片展示的是另一個您可以透過 uv 安裝的獨立驗證工具。

技能無法觸發

您的技能存在且通過驗證，但 Claude 在您預期的時候卻沒有使用它。原因幾乎總是出在描述上。

Claude 使用語意比對，因此您的請求需要與描述的意義有所重疊。如果重疊不足，就不會匹配。以下是您該做的事：

• 檢查您的描述是否符合您實際提出請求的方式
• 加入使用者實際會說出的觸發詞句
• 用各種變化方式測試，例如「幫我分析這個的效能」、「為什麼這個這麼慢？」、「讓這個更快一點」
• 如果任何一種變化方式無法觸發，請將那些關鍵字加入您的描述中

技能無法載入

如果您詢問 Claude「有哪些可用的技能」時，您的技能沒有出現，請檢查以下結構性要求：

• SKILL.md 檔案必須位於具名目錄內，而非技能根目錄
• 檔名必須完全為 SKILL.md——「SKILL」全部大寫，「md」小寫

執行 claude --debug 以查看載入錯誤。尋找提及您技能名稱的訊息。有時光是這樣就能直接指出問題所在。

使用了錯誤的技能

如果 Claude 使用了錯誤的技能，或在多個技能之間感到混淆，您的描述可能過於相似。請讓它們更具區別性。盡可能具體不僅能幫助 Claude 決定何時使用您的技能，也能防止與其他名稱相似的技能發生衝突。

技能優先順序衝突

如果您的個人技能被忽略，可能是因為有一個企業或更高優先順序的技能使用了相同的名稱。



舉例來說，如果有一個企業「code-review」技能，而您也有一個個人「code-review」技能，企業技能每次都會勝出。您的選項：

1. 將您的技能重新命名為更具區別性的名稱（這通常是較簡單的做法）
2. 與您的管理員討論該企業技能

外掛技能未出現

安裝了外掛卻看不到它的技能？執行 /plugin 並檢查該外掛是否列在已安裝項目下且已啟用，然後查看錯誤分頁。如果您是在本次工作階段中安裝的，請執行 /reload-plugins。

如果之後技能仍未出現，可能是外掛結構有誤。技能會從外掛根目錄下的 skills/ 目錄載入，而非從 .claude-plugin/ 內部載入。在您的 shell 中，對該外掛的目錄執行 claude plugin validate，以檢查其清單檔以及每個技能的 frontmatter。

執行階段錯誤

技能已載入但在執行期間失敗。幾個常見原因：

• 缺少相依套件： 如果您的技能使用外部套件，這些套件必須已安裝。請將相依套件資訊加入您的技能描述中，讓 Claude 知道需要什麼。
• 權限問題： 指令碼需要執行權限。請對您技能所參照的任何指令碼執行 chmod +x。
• 路徑分隔符號： 請一律使用正斜線，即使在 Windows 上也是如此。

快速疑難排解檢查清單

• 無法觸發？ 改善您的描述並加入觸發詞句。
• 無法載入？ 檢查您的路徑、檔名與 YAML 語法。
• 使用了錯誤的技能？ 讓各描述之間更具區別性。
• 被遮蔽了？ 檢查優先順序階層，必要時重新命名。
• 外掛技能遺失？ 檢查 /plugin 是否有錯誤，然後執行 /reload-plugins。
• 執行階段失敗？ 檢查相依套件、權限與路徑。

課程反思

• 您在自己的工作中是否曾遇過這些疑難排解情境？哪一種修正方法能為您節省最多時間？
• 您會如何建立一套流程，在與團隊分享技能之前先進行驗證？

課程總結

恭喜您完成「Agent Skills 入門」課程！您已經學會如何在 Claude Code 中建立、設定、分享與疑難排解技能。當您開始為自己的工作流程建立技能時，請記住，最好的技能往往來自真實的痛點——從您發現自己最常重複的指示開始著手。