簡短回答
- 1用名稱呼叫：
/skill-name或$skill-name。能執行，代表安裝沒問題。 - 2找不到？檢查資料夾：
SKILL.md必須直接放在<skills folder>/<name>/裡。 - 3還是不行？在下方找到你遇到的情況。
30 秒找出問題所在
在左欄找到你看到的現象，再跳到右欄對應的解法。
用名稱呼叫失敗
Skill 不在 Agent 會找的位置。請見清單裡找不到 Skill。
用名稱能執行，平常提出需求時卻不會啟動
檢查描述或設定。請見 Skill 不會自動觸發。
執行的是另一個 Skill
兩個 Skill 的描述重疊了。請見執行了錯的 Skill。
開始執行後又停下來
缺少它需要的東西。請見執行到一半失敗。
執行的還是舊版本
別處還有另一份，或工作階段沒有更新。請見還是舊版本。
Claude Code、Codex 或 Cursor 的清單裡找不到 Skill
如果 /skills 或 Customize → Skills 裡沒有它，代表 Agent 沒有載入。最常見的原因是資料夾放錯位置，或多包了一層。
| 可能原因 | 解法 |
|---|---|
用 Skillry CLI 幫 Claude Code 安裝時，沒有加上 --agent claude-code | 加上這個參數重新安裝。不加的話，CLI 會使用 ~/.agents/skills/ |
| ZIP 解壓後多了一層資料夾 | 把內層資料夾往上移一層。Claude Code 需要的結構必須剛好是 skills/<name>/SKILL.md |
--- 之間的 frontmatter 有錯 | 修正它。Codex 和 Cursor 需要 name 與 description，而且在 Cursor 中 name 必須與資料夾名稱相同 |
| Agent 還沒讀到它 | Claude Code：/reload-skills。Codex：在該 repo 內重新啟動。Cursor：開新對話或重新載入視窗 |
ChatGPT 桌面版裡的 Codex：輸入 $ 找不到任何東西 | 這是已回報的 bug（openai/codex#28505）。檢查 /skills、重新啟動，或試著在 ~/.codex/skills/ 放一份（我們尚未實測） |
各 Agent 會讀取的所有資料夾，請見 Skill 存放位置。
Skill 有出現，但不會自動觸發
Agent 是讀 Skill 的描述來決定要不要使用它。如果 Skill 只有在你用名稱呼叫時才會執行，要嘛是描述和你的提問方式對不上，要嘛是某個設定擋住了它。
- 試試 Skill 頁面上的範例提示詞。它是照著描述寫的。
- 檢查
paths。它會把自動使用限制在符合條件的檔案上。 - 裝了很多 Skill？Agent 為了全部塞得下，會縮短或捨棄部分描述，所以要把主要用途寫在最前面。請見觸發機制。
執行的是另一個 Skill
當兩個已安裝的 Skill 描述同一件工作，它們就會互相競爭，Agent 會挑讀起來更貼近你需求的那一個。通常是因為裝了兩個做類似工作的 Skill，或同一個 Skill 裝了兩次。
| 發生了什麼 | 解法 |
|---|---|
| 某個類似的 Skill 一直勝出 | 用名稱呼叫你要的那個：Claude Code 和 Cursor 用 /skill-name，Codex 用 $skill-name。用名稱呼叫一定會執行該 Skill。 |
| 你自己的 Skill 彼此重疊 | 依輸入、對象或產出縮小每個描述的範圍，讓每個 Skill 只負責一件工作。請見觸發機制。 |
| 同一個名稱裝了兩次 | Claude Code 會先用 Enterprise，其次是個人，最後是專案。Codex 可能兩個都列出。只保留一份。 |
| 某個 Skill 在你沒要求時一直自己啟動 | 把它的描述寫得更具體，說清楚何時該用，讓它不再對應到無關的需求。然後用名稱呼叫你要的 Skill。請見觸發機制。 |
開始執行後，中途失敗
這幾乎都是缺少相依項目：Node.js 版本不對，或沒有 Python、FFmpeg 或 FAL key。Skill 頁面會列出它需要的東西，請先檢查：
一直執行舊版本
你更新了 Skill，但 Agent 的表現還是跟以前一樣。原因會是以下其中之一：
- 只替換了
SKILL.md。用--force重新安裝，或替換整個資料夾。 - 別處還裝了一份同名的 Skill。把它移除。
- 在 Claude Code 中，已經執行過的 Skill 在該對話的剩餘時間都會維持原樣。開新對話才會套用你的修改。
備份與回復舊版，請見管理與更新。
在你的電腦上可以，到雲端就不行
雲端工作階段在另一台機器上執行，所以只存在你電腦上的 Skill 不會跟著過去，除非你另外設定：
| Agent | 解法 |
|---|---|
| Claude Code | 雲端工作階段：把它 commit 到 .claude/skills/，或在 claude.ai 開啟它。Cowork：在 claude.ai 開啟它。 |
| Codex | 獨立的 Skill 不會出現在網頁版或行動版 ChatGPT。請把它包進 plugin 發布。 |
| Cursor | 放在 ~/.cursor/skills/，然後開啟 Settings → Agents → Context and Tools → Sync Skills for Cloud Agents。 |
Skillry CLI 錯誤訊息
找到 Skillry CLI 印出的訊息，照右欄的說明處理。
| 你看到的訊息 | 這樣處理 |
|---|---|
| 「Not logged in.」或「Session expired.」 | 執行 npx --yes skillry-cli@latest login |
| 「…already exists. Re-run with --force to replace it safely.」 | 加上 --force。舊的那份會自動備份 |
| 「This Skill requires a paid plan.」 | 確認 Skill 的價格或你的方案 |
| 「--agent and --target cannot be used together.」 | 兩者擇一 |
| 「Secure session storage is currently supported on macOS and Windows only.」 | 在 Linux 上，請改用安裝提示詞或下載 ZIP |
常見問題
為什麼我的 Claude Code Skill 沒有載入？
通常是放在 ~/.agents/skills/ 而不是 ~/.claude/skills/，或多了一層資料夾。修正路徑；如果是新資料夾，再執行 /reload-skills。
為什麼我的 Skill 要我提供 API key？
它用到了付費服務，Skill 頁面的「外部費用」會列出來。請依該服務的說明設定 key，絕對不要貼到對話裡。
怎麼知道安裝成功了？
它會出現在 /skills（Cursor 為 Customize → Skills），而且用名稱呼叫時能執行。
參考來源
這篇指南對你有幫助嗎？