Claude Code Skills 活用ガイド｜.claude/skills・SKILL.md・Agent Skills徹底解説

Claude Code Skillsは、Claudeに「特定タスクの手順・知識・スクリプト」をディレクトリ単位でパッケージ化し、必要なときだけ自動で呼び出せるようにする仕組みです。.claude/skills/<skill-name>/SKILL.md を置くだけで動作し、コンテキストを節約しながら大規模なノウハウを再利用できる点が、CLAUDE.mdや従来のスラッシュコマンドにはなかった強みです。

本記事では、公式ドキュメント（Extend Claude with skills）とAnthropicの発表記事をベースに、Skillsの基本構造・SKILL.mdの全フィールド・3サーフェス（Claude Code／Claude API／Claude.ai）の違い・チーム共有・セキュリティまで一気通貫で整理します。

この記事でわかること

• Claude Code Skills（Agent Skills）の正体と、できる／できないことの境界
• SKILL.md のYAMLフロントマター16フィールドと使い分け
• ~/.claude/skills/ と .claude/skills/、プラグイン・組織配布の優先順位
• Skills・CLAUDE.md・Slash Commands・Subagents・MCPの判断基準
• 実装でハマりやすいポイントとAnthropic公式が警告するセキュリティリスク

こんな方に向いています

• Claude Codeで毎回同じ指示を貼り付けるのに疲れた開発者
• チーム全員に同じ手順・規約を強制したいリードエンジニア
• 業務プレイブックをLLMに任せたいプロジェクトマネージャー
• Claude.aiやAPIで配布しているSkillsをClaude Codeにも展開したい人

Claude Code Skillsとは何か（結論）

Claude Code Skillsは、「いつ呼び出すか」を書いたメタデータと、「何をすべきか」を書いた指示書（SKILL.md）、そして任意のスクリプト・参照ファイルをディレクトリにまとめたパッケージです。Anthropicが2025年10月16日に公式発表した機能で、Claude Code・Claude API・Claude.aiの3サーフェスに対応しています。

公式が掲げる中心的な設計思想は Progressive Disclosure（段階的開示） です。Claudeは起動時にすべてのSkillの「name」と「description」だけを常時ロードし、SKILL.md本体は必要になった時点で初めて読み込みます。これにより、数十〜数百のSkillをコンテキストに「待機」させながら、実コストを最小に抑えられます。

Claude Code上での位置付けとしては、既存の .claude/commands/ の上位互換にあたります。従来のスラッシュコマンドはそのまま動作しますが、Skillsはサポートファイルの同梱・フロントマター制御・Claude自身による自動呼び出しに対応しており、公式ドキュメントには「カスタムコマンドはSkillsにマージされた」と明記されています。

.claude/skills/ と SKILL.md の関係

Claude Code Skillsの実体は、.claude/skills/<skill-name>/SKILL.md というディレクトリ＋Markdownファイルのセットです。Skill本体（SKILL.md）と、それが参照する任意のサポートファイルを同じディレクトリに置く構造になっています。

my-skill/
├── SKILL.md           # 必須：メイン指示（YAMLフロントマター＋本文）
├── template.md        # 任意：Claudeが埋めるテンプレート
├── examples/
│   └── sample.md      # 任意：期待形式の出力例
└── scripts/
    └── validate.sh    # 任意：Claudeが実行するスクリプト

ここで重要なのは、SKILL.mdを1階層深く置くと動かない点です。my-skill/another-folder/SKILL.md のような配置はClaude Codeが認識しません。トップレベルの <skill-name>/ 直下に必ずSKILL.mdを置く必要があります。

サポートファイルは「Level 3+」のリソースとして扱われ、SKILL.md内から参照（@template.md・!bash scripts/validate.sh など）された時点で初めてClaudeに読み込まれます。500行を超えるような大きなノウハウは、SKILL.md本体を薄く保ち、参照ファイルに分割するのが公式推奨パターンです。

SKILL.mdの基本構造とYAMLフロントマター

SKILL.mdは「YAMLフロントマター」＋「Markdown本文」のシンプルな構造です。最低限の例は以下の通りです。

---
name: my-skill
description: What this skill does
---

# My Skill

ここに手順や指示を書く。

Claude Codeでは name も description も任意項目で、省略時はディレクトリ名と本文先頭がフォールバックになります。一方、Claude APIでは両方とも必須かつ description は最大1024文字、予約語 anthropic / claude は使用不可、という制約がある点に注意してください。

