【2026年版】Claude CodeのSKILL.md活用術｜自作スキル実装と最適化ガイド

Claude Codeを使いこなす上で、プロンプトの肥大化は避けたい課題だ。多くのユーザーが「指示をどこまで書くべきか」で迷う。結論として、知識を「常駐させる（CLAUDE.md）」か「呼び出す（SKILL.md）」か「機械的に検知する（ASTルール）」の3層構造で整理するのが最適だ。特にSKILL.mdは、トリガーフレーズを明記することでAIの判断精度を向上させる。この記事では、1人SaaS開発でClaude Codeを活用する視点から、実践的なSKILL.mdの活用術を解説する。

1. SKILL.mdの基本構造

SKILL.mdは、Claude Codeに特定の作業を任せるための「専用命令書」だ。フロントマターとMarkdown本文で構成される。フロントマターには「name」と「description」を記述する。nameはディレクトリ名と一致させる必要がある。最も重要なのはdescriptionだ。ここに「いつ呼び出すか」というトリガーフレーズを具体的に書くことが、Claude Codeに正しく認識させるための鍵となる。

2. スキルのインストール手順

インストールは .claude/skills/<スキル名>/SKILL.md にファイルを配置するだけで完了する。複雑な設定は不要だ。認識されるとsystem-reminderにスキル名が表示され、スラッシュコマンドで明示的に呼び出せるようになる。ディレクトリ名がそのままコマンド名になるため、命名には注意が必要だ。

3. CLAUDE.mdとSKILL.mdの役割分担

CLAUDE.mdはプロジェクト全体に常時適用されるルールを記述する。一方、SKILL.mdは特定のタスク実行時にのみ読み込まれる専門命令書だ。この役割分担がプロンプトの肥大化を防ぐ。プロジェクト全体で守るべき規約はCLAUDE.mdへ、特定の目的がある作業手順はSKILL.mdに記述するのがベストプラクティスだ。

4. descriptionによる呼び出し精度の向上

単なる機能説明では不足だ。descriptionに「〜と言われたら必ず使う」というトリガーフレーズを含める。これにより、Claude Codeの呼び出し漏れを減らせる。AIの判断に依存せず、意図したタイミングで確実に発動させるための工夫だ。

5. 知識の階層化（A1/A2/A3）

守らせたい知識はタスクの抽象度で3つに分類する。機械検知可能な規約はLinterへ、構造的な判断はコンテキストへ、という切り分けが生産性を最大化する。知識の階層化を意識することで、AIの指示遵守率は向上する。

6. AI向けLinterとしてのAST活用

機械的にチェック可能なルールは、 .claude/ast-rules/ でYAML管理し、hooksから実行する。違反時にエラーメッセージをコンテキストに注入することで、AIに直接ルールを学習させる。これは人間向けのLinterでは拾えないAI特有の悪手を防ぐための武器だ。

7. DEVIATEマーカーによる逸脱の管理

ルールを意図的に破る必要がある場合、理由を添えて「// AI: DEVIATE(...)」とコメントを残す。これでAIの再警告を抑制しつつ、レビュー時に妥当性を精査できる。ルールを柔軟に運用しつつ、品質を担保するための仕組みだ。

8. エラーメッセージのプロンプト化

エラーメッセージには禁止事項だけでなく「なぜダメか」「代わりに何を使うか」を記載する。AIへの指摘は単なる警告ではなく、次の行動を導くプロンプトとして機能させるのがコツだ。

しんたろー：
Claude Codeでコードを書く際、SKILL.mdの管理は非常に有効だ。プロンプトを分厚くするのではなく、必要な時に必要な知識だけを読み込ませる設計は、1人SaaS開発の理想形と言える。

比較表：設定ファイルの使い分け

ファイル名	適用範囲	用途	おすすめ度
CLAUDE.md	プロジェクト全体	常時適用ルール	★★★★★
SKILL.md	特定タスクのみ	専門的な作業手順	★★★★★
ASTルール	ファイル編集時	機械的な構文チェック	★★★★☆

しんたろーのTips

エラーメッセージをプロンプトにする手法が有効だ。AIに「ダメだ」と伝えるだけでは、別の悪手を選ぶ可能性がある。必ず「代わりに何を使うか」をセットで記述する。これだけで手戻りが減る。

しんたろー：
Claude Codeの拡張性の高さは唯一無二だ。自分の開発スタイルに合わせてルールを育てていく感覚は、優秀な相棒を育成する過程に近い。

FAQ

Q1: SKILL.mdがうまく読み込まれません。原因は何ですか？

A1: 最も多い原因はdescriptionの記述不足だ。Claude Codeはdescriptionの内容を判断基準にしているため、「いつ呼び出すか」を具体的に書く必要がある。「〜と言われたら必ず使う」という指示を追記し、ディレクトリ名が正しいか、 .claude/skills/ 配下にあるかを確認する。

Q2: CLAUDE.mdとSKILL.md、どちらに書くべきか迷います。

A2: 判断基準は「常時適用か、タスク限定か」だ。プロジェクト全体で守るべきコーディング規約や禁止事項はCLAUDE.mdへ、特定の目的がある作業手順はSKILL.mdに記述するのがベストプラクティスだ。

Q3: SKILL.mdのdescriptionには何を書くべきですか？

A3: スキルの目的と、呼び出しのトリガーとなる言葉を列挙する。例えば「記事生成指示書を作成する」だけでなく、「記事を書いて」「指示書を作って」といった具体的なフレーズを入れ、「必ず使う」と明記することで、AIが迷わずスキルを選択できるようになる。

Q4: ASTルール（.claude/ast-rules/）は必須ですか？

A4: 必須ではない。まずはSKILL.mdで運用を効率化し、それでもAIが同じミスを繰り返すようになった段階で導入を検討する。機械的にチェックできるルールを分離することで、プロンプトの肥大化を防ぎ、AIの指示遵守率を安定させることができる。

Q5: スキル名にルールはありますか？

A5: ディレクトリ名がそのままスキル名になる。ハイフン区切りの半角英数字（例: zenn-article-generator）が推奨されており、この名前がそのままスラッシュコマンドのトリガーになる。シンプルで推測しやすい名前にする。