結論から
- 1名前で呼び出す：
/skill-nameまたは$skill-name。実行されれば、インストールは問題ありません。 - 2見つからない場合はフォルダを確認します。
SKILL.mdは<skills folder>/<name>/の直下に置く必要があります。 - 3それでも解決しない場合は、下から当てはまる症状を探してください。
30 秒で原因を特定する
左側から今の症状を探し、右側の対処法に進んでください。
名前で呼び出しても失敗する
エージェントが探す場所にありません。Skill が表示されないを参照してください。
名前で呼べば動くが、普通の依頼では動かない
説明文か設定を確認します。Skill が自動で動かないを参照してください。
別の Skill が動く
2 つの説明文が重なっています。別の Skill が動くを参照してください。
動き始めてから止まる
必要なものが足りていません。途中で失敗するを参照してください。
古いバージョンが動く
別のコピーがあるか、セッションが古いままです。古いバージョンを参照してください。
Claude Code・Codex・Cursor に Skill が表示されない
/skills や Customize → Skills に Skill がなければ、エージェントはそれを読み込んでいません。多くの場合、フォルダの場所が間違っているか、階層が 1 つ深すぎます。
| 考えられる原因 | 対処法 |
|---|---|
Skillry CLI で Claude Code 向けにインストールしたが、--agent claude-code を付け忘れた | このフラグを付けて再インストールします。付けないと、CLI は ~/.agents/skills/ を使います |
| ZIP の展開でフォルダが 1 階層増えた | 内側のフォルダを 1 つ上に移動します。Claude Code は skills/<name>/SKILL.md の形をそのまま必要とします |
--- の行で囲まれた frontmatter に誤りがある | 修正します。Codex と Cursor には name と description が必要で、Cursor では name をフォルダ名と一致させる必要があります |
| エージェントがまだ認識していない | Claude Code：/reload-skills。Codex：リポジトリ内で再起動。Cursor：新しいチャットを開くかウィンドウを再読み込み |
ChatGPT デスクトップアプリの Codex で、$ を入力しても何も見つからない | 報告済みのバグです（openai/codex#28505）。/skills を確認して再起動するか、~/.codex/skills/ にコピーを置いてみてください（この方法はまだ検証していません） |
各エージェントが読み込むすべてのフォルダは、Skill の保存場所を参照してください。
Skill は表示されるのに自動で動かない
エージェントは説明文を読んで、Skill を使うかどうかを判断します。名前で呼んだときしか動かないなら、説明文と依頼の仕方が合っていないか、設定が Skill を止めています。
- Skill のページにあるサンプルプロンプトを試してください。説明文に合うように書かれています。
pathsを確認します。これを設定すると、自動での利用は一致するファイルに限られます。- Skill をたくさんインストールしていますか？すべてを収めるために、エージェントは説明文を短くしたり省いたりします。主な用途を先頭に書きましょう。トリガーの仕組みを参照してください。
代わりに別の Skill が動く
インストール済みの 2 つの Skill が同じ仕事を説明していると、両者が競合し、エージェントは依頼により近いほうを選びます。たいていは、似た作業用の Skill が 2 つあるか、同じ Skill が 2 回インストールされています。
| 起きていること | 対処法 |
|---|---|
| 似た Skill がいつも選ばれてしまう | 使いたい Skill を名前で呼び出します。Claude Code と Cursor では /skill-name、Codex では $skill-name。名前で呼べば、必ずその Skill が動きます。 |
| 自作の Skill 同士が重なっている | 入力・対象・成果物で各説明文を絞り込み、1 つの Skill が 1 つの仕事だけを担当するようにします。トリガーの仕組みを参照してください。 |
| 同じ名前が 2 回インストールされている | Claude Code は Enterprise、個人、プロジェクトの順に優先します。Codex は両方を表示することがあります。コピーは 1 つだけ残してください。 |
| 頼んでいないのに、ある Skill が毎回動き出す | いつ使うべきかを説明文でより具体的に書き、無関係な依頼に一致しないようにします。そのうえで、使いたい Skill を名前で呼び出してください。トリガーの仕組みを参照してください。 |
動き始めたのに途中で失敗する
ほぼ確実に依存関係の不足です。Node.js のバージョン違い、あるいは Python、FFmpeg、FAL key がないケースです。Skill のページに必要なものが書かれているので、まずそこを確認してください：
古いバージョンのまま動き続ける
Skill を更新したのに、エージェントが以前の動きのままになる場合、原因は次のいずれかです：
SKILL.mdだけを置き換えた。--forceで再インストールするか、フォルダごと置き換えてください。- 同じ名前の別のコピーが他の場所にインストールされている。それを削除してください。
- Claude Code では、一度実行された Skill はその会話が終わるまで元のままです。変更を反映するには新しい会話を始めてください。
バックアップとロールバックについては、管理と更新を参照してください。
手元では動くのにクラウドでは動かない
クラウドセッションは別のマシンで動くため、自分のコンピューターにしかない Skill は、設定しない限り持ち込まれません：
| エージェント | 対処法 |
|---|---|
| Claude Code | クラウドセッション：.claude/skills/ にコミットするか、claude.ai で有効にします。Cowork：claude.ai で有効にします。 |
| Codex | 単体の Skill は Web 版やモバイル版の ChatGPT には届きません。プラグインに含めて配布してください。 |
| 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 では、インストールプロンプトか Download ZIP を使ってください |
よくある質問
Claude Code の Skill が読み込まれないのはなぜですか？
たいていは ~/.claude/skills/ ではなく ~/.agents/skills/ に入っているか、フォルダが 1 階層多くなっています。パスを直し、フォルダが新しい場合は /reload-skills を実行してください。
Skill が API key を求めてくるのはなぜですか？
有料サービスを使う Skill だからです。どのサービスかは、Skill ページの「外部コスト」に記載されています。そのサービスの案内どおりに key を設定し、チャットには絶対に貼り付けないでください。
インストールできたかどうかを確認するには？
/skills（Cursor では Customize → Skills）に表示され、名前で呼び出すと実行されれば成功です。
出典
このガイドは役に立ちましたか？