フロントマター16フィールド一覧（Claude Code）

特に description は 「いつ・なぜ呼ばれるべきか」を明確に書くのが重要です。Anthropic engineering blogでも、descriptionが曖昧なSkillは自動呼び出しが効かず「死蔵される」と指摘されています。「PRレビュー時に呼ばれる」「Excel変換タスクで使う」のように具体的なトリガー条件を含めましょう。

呼び出し権限の制御マトリクス

disable-model-invocation と user-invocable の組み合わせで、Skillの呼び出し可否を細かく制御できます。

「重要な手順だが誤発動されると困る（例：本番デプロイ）」場合は disable-model-invocation: true、「Claudeに状況判断させたい背景知識」を渡したい場合は user-invocable: false がそれぞれ適しています。

Progressive Disclosureの3層構造

Skillsの設計の肝は、Claudeが情報を「3段階で必要なときだけ読む」点にあります。これにより、巨大な参照資料を保持しながらコンテキストを節約できます。

運用上の重要な挙動として、SKILL.mdは一度呼び出されるとセッション中の会話に1メッセージとして残り続け、後続ターンで再読み込みされません。タスク全体に効かせたいルールは「スタンディング指示」として書く必要があります。

また、自動コンパクション時には各Skillの最新呼び出しから先頭5,000トークン分が再アタッチされ、全Skillの合計予算は25,000トークンという上限があります。多数のSkillを使ったセッションでは、コンパクション後に古いSkillが落ちる可能性があるため、必要なら再度呼び出して復元する運用が必要です。

4つの保存場所と優先順位

Claude Code公式ドキュメントが定める保存階層は以下の4つです。

優先順位は enterprise > personal > project で、同名のSkillが複数階層にある場合は上位が勝ちます。プラグインSkillは plugin-name:skill-name のネームスペースを持つため、他と衝突しません。

Personal vs Project vs Plugin の使い分け

チーム展開を狙うなら .claude/skills/ をリポジトリにコミットするのが基本です。新しくジョインしたメンバーがリポジトリを git clone した瞬間にSkillsが利用できる状態になり、CLAUDE.mdと同じ配布モデルで揃えられます。

ライブ変更検出とネストディレクトリ検出

Claude Codeは既存のskillsディレクトリ下で追加・編集・削除したSkillを再起動なしで即反映します。ただし、セッション開始時に存在しなかったトップレベルのskillsディレクトリを新規作成した場合は、Claude Codeの再起動が必要です。

モノレポ対応として、packages/frontend/ 配下のファイルを操作していれば packages/frontend/.claude/skills/ も自動で読み込まれるネストディレクトリ検出もサポートされています。

Skills・CLAUDE.md・Slash Commands・Subagents・MCPの使い分け

Claude Codeには似たような機能が複数あり、混乱しやすいポイントです。「いつ・どう発動するか」と「コンテキストへの影響」で使い分けるのが分かりやすい整理です。

「全タスクに常時効かせたいか」がCLAUDE.mdとSkillsの分かれ目です。CLAUDE.mdは毎回コンテキストに入るため濃くなりがちですが、Skillsは必要時のみロードされるので、頻度の低い専門手順を大量に抱えるのに向きます。

.claude/commands/ のスラッシュコマンドはまだ動作しますが、サポートファイル同梱・フロントマターによる細かい制御・自動呼び出しが必要なら、Skillsへ移行するのが公式推奨です。

3つのサーフェス（Claude Code・Claude API・Claude.ai）の違い

Agent SkillsはClaude Code・Claude API・Claude.aiの3サーフェスで動きますが、それぞれ提供形態と制約が大きく異なります。

公式提供のプリビルトSkillsは、2026年4月時点で pptx（PowerPoint）／xlsx（Excel）／docx（Word）／pdf の4種類です。これらはClaude APIとClaude.aiで即利用できますが、Claude Codeでは利用できない点を誤解しないようにしましょう。

Claude API経由でSkillsを使うときの追加要件

Claude APIでSkillsを呼び出すには、Code Execution Toolと併用し、以下の3つのベータヘッダを送信する必要があります。

anthropic-beta: code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14

また、Code Execution Toolの実行時間とコンテナストレージは標準課金が発生します。Skills機能自体に追加課金はありません。

サーフェス間の同期

