Claude Code「Unknown skill」の原因｜スキルが呼べない時の直し方

Claude Codeで「/」から始まるコマンドや自作のスキルを呼んだのに、「Unknown skill: ○○」と出て何も動かないことがあります。原因は1つではなく、版の違いや置き場所などに分かれます。

本記事では、公式ドキュメントと変更履歴、GitHubに寄せられた報告をもとに、原因を「標準のコマンドが今の版にない」「版の不具合」「自作スキルの置き場所と名前」「会話の途中で見えなくなる」の4つに分けて、見分け方と直し方を解説します。

Claude Codeの「Unknown skill」とは

呼んだ名前のスキルが見つからないという表示

「Unknown skill」は、呼び出した名前のスキル（またはコマンド）が、今のセッションで見つからないという意味です。Claude Codeでは自作のコマンドもスキルとして扱われるため、標準のコマンドでも自作のスキルでも同じ表示になります。

最近の版でこの表示が出るのは、主にClaude（AI）がスキルを呼び出す仕組みの中で名前が見つからなかったときです。公式の変更履歴でも、v2.1.269とv2.1.299でこの「Unknown skill」の表示が改善され、正しい名前を示すようになっています。

今の版では打ち間違いは「Unknown command」と出る

今の版では、ターミナルで存在しない名前を打つと「Unknown skill」ではなく、次の表示になります。公式のエラー一覧に載っている例です。

Unknown command: /hepl. Did you mean /help?（訳）不明なコマンドです：/hepl。/help のことですか？

v2.1.274以降はターミナル以外（-pでの実行、デスクトップアプリ、VS Codeのチャット欄、クラウドなど）では、合わない名前はClaudeへの普通のメッセージとして送られます。手元で「Unknown skill」と表示されたなら、古い版を使っているか、Claudeがスキルを呼んで失敗したかのどちらかを疑うのが近道です。

原因1：標準のコマンドが今の版にない

/buddyは4月1日向けに追加された機能

「Unknown skill」の報告で最も反応が多いのが/buddyです。GitHubの報告（#45525）では、v2.1.97へ自動更新されたあとに次の表示が出て動かなくなったと、2026年4月9日に報告されています。

Unknown skill: buddy（訳）不明なスキルです：buddy

変更履歴では、/buddyはv2.1.89で「4月1日向け」として追加された、コードを書く様子を見守る小さな生き物の機能です。廃止の記載はありませんが、11月9日時点の公式コマンド一覧には載っていません。今の版では呼べないものとして扱い、設定で直そうとしないのが安全です。

/dreamは公式のコマンド一覧に載っていない

/dreamも同じ表示が続いている例です。GitHubの報告（#38461）では、/memoryの画面に「/dream to run」と案内が出るのに、打つと「Unknown skill: dream」になると3月24日に報告され、9月9日にもv2.1.267で同じ症状が書き込まれています。報告は11月9日時点で未解決のままです。

今の公式コマンド一覧にも、記憶の機能のページにも/dreamの記載はなく、手元の設定で解決できる問題ではありません。

古い版では新しいコマンドがまだ使えない

版が古いと、後から追加されたコマンドは「Unknown skill」になります。GitHubの報告（#33000）では、画面の右下に「/effort」と表示されているのに、打つと次の表示が出ました。

Unknown skill: effort（訳）不明なスキルです：effort

この報告は「v2.1.76で修正済み」として閉じられました。一方で9月11日にも、v2.1.12という古い版で/effortが同じ表示になったという報告（#93700）が出ています。ブログやドキュメントで見たコマンドが動かないときは、まず自分の版を確かめてください。

原因2：版の不具合ですべてのコマンドが呼べない

v2.1.89で全コマンドが失敗し2.1.91で直った

特定の版の不具合で、すべてのコマンドが一斉に「Unknown skill」になったこともあります。GitHubの報告（#42069）では、v2.1.87からv2.1.89へ上げた直後に/commitなどのコマンドがすべて失敗しました。この不具合はv2.1.91で修正されています。

昨日まで動いていたコマンドが急に全部呼べなくなった場合は、設定を疑う前に、更新の直後かどうかを思い出してください。版を上げ直すだけで直るケースです。

v2.1.76より前は表示そのものの不具合があった

変更履歴のv2.1.76には「スラッシュコマンドで"Unknown skill"と表示される不具合を修正」とあります。先ほどの/effortの報告が閉じられたのもこの版で、古い版を使い続けているなら、更新するだけで消える表示があるということです。

原因3：自作スキルの置き場所と名前

スキルを置ける場所は決まっている

公式のスキルのドキュメントでは、自作スキルの置き場所が決まっています。個人用は「~/.claude/skills/スキル名/SKILL.md」、プロジェクト用は「.claude/skills/スキル名/SKILL.md」で、プラグインに入ったスキルは「/プラグイン名:スキル名」の形で呼びます。

これ以外の場所に置いたスキルは読み込まれません。GitHubには、別のツールで「~/.agents/skills/」に入れたスキルが「Unknown skill」になったという報告（#53950）もあります。また、「synced」という名前のフォルダはclaude.aiから同期したスキル用に予約されていて、自分で作っても読み飛ばされます。

名前に使えない文字がある

