つまずき辞典

症状別の対処

作ったのに、ふだんの頼み方で呼ばれない

第08章の点検順そのままです。①説明文に自分の言い回しが入っているか ②ファイル名がSKILL.mdか・置き場所は正しいか ③先頭の設定部分が壊れていないか ④作りすぎで説明文が削られていないか。第08章の「やってみよう②」の依頼文で、点検ごと任せられます。

スキルの一覧に、そもそも出てこない

いちばん多い原因は、その会話の開始後にskillsフォルダ自体を新しく作ったことです。Claude Codeを立ち上げ直してください。それでも出なければ、置き場所が第05章の2か所から外れています。「このスキルがどこにあるか探して、正しい場所へ移して」と頼んでください。

「/名前」と打てば動くのに、ふだんの言葉では動かない

先頭の設定部分（---で挟まれた数行）の書式が壊れているサインです。壊れていると本文だけが読み込まれ、説明文が空扱いになるので、直接呼べば動くのに自動では選ばれません。「このスキルの設定部分の書式を点検して、壊れていたら直して」で解決します。

スキルを増やしたら、前より呼ばれなくなった

一覧表の枠（全体の1%）からあふれて、呼ぶ回数が少ないスキルの説明文が削られています。第13章の棚卸しで、今月呼んでいないスキルを退避してください。枠が空けば説明文は戻ります。

症状別の対処

関係ない依頼のときにまで発動する

説明文が広すぎます。「〜には使わない」を1行足すのが第一手（第07章）。それでも止まらなければ「このスキルを手動専用にして」と頼んで、自分が/名前で呼ぶときだけ動く設定（disable-model-invocation）に切り替えます。

手順書どおりに仕上がらないことがある

手順に矛盾があるか、例外の扱いが書かれていないケースが大半です。うまくいかなかった実例を貼って「この場合の扱いをスキルに追記して」と頼んでください。まとめて直すより、1行ずつ足すほうが早く安定します（第14章）。

長い会話の途中から、スキルの指示が効かなくなった気がする

会話が長くなると、Claudeは古いやり取りを要約して容量を空けることがあり、その際にスキル本文の一部が畳まれることがあります。効きが怪しくなったら、/名前でもう一度呼び直してください。全文が読み直されます。

直したはずなのに、直る前の動きをする

同じ名前のスキルが別の場所にもあって、そちらが勝っている可能性があります。同名は管理用→個人用→プロジェクト用の順で強いのでしたよね。「この名前のスキルが何か所にあるか探して」と頼むと、すぐ特定できます。

症状別の対処

ブラウザ版Claudeへのアップロードで弾かれる

先頭の設定部分に、標準の6項目（name・description・license・compatibility・metadata・allowed-tools）以外が混ざっています。「このスキルをブラウザ版Claudeに持ち込める形に直してzipにして」と頼めば、項目の整理ごとやってくれます。

スキルにパスワードやAPIキーを書いていいか迷う

書かないでください。スキルはただのテキストで、コピーも共有も簡単にできてしまいます。秘密の値は専用の置き場（環境変数や鍵管理）に置いて、スキルには「どこを参照するか」だけを書きます。この設計もClaudeに相談できます。

配布されているスキルを入れたいが、少し不安

その不安は正しいです。スキルは指示とプログラムでClaudeに新しい動きをさせるものなので、悪意ある作りなら危険もあります。公式も「信頼できる出どころのものだけを使い、導入前に中身を確認する」よう求めています。入れる前に「このスキルの中身を全部読んで、何をするものか、怪しい動きがないかを報告して」とClaudeに監査させてください。特にscriptsの中身は必ず。

パソコンの買い替えでスキルを失いそう

スキルはフォルダなので、コピーがそのまま引っ越しです。第13章の「やってみよう①」で控えを作り、新しいパソコンの同じ場所（~/.claude/skills/）に置けば、そのまま動きます。