よくあるSkill作成エラーと対処法

TROUBLESHOOTING よくある Claude Skill 作成エラーと対処法 6つの典型パターンから学ぶ うさうさ研修工房

6つのエラーパターン一覧 まずは全体像から ① 呼び出されない descriptionが曖昧 ② エディタでエラー表示 YAMLバリデータの解釈違い ③ コンテキスト圧迫 本文が長すぎる ④ 長い会話で指示を忘れる 自動再読み込みされない ⑤ 誤発火／不発火 トリガー条件の設計不足 ⑥ メモリでの応急処置 根本原因を直していない 2

エラー1 descriptionが曖昧で、 Skillが呼び出されない Claudeは起動時、全Skillの name と description だけを読み込む。 本文がどれだけ詳しくても、descriptionが曖昧だと選ばれない。 ✕ 弱い例 description: プロジェクトの コードをレビューします ○ 強い例 PythonコードのOWASP Top10脆弱性チェック。 セキュリティ診断時に使用 ポイント：「何を」と「いつ」の両方を、具体的なトリガーワードで書く 3

エラー③④ 本文の肥大化と、長い会話での指示忘れ ③ 原因 ③ 対処 SKILL.md本文は呼び出されるたびに 詳細情報は references/ に分割。 会話へまるごと読み込まれる。 本文は500行未満を目安に、 詳細を書き込みすぎるとコンテキストを圧迫する 必要な時だけ読みに行く設計にする ④ 原因 ④ 対処 Skillは呼び出された時点の内容が 「1回限りの手順」でなく 読み込まれるだけで、後のターンで 「タスク全体のスタンディング指示」 自動的に再読み込みされない として書く。状態はファイルに保存する 4

エラー5 誤発火する／必要な場面で呼ばれない チェックの型（ 3ステップ） 1 descriptionを読み返し、起動ワードが自然な言い回しか確認する 2 実際に「〜して」と話しかけてみる 3 呼ばれなかったら起動ワードを足す、呼ばれすぎたら否定条件を足す 5

エラー6 メモリでの応急処置に逃げてしまう 「こう言われたらこのSkillを呼ぶ」というルールをメモリに保存して回避する → 根本原因（descriptionの曖昧さ）を直していない、対症療法 SKILL.md自体のdescription・本文を直して解決する →「スキル本体が適切に書かれていれば起動するはず」に立ち返る 6

まとめ 1 9割の不具合は description の書き方に起因する 2 本文は「メニュー」、詳細は references/ に分割する 3 Skillは一度作って終わりではなく、使いながら育てていくもの うさうさ研修工房