カスタムSkillsはサーフェス間で自動同期しません。Claude.aiにアップロードしたものをClaude APIやClaude Codeに反映させるには、別々に管理する必要があります。同じSkillを複数サーフェスで使いたい場合は、ファイルシステム上のソースをマスターにして、API・Claude.aiにそれぞれデプロイするスクリプトを組むのが一般的です。

最初のSkillを作る5ステップ

最小構成のSkillを作って、自動呼び出しの感触を掴みましょう。ここではコードレビュー支援用の pr-review Skillを例にします。

1. ディレクトリを作る

mkdir -p .claude/skills/pr-review

2. SKILL.mdを書く

---
name: pr-review
description: GitHub PRをレビューするときに自動で使う。差分・テスト追加・規約違反の3観点で評価する
when_to_use: ユーザーがPRレビュー、差分確認、コードレビューを依頼したとき
allowed-tools: Bash(gh pr diff *) Bash(gh pr view *)
---

# PR Review Skill

PRをレビューするときは以下の手順で評価する。

## Step 1: 差分の取得
!`gh pr diff`

## Step 2: 評価観点
1. **差分の意図**：コミットメッセージとPR本文と一致しているか
2. **テスト**：新しいロジックに対するテストが追加されているか
3. **規約違反**：CLAUDE.mdに記載のコーディング規約に反していないか

## Step 3: 出力形式
- 各観点ごとに「OK / 要修正 / 確認希望」をマークする
- 要修正がある場合は具体的な修正案を提示する

3. 動作確認

Claude Codeを起動し、/skills でSkill一覧に pr-review が出ることを確認します。次に「PR #42 をレビューして」のように依頼すると、descriptionに基づいてClaudeが自動で pr-review を呼び出します。明示的に呼び出したい場合は /pr-review をタイプします。

4. 動作検証

!`gh pr diff` の動的注入が走り、Claudeが差分を見た上で評価する流れになっているか確認します。期待通りでなければdescription・when_to_use・本文の手順を調整します。

5. チームに展開

問題なければ .claude/skills/pr-review/ をリポジトリにコミットします。これでチーム全員が git pull した瞬間からSkillが使えるようになります。

実践でよく使う4つの応用パターン

1. 動的コンテキスト注入（! バックティック構文）

SKILL.md本文に !`コマンド` と書くと、Claudeが本文を見る前にシェルコマンドを実行し、結果がプロンプトに差し込まれます。PR差分・git log・現在の環境情報など、毎回最新を取りたい情報を自動で同梱できます。

## 現在のブランチ状況
!`git status --short`

## 最近のコミット
!`git log --oneline -10`

2. サブエージェント分離実行（context: fork）

巨大な探索や複数ファイルの読み込みが必要なSkillは、メインコンテキストを汚さないようサブエージェントに分離するのが有効です。

---
name: dependency-audit
description: package.jsonの依存関係を全件監査する
context: fork
agent: Explore
---

メイン会話には結論だけが返り、途中の探索ログでメインコンテキストを潰さずに済みます。

3. ツール事前承認（allowed-tools）

定型的なBashコマンドを毎回承認するのは煩雑です。allowed-tools に指定しておけば、Skillアクティブ時のみ承認を省略できます。

allowed-tools: Bash(git add *) Bash(git commit *) Bash(git push *)

ただし広すぎる権限はセキュリティリスクになります。Bash(*) のような全許可ではなく、必要なサブコマンドだけを列挙しましょう。

4. ファイルパスベースの自動発動（paths）

特定のファイルglob配下を編集しているときだけ自動発動させたいSkillには paths が便利です。

---
name: react-component-style
description: Reactコンポーネントのスタイル規約を適用する
paths:
  - "src/components/**/*.tsx"
---

「TSXファイルを編集する場面だけスタイル規約Skillを呼ぶ」のように、コンテキストに応じた自動発動が可能になります。

ハマりやすいポイントとアンチパターン

公式ドキュメントとAnthropic engineering blogが繰り返し指摘している、初学者が陥りがちな失敗を整理します。

特に 「descriptionが弱くて発動しない」 は最頻出の失敗です。description: This skill is for code review のような無味乾燥な記述では、Claudeが「今このSkillを呼ぶべきか」を判断できません。「PRレビュー、差分確認、コードレビュー依頼を受けたとき」のようにトリガーフレーズを並べるのが効きます。

セキュリティ：Anthropic公式が繰り返し警告するリスク

