開発者向け Claude Skills と SKILL.md：VS Code、JetBrains、Cursor

多くのチームは、Claude Skills を 2 つの方法のいずれかで誤用しています。SKILL.md を何でもありの dumping ground（ごみ箱）にするか、巨大なコピペプロンプトから卒業できないかのどちらかです。

どちらの手法も雑です。Skills を実際の開発ワークフローで機能させたいなら、それをプロンプトの詩作ではなく、コードや運用ロジックとして扱う必要があります。

Claude Skills は SKILL.md をアンカーとするディレクトリで、スクリプト、参照、アセットなどがオプションとして含まれます。これが機能するのは、プログレッシブ・ディスクロージャー（段階的な開示）によるものです。エージェントは、スキル名や説明などのコンパクトなメタデータのみを読み込み、タスクが一致したときにのみ完全な指示を読み取るように設計されています。これにより、エージェントはすべてのセッションの開始時に膨大な情報を抱えることなく、多くのスキルを準備しておくことが可能になります。

Anthropic 自身のガイダンスは、この役割分担を非常に明確にしています。CLAUDE.md は、永続的で常時有効なプロジェクトのコンテキスト用です。一方、Skills は、再利用可能な知識、プレイブック、オンデマンドでロードすべき呼び出し可能なワークフロー用です。Claude Code は、古いカスタムコマンドを同じメカニズムに取り込んでおり、レガシーの .claude/commands/*.md ファイルも引き続き機能しますが、Skills が長期的にはより優れた形態であり、あらゆる AI 駆動の開発ワークフロー において最も再利用可能な構築要素となっています。

Claude Skills の適用タイミング：CLAUDE.md と Skills と Hooks の違い

同じチェックリスト、同じデプロイプレイブック、同じコードレビュー基準、あるいは同じ内部 API の注意点などをチャットに貼り続けている場合、Claude Skills を作成する価値があります。Anthropic は、同じ手順を繰り返し再利用する場合、または CLAUDE.md のセクションが事実ではなくプロセスに成長した場合に、スキルを作成することを明確に推奨しています。これは FAQ の「Claude Skill とは何か、いつ使うべきか」という質問に対する実用的な答えです。スキルは、一般的な好みや広範なリポジトリルールではなく、反復可能な手順のために使用します。

真のメリットは、コンテキストコストと動作に対する制御にあります。良質なスキルは、関連するときにのみロードされますが、膨らんだ CLAUDE.md はすべてのセッションでロードされます。Anthropic が CLAUDE.md を短く保ち、ドメイン知識や手順をスキルに移すことを推奨するのは、オンデマンドでのロードがエージェントを現在のタスクに集中させるからです。

私の意見に基づくルールは単純です。指示がすべてのセッションで適用されるべきであれば、CLAUDE.md に記述します。指示が再利用可能な方法、チェックリスト、または時折必要なワークフローであれば、スキルに記述します。アクションが一致するイベントで自動的に実行される必要がある場合、それはスキルではなくフックに属する可能性が高いです。Anthropic の機能概要は、これらのツールをほぼ正確にそのレイヤーモデルで整理しています。

それぞれの判断基準は実用的です。すべてのチャットに同じ指示を貼り付け自身を感じたなら、それはスキルです。CLAUDE.md のセクションがステップバイステップのプロセスに成長したなら、それをスキルとして抽出します。ファイル保存時に静かに発火させたいなら、代わりにフックを作成します。

Claude Skills の IDE 対応：VS Code、JetBrains、Cursor、Codex

Claude Code は、CLI、デスクトップ、VS Code、JetBrains、Web、およびモバイル関連のリモート制御フローなどで動作します。Anthropic は CLI を最も完全なローカルインターフェースとして説明しており、IDE 統合は CLI 固有の機能の一部を犠牲にして、エディターネイティブなレビュー、ファイルコンテキスト、より緊密なワークフロー人体工学を提供します。設定、プロジェクトメモリ、MCP サーバーはローカル表面全体で共有されるため、.claude の設定はエディターに閉じ込められることなく、あなたについてきます。

VS Code については、Anthropic は拡張機能をエディター内での推奨インターフェースとしています。これは、プランレビュー、インライン差分、ファイルメンションサポート、CLI への統合アクセスを提供します。同じインストールフローは、Cursor への直接的なパスも公開しています。JetBrains については、現在サポートされているリストには IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLand が含まれており、プラグインには差分表示、選択共有、ファイル参照ショートカット、診断共有が組み込まれています。

JetBrains への対応は、多くの開発者が認識しているよりも良好です。IDE の統合ターミナルから claude を実行する場合、統合機能は自動的にアクティブになります。外部ターミナルから開始する場合は、Anthropic は /ide コマンドを使用して Claude Code を JetBrains セッションに再接続するよう文書化しており、Claude が IDE で見ているのと同じファイルを見るために、同じプロジェクトルートから起動することを明確に推奨しています。JetBrains で自動編集モードを使用する場合、Anthropic は IDE 設定ファイルが編集可能な表面の一部になる可能性があるため警告しており、その環境では手動承認がより安全なデフォルトであると述べています。

ここで重要な点です。Claude Skills は単なる Claude Code のものではありません。Agent Skills はオープンな標準です。公式の Agent Skills クイックスタートでは、同じスキルが GitHub Copilot、Claude Code、OpenAI Codex を使用した VS Code でも動作するとされており、OpenAI 自身の Codex ドキュメントでも、スキルが Codex CLI、IDE 拡張機能、アプリで利用可能であると述べています。Agent Skills 実装ガイドでは、重要な移植性の詳細が追加されています：.agents/skills がクライアント間の規約として浮上しており、一部のクライアントは実用的な互換性のために .claude/skills もスキャンします。

したがって、私が推奨する実用的な互換性のルールは以下の通りです。Claude Code のみを最初に構築している場合は、.claude/skills で記述します。真にクロスクライアントの移植性を求める場合は、オープンな Agent Skills の形状をターゲットにし、.agents/skills を標準パスとして使用します。これら 2 つの目標が同じであることを装うべきではありません。これらは関連していますが、同一ではありません。

簡単な互換性参照：

SKILL.md ファイル構造、フォルダレイアウト、保存場所

適切なスキルは、リポジトリのルートに置かれたランダムな Markdown ファイルではなく、フォルダです。コア仕様に従うと、SKILL.md ファイルを含むディレクトリが必要で、オプションとして scripts/、references/、assets/ ディレクトリが許可されています。SKILL.md には、YAML フロントマターに続き、Markdown 指示が含まれている必要があります。仕様では、name と description は必須で、name は小文字の文字、数字、ハイフンを使用し 64 文字に制限され、compatibility は実際の環境要件のみに使用され、allowed-tools は実装間で明示的に実験的であるとされています。

Claude Code は移植可能な仕様よりも少し緩やかで、ディレクトリ名から名前を導き出し、description が欠落している場合は最初の段落にフォールバックできます。ただし、移植性や予測可能性を重視する場合は、これに依存すべきではありません。Claude.ai はディレクトリ名が name フィールドと一致する必要があることを要求し、カスタムスキルアップロードパスでは、より広範な仕様がはるかに多くを許可しているにもかかわらず、説明を 200 文字に制限します。移植可能な選択は、明示的な name を設定し、ディレクトリを同一に保ち、厳しい制限内で正確な説明を書くことです。これは「SKILL.md ファイルに何を記述すべきか」という FAQ トピックに対する答えで、うやむやにすることはありません。

このように退屈な構造から始めます：

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

スキル対応クライアント間の移植性が Claude Code の利便性よりも重要であれば、内部形状を同じままに保ち、.claude/skills/ を .agents/skills/ に置き換えます。どちらの場合でもフォルダ構造の考え方は同じです。

Claude Code における保存場所は単純です。プロジェクトスキルは .claude/skills/<skill-name>/SKILL.md に、個人スキルは ~/.claude/skills/<skill-name>/SKILL.md に、プラグイン配布スキルは <plugin>/skills/<skill-name>/SKILL.md 下に存在します。Anthropic は、ビルトインスコープ間の優先順位をエンタープライズ > 個人 > プロジェクトと文書化しており、プラグインスキルは plugin-name:skill-name のような名前空間形式を使用して衝突を回避します。Windows では、~/.claude は %USERPROFILE%\.claude に解決され、CLAUDE_CONFIG_DIR でベースディレクトリ全体を再配置できます。

プロジェクトスコープと個人スコープの選択も単純です。スキルがそのコードベースと緊密に結合されている場合は、リポジトリ内の .claude/skills/ を使用します。例えば、特定のクラスタ名を知っているデプロイプレイブックや、チームの慣習に合わせて調整されたレビュー基準などです。~/.claude/skills/ は、プロジェクト間を移動するスキルに使用します。個人的なチェックリスト、一般的なチェンジログジェネレーター、好みのデバッグワークフローなどです。ドットファイルリポジトリに入れるようなものはすべて、個人スコープに属します。

いくつかの重要な点は記憶に留める価値があります。SKILL.md は、その大文字・小文字を正確に含めて命名する必要があります。Anthropic の PDF ガイドは、ケバブケースのフォルダ名を推奨し、スキルフォルダ内に README.md を配置しないよう明確に述べています。これは、運用ドキュメントは SKILL.md または references/ に存在すべきだからです。同じガイドは、SKILL.md の命名が大文字小文字を区別することを強調しています。これらは退屈な制約ですが、退屈な制約こそがツールを信頼可能にします。

Claude Code はモノリポジトリでも適切に対応します。サブディレクトリ内で作業する際に、ネストされた .claude/skills/ ディレクトリを自動的に検出し、パッケージレベルやサービスレベルのスキルに理想的です。また、現在のセッション中に既存のスキルディレクトリの変更を監視します。唯一の再起動トラップは、セッション開始時に存在しなかったトップレベルのスキルディレクトリを作成することです。Anthropic は、新しいディレクトリが監視されるようにするために再起動が必要となるケースとしてこれを文書化しています。

Claude Skills ベストプラクティス：説明、スクリプト、スコープ

最も無駄なスキルを作成する最速の方法は、LLM に一般的なトレーニング知識からそれを作り出させることです。Anthropic のベストプラクティスガイドは、まさにそれを警告しています。価値ある部分は、モデルが独自に信頼して発明できないドメイン固有の修正、エッジケース、ツールの選択、慣習です。正しいワークフローは、エージェントでタスクを一度解決し、動作するまで修正し、その後その方法をスキルとして抽出することです。

スキルをウィキのようにではなく、良い関数のようにスコープします。Anthropic は、スキルが連関した作業の単位をカプセル化すべきだと述べています。狭すぎると、1 つのタスクのために複数のスキルを積み重ねることを強いることになります。広すぎると、エージェントはそれらを正確に活性化できません。ベストプラクティスガイドは、過度に包括的なスキルは、モデルが関連性の低い指示を追いかけてシグナルを見失うため、むしろ害を及ぼす可能性があると率直に述べています。

説明の質は装飾的な問題ではありません。それはルーティングレイヤーです。Anthropic と Agent Skills ドキュメントの両方が、description フィールドはモデルがスキルをロードするかどうかを決定する主要なメカニズムであると述べています。良い説明は、スキルが何をするか、いつ使用するべきか、ユーザーが実際に言及するトリガーフレーズやファイルタイプを伝えます。悪い説明は、曖昧で、技術的すぎるか、無意味に一致するほど広範です。これは FAQ の「なぜ Claude Skill がトリガーされないのか」という質問に対する真の答えです。多くの場合、問題なのはモデルではなく、ルーターです。

対比は並べると明確です：

悪い説明 — 信頼してルーティングするには曖昧すぎる:

• Helps with code review — すべてに一致し、何ら曖昧性を除かない
• Useful for development tasks — 検索クエリよりも広範
• Assists with writing — ルーターではなく、単なるカテゴリラベル

良い説明 — 特定のトリガー言語:

• Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
• Generate a changelog from git log output. Use when preparing a release, writing release notes, or summarising commits since last tag.
• Scaffold a new Go HTTP handler with request validation and error middleware. Use when adding a new endpoint or route to a Go service.

パターンは毎回同じです：スキルが何をするかを述べ、それを活性化すべき正確なユーザーフレーズを命名し、オプションとして関連するファイルタイプやツールを命名します。説明が一般的な Google クエリに一致する場合は、十分に特定されていません。

ワークフローに副作用がある場合は、手動操作にします。Claude Code はそれを直接公開しています。disable-model-invocation: true はスキルをユーザー呼び出し専用にし、Anthropic はデプロイ、コミット、外部メッセージなどのアクションに対してこれを推奨しています。user-invocable: false は逆方向に進み、スラッシュメニューからスキルを隠しますが、背景知識として Claude が使用することを可能にします。これは「スキルを自動ではなく手動にするべきなのはいつか」という FAQ トピックに対する 1 文の答えです：リスクには手動、安全な反復可能なガイダンスには自動です。

SKILL.md は、理解可能に保つために十分に小さくします。Anthropic は、それを 500 行未満、約 5,000 トークンに保ち、詳細な資料を references/ または明示的なロード指示を持つ類似のファイルに移すことを推奨しています。「API が 200 以外のレスポンスを返したら references/api-errors.md を読む」は良いパターンです。「references/ を参照」は怠慢です。Claude Code は、レンダリングされたスキルをメッセージとして会話に注入し、後のターンでファイルを再読み取りしません。コンテキスト圧縮後、トークン予算内では最近のスキル内容のみが引き継がれます。したがって、巨大なスキルは単に醜いだけでなく、長期的なセッションではもろくなります。

良い SKILL.md は非常にシンプルに保つことができます：

---
name: review-pr
description: Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
compatibility: Designed for Claude Code. Requires git and gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Review PR

Read references/checklist.md before running any commands.

1. Collect the diff and changed files.
2. Flag correctness, security, and test coverage issues.
3. Return findings grouped by severity with file references.
4. Suggest the smallest safe fix first.

決定性が雄弁さよりも重要な場合はスクリプトを使用します。スキルスクリプトガイドはここで優れています。エージェント向けスクリプトは、対話プロンプトを避け、--help を通じて使用法を文書化し、役立つエラーメッセージを発信し、stdout への構造化出力（JSON や CSV など）を優先し、診断を stderr に送信し、リトライ安全な使用をサポートすると述べています。また、ワンオフのツールバージョンを固定し、環境が適切なパッケージを持っていると仮定するのではなく、SKILL.md または compatibility フィールドで明示的にランタイム要件を記述することを推奨しています。

最小限だが正しいエージェント向けスクリプトは以下のようになります：

#!/usr/bin/env bash
# scripts/collect-diff.sh — called by review-pr skill
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Structured output to stdout so the agent can parse it
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

3 つの要素がこれをエージェント安全にします。set -euo pipefail は、スクリプトが静かに進むのではなく、あらゆる失敗で明示的に終了するようにします。stdout への JSON は、エージェントが推測せずにパースできるフォーマットを提供します。診断は stderr に行き、エージェントの stdout ストリームがクリーンに保たれます。これらはすべて賢いものではなく、すべて必要です。

1 つの微妙なトラップは allowed-tools です。仕様では実験的で、サポートは異なります。Claude Code では、スキルがアクティブな間に特定のツールを事前承認しますが、呼び出し可能なツールの宇宙を制限するわけではなく、拒否ルールは依然として Claude Code の権限に属します。Claude Agent SDK では、Anthropic は SKILL.md の allowed-tools フロントマターが適用されないことを明確に述べており、SDK アプリはツールアクセスをメインの allowed_tools または allowedTools 設定で強制する必要があります。その違いを無視すると、スキルは CLI と SDK 駆動の自動化で異なる動作を示します。

もう 1 つの高度なパターンは盗む価値があります。ワークフローがメインスレッドにログ、ファイル検索、長期的な研究成果を洪水のように流す場合、Claude Code は context: fork と Explore などの agent を使用して、スキルをフォークされたサブエージェントで実行することを可能にします。Anthropic は、これは重労働が隔離されたコンテキストで起こり、メイン会話は要約を受け取る研究ワークフローのためにこれを示しています。深いコードベースの探索については、メインセッションを汚染する巨大なインラインスキルよりもはるかに優れた設計です。

フォークされたスキルは、フロントマターで以下のように見えます：

---
name: explore-codebase
description: Deep exploration of an unfamiliar codebase. Use when onboarding to a new repo, auditing architecture, or mapping module dependencies.
context: fork
agent: Explore
compatibility: Requires Claude Code CLI.
---
# Explore Codebase

1. Walk the directory tree and summarise the top-level modules.
2. Identify the main entry points and their responsibilities.
3. Map the dependency graph between packages.
4. Return a structured summary to the main session — not the raw file list.

キーの行は context: fork です。これがないと、探索出力は会話内にインラインで配置されます。これがある場合、サブエージェントは独自のコンテキストウィンドウで実行し、要約を返します。この違いは、探索だけで数千のトークンを消費しうる大きなリポジトリでは重要です。

Claude Skills のテスト：トリガー、正確性、ベースライン比較

スキルは、1 つのハッピーパスデモが一度機能しただけではテストされません。Anthropic のガイドは、テストを 3 つのレイヤーに分割します：Claude.ai での手動テスト、Claude Code でのスクリプトテスト、Skills API 経由のプログラムテスト。推奨される評価領域は、トリガー、機能的正確性、そしてスキルなしのベースラインに対するパフォーマンスです。これも「スキルが信頼できるかどうかをどのようにテストするか」という FAQ 質問に対する最善の答えです。モデルが自信満々に聞こえたかどうかだけでなく、ルート選択、出力品質、効率性をテストします。

公式の評価ガイダンスは、テストケースのためのクリーンな構造を提供します。各ケースには、現実的なユーザープロンプト、期待される出力の人間が読める説明、オプションの入力ファイルが含まれるべきです。ドキュメントはそれらをスキルディレクトリ内の evals/evals.json に保存しており、これは独自のハーネスを構築する場合でも理にかなった規約です。

フィクスチャファイルと、以下の無骨な評価レイアウトを使用します：

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR for security issues and missing tests",
      "expected_output": "Findings grouped by severity with file references and at least one test recommendation.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Summarise last week's commits",
      "expected_output": "The skill should not activate.",
      "files": []
    }
  ]
}

私のテストルールは、多くのチームが使用するよりも厳格ですが、公式ガイダンスと一致します。すべての真面目なスキルには、トリガーすべきクエリ、トリガーすべきでないクエリ、少なくとも 1 つのエッジケーステスト、スキルなしのベースライン比較が必要です。Anthropic の例では、ツールの呼び出し、失敗した API 呼び出し、明確化ループ、そしてスキルあり/なしのトークン使用量を比較しており、「動作する」ことと「ワークフローを改善する」ことは同じではないからです。

Claude Agent SDK を通じてテストする場合は、配管を思い出してください。スキルはそこでプログラム登録ではなく、ファイルシステムアーティファクトです。Anthropic は、"Skill" ツールを有効にし、settingSources または setting_sources を通じて関連するファイルシステム設定をロードする必要があると述べています。user または project を省略するか、cwd を誤った場所に指す場合、SDK はスキルを発見しません。Anthropic は、直接発見チェックとして「利用可能なスキルは何ですか？」と尋ねることを推奨しています。

また、実際に出荷することを意図するモデルとクライアントでテストしてください。オープン Agent Skills クイックスタートは、ツール使用の信頼性がモデル間で異なることを明確に警告しており、一部のモデルはスキルが意図するコマンドを実行するのではなく、直接回答する可能性があります。これは必ずしもスキル設計の問題ではありません。時としてそれはモデル選択の問題であり、テストマトリクスはそれを明らかにすべきです。

Claude Skills のトラブルシューティング：一般的な失敗と修正

スキルが誤動作する場合は、知性よりもパッケージングを疑ってください。最も一般的な失敗は依然として退屈なものです。

• スキルが全く見つからない場合は、ファイル名が正確に SKILL.md であり、正しい大文字・小文字で、正しいディレクトリ内にあることを確認してください。Anthropic のトラブルシューティングガイドは、ファイル名の大文字・小文字を明示的に指摘しており、Claude Code と SDK のドキュメントは、最初のチェックとして .claude/skills/*/SKILL.md と ~/.claude/skills/*/SKILL.md を指しています。
• フロントマターが無効な場合は、まず YAML デリミタとクォートをチェックしてください。Anthropic の例は、欠落した ---、閉じられていないクォート、スペースや大文字を含む無効な名前などの古典的なミスを示しています。スキル名は小文字でハイフン付きであるべきです。
• スキルが存在するがトリガーしない場合、説明が通常曖昧すぎます。Claude Code 自身のトラブルシューティングでは、ユーザーが自然に言うキーワードを含めるよう、スキルが「利用可能なスキルは何ですか？」と尋ねたときに表示されることを確認し、説明に近い言い回しを試すよう述べています。Anthropic の PDF ガイドは、Claude にスキルを使用するタイミングを尋ね、その説明をどのように言い換え返すかを聞くという優れた診断トリックを追加しています。
• スキルが頻繁にトリガーする場合は、スコープを狭めます。Anthropic は、説明をより具体的にし、ネガティブトリガーを追加し、明示的なコマンドでのみ望むワークフローに disable-model-invocation: true を使用することを推奨しています。過剰なトリガーは、通常、指定不足のルーティング言語です。
• スキルが長期的なセッションで影響力を失うように見える場合、多くのスキルが存在するときに Claude Code カタログで説明が短縮され得ることを思い出してください。また、呼び出されたスキルは圧縮後にトークン予算内で引き継がれます。Anthropic は、説明の先頭にキーワードを配置し、余分なテキストを切り詰め、Claude Code の場合は説明リストが過度に圧縮されている場合 SLASH_COMMAND_TOOL_CHAR_BUDGET を調整することを推奨しています。
• バンドルされたスクリプトがハングしたり不規則な動作をする場合、対話入力が必要かどうかを確認してください。スクリプトガイドでは、エージェントは対話シェルで実行されるため、TTY プロンプト、パスワードダイアログ、確認メニューは設計上のバグであると述べています。フラグ、環境変数、または stdin を通じて入力を受け取り、失敗を明示的にします。
• SDK がスキルを見ない場合は、allowed_tools に "Skill" が含まれていること、settingSources または setting_sources に user と project が含まれていること、cwd が実際に .claude/skills/ を含むディレクトリを指していることを確認してください。その設定なしでは、Markdown がどれほど正しくてもスキルシステムは有効になりません。
• MCP 対応のスキルがロードするがツール呼び出しが失敗する場合は、Anthropic のトラブルシューティングチェックリストが理にかなっています：MCP サーバーが接続されていることを確認し、認証とスコープを確認し、スキルなしで MCP ツールを直接テストし、大文字小文字を区別するため正確なツール名を確認します。

退屈な真実は、良い Claude Skills は良い運用エンジニアリングのように見えるということです。明確な名前。小さなファイル。明示的なトリガー。必要な場合は決定論的なスクリプト。実際のテスト。スキルがすっきりとしたランブックのように読めるなら、エージェントは戦うチャンスがあります。ブレインストーミングのように読めるなら、単にフォルダ内に混沌を隠しているだけです。