クロードコードのスキルファイルを実際に動作させる6つのパターン

r/ClaudeAIの開発者が3ヶ月かけて2,300以上のコミュニティおよび自作スキルファイルをテストし、ほとんどのClaude Codeスキルがなぜ有効にならないのかを調査しました。重要な発見は、多くのスキルが~/.claude/skills/に保存されているものの、Claudeが実際に使用するアクティベーションパターンに従わずに配置されているため、決して起動しないということです。以下がスキルが読み込まれるかどうかを決定する6つのパターンです。

パターン1: 説明文に具体的なトリガー言語を含める

ClaudeはYAMLのdescription:フィールドを読み取り、スキルがいつ関連するかを判断します。「データベース関連の作業を支援」のような一般的な説明では決してトリガーされません。一方、「データベース接続プールの設定、プールサイズの選択、接続枯渇のデバッグ時に使用」のような具体的な説明は確実にトリガーされます。説明文はスキルの発見可能性を決める基本要素であり、単なる飾りではありません。

パターン2: 1ファイルに1つの機能に絞る

「すべてのSQL関連」をカバーするスキルは、マイグレーション作成、インジェクション修正、クエリ計画説明という3つの個別スキルに負けます。Claudeのマッチングはユーザーのプロンプトと各スキルの説明のコサイン類似度を使用します。希釈された説明は弱くマッチし、具体的な説明が勝ちます。

パターン3: フロントマターの規約が重要

Claudeが実際に使用するフィールドはname、description、category、difficultyです。オプションですが便利なのはtagsです。カスタムキーは解析されますが、アクティベーションには影響しません。ランダムなメタデータを追加しても処理が遅くなることはありませんが、助けにもなりません。

パターン4: 使用すべきでない場合のリスト

「このスキルは～の場合には使用しないでください」という明示的なリストは、アクティベーションをより正確にします。ネガティブな例を提供し、トリガー範囲を制限します。このセクションを省略することは、コミュニティスキルで最も一般的な間違いです。

パターン5: 実際にコンパイルできるコード例

スキルに構文エラーを含むコードブロックがあると、例が説明と矛盾するため、Claudeはスキルを避ける方向に働きます。保存前にすべてのコードブロックを構文チェッカーで確認してください。

パターン6: 本文に検証手順を含める

「これを実行した後、～で確認する」といった検証セクションを含むスキルは、タスク実行中のアクティベーション信頼性が高まります。検証アンカーは、Claudeが「これがユーザーの意図に合致するスキルだ」と判断する助けになります。

6つのパターンをすべて満たすスキル例

• smart-commit — パターン1 + 6
• connection-pool-setup — パターン2
• sql-injection-fix — パターン4
• redis-lua — パターン5
• error-handling-audit — パターン6
• api-documentation — パターン1
• angular-rxjs — パターン2
• trpc-router — パターン5
• dockerfile-generator — パターン4
• infrastructure-as-code — パターン3
• custom-slash-commands — パターン1
• placebo-detector — パターン4

これらのスキルはclskillshub.com/browseで参照できます。また、6つのパターンを使って自分で作成することもできます。