Skillsは強力ですが、コード実行能力を持つ仕組みです。Anthropic公式ドキュメントは「ソフトウェアをインストールするのと同じ感覚で扱え」と繰り返し警告しています。

主なリスク

• データ窃取：悪意あるSkillが認証情報・ソースコード・環境変数を外部送信する
• 未承認のシステムアクセス：allowed-tools の広すぎる指定で、想定外のコマンドが承認なしで実行される
• ツール悪用：MCPサーバや他のツールを組み合わせた連鎖攻撃
• 外部フェッチの改ざん：外部URLから追加コンテンツを取得するSkillは、フェッチ先が後から書き換えられる可能性がある

安全に運用するためのポイント

1. 信頼できるソースのSkillだけを導入する。自作 or Anthropic公式（anthropics/skills）以外は原則使わない
2. 導入前に SKILL.md本文・スクリプト・参照ファイルをすべて監査する
3. allowed-tools は必要最小限の範囲に絞る（Bash(*) のような全許可は避ける）
4. Skillの ! シェル実行を全面禁止したい場合は、設定で "disableSkillShellExecution": true を有効化する
5. 機密性の高い環境では Enterprise配布のSkillsだけに限定し、ユーザー側のpersonal skillsを禁止するポリシーも検討する
6. Agent Skills機能はZero Data Retention（ZDR）対象外である点を理解し、機密データの扱いはAnthropicの標準保持ポリシーに従うことを前提に運用する

「便利だから動かす」ではなく、他社のスクリプトをサーバに入れるのと同じ警戒度で扱うのが正しい姿勢です。

チーム・組織での運用ベストプラクティス

Skillを「育てる運用」（Claude A／Claude B分業）

Anthropic公式のbest-practices文書で推奨されているのは、1つのClaudeでSkillを設計し、別のClaudeで利用させて改善する分業サイクルです。

1. Claude A（設計役）：ヒアリングやサンプル出力からSKILL.mdの草案を作る
2. Claude B（利用役）：作ったSkillを実タスクで使ってみる
3. 失敗・違和感をClaude AにフィードバックしてSKILL.mdを改善
4. これを繰り返してSkillを「育てる」

人間がゼロからSKILL.mdを書き上げるよりも、Claude自身に書かせて運用しながら磨くほうが、実態に合った発動条件・指示文に収束しやすくなります。

評価駆動開発（Evaluations-First）

公式が推奨するもう1つのパターンが、Skillの開発前に「合格基準（評価ケース）」を先に決めておくやり方です。

• 期待入力：「PR #42 をレビューして」
• 期待出力：「差分・テスト・規約の3観点で評価結果が返る」
• 失敗例：「規約違反を見落とす」「テスト不足を指摘しない」

評価ケースを先に書いておくと、SKILL.mdの調整が「実装の改善」ではなく「テストを通す改善」として進められ、品質が安定します。

バージョン管理とドキュメント

.claude/skills/ 配下はgit管理し、変更時はPRレビューを通すのが基本です。各Skillに README.md を添えて「いつ・誰が・なぜ作ったか」を残しておくと、半年後の自分やチームメンバーが意図を理解しやすくなります。

Claude Code Skillsの料金

Skills機能自体は、Claude Code・Claude API・Claude.aiのいずれでも追加課金なしで利用できます。ただし、各サーフェスの既存課金体系には従います。

なお、Claude本体の料金詳細はClaude Code 料金・Claude料金の記事も参考にしてください。

こんな方におすすめ／おすすめしない方

Claude Code Skillsをおすすめする方

• 同じ指示を繰り返し貼り付けている開発者（Skill化で大幅短縮）
• チーム全員に同じ手順・規約を強制したいリードエンジニア（.claude/skills/ をgit管理）
• PDF/Excel処理など決定論的なスクリプト実行を任せたい人（バンドルスクリプトで再現性確保）
• 業務プレイブックをLLMに任せたいプロジェクトマネージャー
• CLAUDE.mdが肥大化してコンテキストを圧迫しているプロジェクト

おすすめしない方

• 1回限りのタスクしかないケース（普通のプロンプトかCLAUDE.mdで十分）
• 頻繁に内容が変わる情報を扱いたい場合（time-sensitive情報はアンチパターン）
• 信頼できないSkillを導入する可能性がある環境でガードレールが整っていない組織
• Claude Codeの基本操作にまだ慣れていない段階の人（まずCLAUDE.mdで型を作ってからSkillsに移行）