同じドキュメントによると、スキルの名前に次の文字が入っていると、その名前は受け付けられません。フォルダ名が受け付けられないとスキルそのものが読み込まれず、SKILL.mdの「name」欄だけの場合はその名前で呼べなくなります。

• ゼロ幅スペースや制御文字
• 全角スペースなど、半角スペース1つ以外の空白
• 文字の向きを変える文字や、「<」「>」

この場合は起動時に「1 skill or command name refused」で始まるお知らせが出ます。どの名前が問題かは、後述する手順4のデバッグ記録で確かめられます。

クラウドとCoworkでは手元のスキルを読まない

CoworkやClaude Codeのクラウドのセッション（クラウドの定期実行を含む）は、手元のパソコンの「~/.claude/skills/」を読みません。クラウドでも使いたい場合は、claude.aiのアカウントでそのスキルを有効にするか、リポジトリの「.claude/skills/」に入れてコミットします（どちらが使えるかはセッションの種類で変わります）。

原因4：会話の途中でスキルが見えなくなる

下の階層やpaths付きのスキルは後から読み込まれる

起動した場所より下の階層にある「.claude/skills/」は、起動時には読み込まれません。Claudeがそのフォルダのファイルを読むか編集した時点で初めて使えるようになり、それまでは呼んでも見つからない、というのが公式の仕様です。先に読ませたいときは、v2.1.257以降なら/add-dirでそのフォルダを追加します。

対象のファイルを指定する「paths」を付けたスキルでは、一度使えたのに途中で消える報告もあります。GitHubの報告（#103776）では、v2.1.304で6時間半後に「Unknown skill: css-cop. Did you mean tsx-cop?」となり、該当のファイルを読み直すと戻ったとされています。11月9日時点で未解決です。

worktreeに移ったあとに見えなくなる報告

Gitのworktree（同じリポジトリを別のフォルダで並行して開く機能）に移ったあと、プロジェクトのスキルが「Unknown skill」になるという報告（#102589）があります。v2.1.296で報告され、v2.1.302でも変わらないと追記されています。

公式ドキュメントでは、v2.1.277以降、worktree側に「.claude/skills」がなければ本体側のスキルを読むとされています。それでも見えない場合は、worktreeの中でClaude Codeを起動し直し、「/」の一覧に出るかを確かめてください。

スキルが多いと一部が読み込まれない報告

プロジェクトに置いたスキルが多いと、一部しか読み込まれないという報告（#93044）もあります。61個のスキルのうち約14個しか一覧に載らず、残りは名前を正確に指定しても「Unknown skill」になったという内容で、11月9日時点で未解決です。

上限の数は公式に書かれていないので、使わないスキルを減らして症状が変わるかで切り分けます。

確認と直し方の順番

手順1：claude --versionで版を確かめて更新する

まず、ターミナルで今の版を確かめます。11月9日時点の最新はv2.1.319です。v2.1.89なら原因2の不具合、v2.1.76より前なら表示の不具合に当たっている可能性があります。

claude --version

古ければ、公式のセットアップ手順にある次のコマンドで更新します。

claude update

手順2：「/」を打って一覧に出るか確かめる

入力欄で「/」に続けて名前の一部を打つと、そのセッションで使えるコマンドとスキルの候補が出ます。ここに出てこなければ、読み込まれていないか、原因1のように今の版にないコマンドです。

自作スキルが一覧に1つも出ない場合は、置き場所やフォルダの形の問題が考えられます。次の記事で詳しく解説しています。

関連記事：Claude Code「No skills found」の原因｜スキルが出ない時の直し方

手順3：/reload-skillsか新しいセッションで読み直す

セッションの途中でスキルを足したり書き換えたりしたときは、/reload-skillsで読み直します。v2.1.152で追加されたコマンドで、再起動せずにスキルのフォルダを読み直してくれます。

/reload-skills

会話の要約（compact）のあとにスキルが見えなくなった場合も、v2.1.304以降は要約後にスキルの一覧がClaudeへ送り直されます。それでも直らなければ、新しいセッションを始めてください。

手順4：claude --debugで読み込みの記録を見る

ここまでで直らなければ、デバッグモードで起動して記録を確かめます。名前が受け付けられなかったスキルは、記録の中の「[names]」の行に出ます。

claude --debug

SKILL.mdの書式の誤りは、v2.1.233以降なら「claude plugin validate .claude/skills」で探せます。

スキルの作り方そのものを確かめたい場合は、次の記事も参考にしてください。

関連記事：【実践ガイド】Claude Code Skills実装の完全版｜自動化を加速させるスキル作成と3つの管理術

まとめ

「Unknown skill」は、呼んだ名前のスキルやコマンドが今のセッションで見つからないという表示で、原因は次の4つに分かれます。

• 標準のコマンドが今の版にない：/buddyや/dreamは今の公式コマンド一覧にない
• 版の不具合：v2.1.89で全コマンドが失敗し、v2.1.91で修正された
• 置き場所と名前：決まったフォルダに置き、使えない文字を名前に入れない
• 会話の途中で消える：/reload-skillsか新しいセッションで読み直す

まずはclaude --versionで版を確かめ、古ければclaude updateで更新してから、「/」の一覧に名前が出るかを確かめてください。

​