「常に効くべきルール」はCLAUDE.md、「ときどき・特定条件で効くべき手順」はSkills、と棲み分けを明確にすると失敗が減ります。

よくある質問（FAQ）

Q1. SKILL.mdは何文字くらいまでに収めるべき？

A. SKILL.md本文（Level 2）は5,000トークン未満が公式推奨です。それ以上の情報は、サポートファイルとしてLevel 3+に分割し、SKILL.md本文には参照だけを書きます。

Q2. Skillが自動で呼ばれません。何が原因？

A. ほぼ全てのケースが description が曖昧 or 短すぎることに起因します。「いつ・なぜ・どのキーワードで呼ばれるべきか」を具体的に書き直すと改善します。それでも呼ばれない場合は when_to_use でトリガーフレーズを補強しましょう。

Q3. Claude.aiにアップロードしたSkillをClaude Codeでも使えますか？

A. 自動同期はされません。同じSkillを使いたい場合は、.claude/skills/<skill-name>/ にも同じ内容を配置するか、デプロイスクリプトで両方に反映する運用が必要です。

Q4. プリビルトSkillsはClaude Codeで使えますか？

A. 2026年4月時点でClaude Codeはプリビルトに非対応です。pptx・xlsx・docx・pdfのプリビルトSkillsはClaude APIとClaude.aiでのみ利用できます。

Q5. CLAUDE.mdとSkillsはどう使い分けるべき？

A. 「全タスクに常時効かせたいルール・事実」はCLAUDE.md、「特定条件で発動する手順・プレイブック」はSkillsが基本です。CLAUDE.mdが肥大化してきたら、頻度が低い節をSkillに切り出すとコンテキスト効率が上がります。

Q6. .claude/commands/ の旧スラッシュコマンドはまだ使えますか？

A. 公式ドキュメントに「カスタムコマンドはSkillsにマージされた」と明記されており、既存の .claude/commands/ も動作は継続します。ただし、サポートファイル同梱・自動呼び出し・細かい制御が必要ならSkillsへ移行するのが推奨です。

Q7. Agent SkillsはClaude以外のAIツールでも使えますか？

A. Agent Skills自体はオープンスタンダードとして公開されており、複数のAIツールが対応を進めているとの報告があります。ただし、各ツールの公式対応状況は変動するため、最新の情報は各ツールの公式ドキュメントで確認してください。

Q8. Skillsを使うと請求額は増えますか？

A. Skills機能自体に追加課金はありません。Claude APIで使う場合のみ、Code Execution Toolの実行時間・コンテナストレージの標準課金が発生します。Claude Code・Claude.aiでの追加コストはゼロです。

まとめと次に読むべき記事

Claude Code Skillsは、.claude/skills/<skill-name>/SKILL.md という単純な仕組みで、繰り返しのプロンプトをパッケージ化し、チーム全体に配布できる強力な仕組みです。CLAUDE.mdが「常時効くルール」だとすれば、Skillsは「必要なときだけ呼ばれる業務プレイブック」と位置付けると、運用設計が分かりやすくなります。

成功の鍵は次の3つです。

1. descriptionに「いつ・なぜ呼ばれるか」を具体的に書く（自動発動の精度を決める）
2. SKILL.md本文を5,000トークン未満に保ち、詳細はサポートファイルへ分割する
3. 信頼できるSkillだけを導入し、allowed-tools は最小限に絞る

導入の最初の一歩は、CLAUDE.mdから頻度の低い節を切り出してSkill化することです。1個でも動けばProgressive Disclosureの威力を実感できるはずです。

関連記事

• Claude Codeとは？特徴・料金・使い方を完全解説 — Claude Codeの全体像
• Claude Code 使い方ガイド — 基本操作からプロジェクト導入まで
• CLAUDE.md 書き方 ベストプラクティス — Skillsの兄弟機能であるCLAUDE.mdの設計
• Claude Code Hooks 使い方 — フックでClaude Codeの挙動を自動制御
• Claude Code サブエージェント 使い方 — context: fork のベースとなるSubagent機能
• Claude Code MCP連携 ガイド — Skillsと並ぶ拡張機構MCPの活用
• Claude Code スラッシュコマンド 作り方 — Skillsへ移行する前段の整理
• Claude Code セキュリティ 安全な使い方 — Skillsを含むClaude Code全体の安全運用
• Claude Code チーム導入 ガイド — .claude/skills/ をチームに展開する組織運用