Claude CodeのAgent Skillsとは？使い方・設計・活用パターンを徹底解説

「Claude Codeに、いつも自分がやっている開発ルーチンを覚えさせたい」「プロジェクトごとのやり方を、エージェントにちゃんと守らせたい」──そんなニーズに応えるのが、Claude Codeで使える「Skills（Agent Skills）」です。

Skillsは、指示書となるSKILL.md、補助スクリプト、テンプレート、補足ドキュメントなどを1つのフォルダにまとめ、Claude Codeから再利用できるようにする仕組みです。オープンスタンダードとして公開されている「Agent Skills」標準に基づいており、ClaudeアプリやAPIに加えて、GitHub CopilotのCoding AgentやOpenAIのCodex CLIなど、Agent Skills標準に対応した他のエージェントともSKILL.mdフォーマットを共有できます。

本記事では、Claude CodeにおけるSkillsの位置づけや仕組み、プロジェクトへの組み込み方、SKILL.mdの設計、具体的なユースケース、テストやセキュリティ設計まで、エンジニア目線で整理して解説します。

Claude CodeにおけるAgent Skills

Agent Skillsは、Anthropicが公開しているオープンなスキル定義フォーマットです。

Claude Codeは、この標準に沿ったスキルフォルダをローカル環境（「~/.claude/skills/」やリポジトリ内の「.claude/skills/」）から検出し、開発タスクに応じて自動的に利用します。

Claude Codeまわりの構成要素（AGENTS.md・CLAUDE.md・SKILL.md・MCPなど）

Claude Codeまわりの主な構成要素をまとめると、次のようになります。

AGENTS.md

• Codex CLI や Copilot Coding Agent、Gemini CLI など、複数のエージェントから共通で参照できる「上位ガイドライン」用フォーマットです。
• Claude Code自体は現状「CLAUDE.md」を読む前提ですが、「AGENTS.md」を「CLAUDE.md」のシンボリックリンクにする、あるいは「CLAUDE.md」から「@AGENTS.md」のように参照することで、「1つのガイドラインを複数エージェントで共有する」という運用もできます。

CLAUDE.md

• Claude Code向けのプロジェクトガイドです。
• 「このリポジトリでは、こういう前提・コマンド・禁止事項で動いてほしい」というルールや、レビュー方針などを記述します。プロジェクトルートや「.claude/CLAUDE.md」、グローバル設定として「~/.claude/CLAUDE.md」を置くパターンがあります。

SKILL.md（Agent Skills）

• テスト実行・リリース準備・リファクタリングなど、まとまったタスクのワークフローを定義するレシピです。
• 入力・出力・手順・制約・例を構造化して書き、「~/.claude/skills//SKILL.md」や「.claude/skills//SKILL.md」として配置します。1つのディレクトリが1つのスキルに対応します。

開発者のプロンプト

• 「いまこの会話で何をしてほしいか」を伝える、その瞬間の要求です。
• Claude Codeは、「CLAUDE.md」や「SKILL.md」の内容を前提に、開発者のプロンプトを踏まえてどのスキルをどう使うかを自動的に判断します。

MCP（Model Context Protocol）

• データベースやチケット管理などの外部システムを「ツール」として公開するためのプロトコルです。
• Agent Skillsからは、MCP経由で公開されたツールやClaude Codeのツール群を組み合わせて利用し、より複雑なワークフローを自動化できます。

実際のフローとしては、次のように整理しておくとイメージしやすくなります。

1. Claude Codeが、グローバル／プロジェクトの「CLAUDE.md」を読み、プロジェクトの前提・ルールを把握する。
   「AGENTS.md」を使っている場合は、「CLAUDE.md」を「AGENTS.md」のシンボリックリンクにするなどの運用で、共通ガイドラインを共有します。
   
   

2. 開発者のプロンプトに応じて、「~/.claude/skills」や「.claude/skills」配下の SKILL.md から、適切なスキルが自動的に選ばれます。
   
   

3. 必要に応じて MCP 経由のツールやシェルスクリプトを呼び出しながら、SKILL.md に書かれた手順どおりにタスクを進めます。

という構造で押さえておけば十分です。

Claude CodeでSkillsを使う手順

Claude CodeでSkillsを活用するにあたっては、「Claude Codeが問題なく使えていること」を前提に、あとはプロジェクト側でスキルフォルダをどう用意するかを押さえておけば十分です。

ここでは、そのための最低限の前提と、リポジトリ内での準備方法を整理します。

プロジェクト内にスキルフォルダを置く

Claude Codeで使うSkillsは、基本的に「ユーザー共通」「プロジェクトローカル」「プラグインにバンドルされたスキル」の3つのソースから読み込まれます。

頻繁に使う汎用スキルは 「~/.claude/skills」 に、特定プロジェクト専用のスキルはリポジトリ内の 「.claude/skills」に配置し、各種プラグインが提供するスキルはプラグイン側にバンドルされる、という整理です。

プロジェクト内での典型的な構成は、次のようなイメージです。

repo-root/
  .claude/
    skills/
      webapp-testing/
        SKILL.md
        run_local_tests.sh
        fixtures/
          sample.json
      docs-refactor/
        SKILL.md
  CLAUDE.md
  src/
  tests/
  ...

このように、リポジトリの直下に .claude/skills フォルダを置き、その配下に「スキルごとのサブフォルダ」を作るイメージです。

ポイントは次の通りです。

• スキルは、リポジトリごとにローカル配置する（プロジェクト単位で完結させる）
• スキルフォルダには、必要最低限のファイルだけを入れる（巨大なアセットは避ける）
• CLAUDE.mdと合わせてコミットし、レビュー対象に含める

グローバルな「デフォルトインストールパス」を前提にするのではなく、
「このリポジトリの中に、このプロジェクト専用のスキルがある」という形にしておくと、安全かつ再現性が高くなります。

Claude Code×Skillsの基本ワークフロー

ここでは、Claude CodeでSkillsを使うときの典型的な流れを、ざっくりと整理します。

1. プロジェクトを準備する

まず、開発者側で次のような準備を行います。

• CLAUDE.mdをプロジェクトルートに追加し、プロジェクトの前提やコマンドを記述する
• プロジェクト内の 「.claude/skills」フォルダを作成し、スキルフォルダとSKILL.mdを用意する
• 必要に応じて、テストスクリプトやフィクスチャを配置する

CLAUDE.mdは、「プロジェクト専用のREADMEを、Claude向けに書き直したもの」と考えるとイメージしやすいです。

2. Claude Codeからリポジトリを開く

次に、Claude Codeを起動し、対象のリポジトリを開きます。

• VS Code拡張や専用クライアントから、作業したいリポジトリに接続する
• 最初のロード時に、ClaudeがCLAUDE.mdなどを読み込んでコンテキストを構築する
• 「.claude/skills` フォルダ内のスキルは、「タスクに関係がありそうなタイミング」で段階的に読み込まれる

この段階では、まだ特定のスキルが強制的に呼ばれているわけではなく、「候補として存在している」状態です。

3. 会話の中でスキルを呼び出す

開発者は、普段どおりClaude Codeに指示を出していきます。

• 「このリポジトリでユニットテストを走らせて、失敗したテストを要約して」
• 「いつものリリース手順に沿って、変更点のチェックリストを出して」
• 「このモジュールに新機能を追加するための実装方針と差分を提案して」

Claude Codeは、会話の内容とSKILL.mdの説明文を照らし合わせながら、
「このタスクにはどのスキルが有効か」を判断し、必要なフォルダやスクリプトを読み込んで実行します。

4. 実行結果をレビューし、改善していく

スキルが動くと、テスト結果やログの要約、生成されたコードの差分などが返ってきます。

• Claudeから提案された手順やコマンドを確認する
• 変更されたファイルの差分をレビューし、必要に応じて修正する
• スキルの指示やスクリプトが微妙な場合は、SKILL.mdやスクリプトの内容を調整し、再度試す

この「スキル側を少しずつチューニングしていく」サイクルを回すことで、
自分のチームにフィットしたSkillsセットが育っていきます。

Claude Code向けSkill設計のベストプラクティス

Claude Codeで使うSkillsは、「コードをさわるエージェント」に直接権限を渡すことになるため、設計が重要です。ここでは、SKILL.md・フォルダ構成・CLAUDE.mdとの役割分担という3つの観点で整理します。

SKILL.mdに書くべき項目

すべてのスキルには、SKILL.mdが必須です。
Agent Skillsの仕様では、この1ファイルに「メタ情報（フロントマター）」と「手順書（本文）」をまとめておく前提になっています。

例として、「このリポジトリのWebアプリに対して自動テストを実行し、失敗したテストを要約する」用途のスキル（Web App Testing）の SKILL.md 記述例は次のとおりです。

---
name: webapp-testing
description: Run focused tests against this web application and summarize failures for the developer.
---

# Web App Testing Skill

## Purpose
Run the project's automated tests in a safe, repeatable way and summarize any failing cases.

## Inputs
- Test code and configuration files in this repository
- The branch or test scope specified by the developer
- Any test commands, flags, or environment variables described in CLAUDE.md

## Outputs
- A summary of the test run
- A list of failing tests (file names, test names, error messages)
- Suggested next actions or potential fixes when appropriate

## Steps
1. Read `CLAUDE.md` to understand how to run the test suite.
2. Run the tests locally, keeping the scope narrow enough to finish in a reasonable time.
3. Collect failing tests and list them with file paths, test names, and relevant output.
4. Group failures by root cause and propose next steps to the developer.

## Safety and constraints
- Do not modify files outside the project root.
- Avoid running extremely long or full-regression suites unless explicitly requested.
- Confirm with the developer before running tests that depend on external services or networks.

## Examples
- "Run the unit tests for this repository and summarize only the failing tests."
- "Use the Web App Testing skill to investigate why the CI test job is failing."

押さえておきたいポイントは次のとおりです。

• フロントマターのnameとdescriptionは短く、具体的に書く
  → 「どんなタスクのときに使うべきか」が分かるようにする
• 本文では、目的・入力・出力・手順・制約・例を見出しで分ける
  → 人間が読んでも「業務手順書」として成立するレベルで整理する
• 長い説明文よりも、箇条書きベースで段階的に書く
  → Claude側がステップを抽出しやすくなる

フォルダ構成とスクリプト・フィクスチャ設計

SKILL.mdだけでもシンプルなスキルは作れますが、実務ではスクリプトやフィクスチャを組み合わせることで、より再現性の高いワークフローになります。

フォルダ構成の例をもう少し細かく見ると、次のようなパターンが考えられます。

repo-root/
├── .claude/
│   └── skills/
│       ├── webapp-testing/
│       │   ├── SKILL.md              (required: スキルの定義)
│       │   ├── run_local_tests.sh    (optional: テスト実行用スクリプト)
│       │   └── fixtures/
│       │       └── sample-user.json  (optional: 安全なサンプルデータ)
│       └── docs-refactor/
│           ├── SKILL.md              (required: スキルの定義)
│           └── patterns.md           (optional: リファクタリング方針メモ)
├── CLAUDE.md                         (optional: プロジェクト全体の前提・コマンド)
├── src/                              (アプリ本体)
└── tests/                            (テストコード)

構成を考えるときのポイントは、次の通りです。

• スキルフォルダは「1タスク＝1フォルダ」が基本
  → テスト、リファクタリング、ドキュメント整形などで分ける
  
  

• スクリプトは、小さく・決定的な挙動にする
  → 実行するたびに結果がブレないようにする
  
  

• 巨大なデータやバイナリは入れない
  → スキルの読み込みが重くならないようにする
  
  

• 入出力フォーマット（テキスト・JSON・JUnitレポートなど）は、SKILL.md側に明記する

Anthropicやコミュニティのベストプラクティスでは、「スキルフォルダは小さく保ち、SKILL.mdと最小限のスクリプト・フィクスチャだけを入れる」ことが強調されています。

大きなデータセットや長大なログは、別の場所で管理し、必要に応じて切り出した断片だけをフィクスチャとして置いておく方が安全です。

CLAUDE.mdとの役割分担

Claude Codeでは、CLAUDE.mdが非常に重要な役割を持ちます。
Anthropicのエンジニアリングガイドでは、「プロジェクトのスコープ・コマンド・テスト方針・注意点などをまとめた、Claude向けのプロジェクトガイド」として整理されています。

典型的なCLAUDE.mdには、次のような内容を含めます。

• Scope（どこまで操作してよいか）
• Common Commands（アプリ起動・テスト実行・ビルドなどの標準コマンド）
• Code Style（コーディング規約、PRポリシーなど）
• Testing Expectations（テスト戦略、期待する実行時間など）
• Review Rules（レビュー時の観点、ブランチ戦略など）

一方、Skills側のSKILL.mdは、「特定のタスクをどう進めるか」にフォーカスします。

• CLAUDE.md
  → 「このリポジトリ全体で、どういう前提・ルールで動いてほしいか」
  
  

• SKILL.md
  → 「その中で、テスト実行・リファクタリング・リリース準備などをどう進めるか」

この役割分担を意識しておくと、CLAUDE.mdとSKILL.mdが重複したり、どちらか一方が肥大化したりするのを防ぎやすくなります。

Claude Codeならではのユースケース

ここからは、Claude Codeだからこそ相性が良いSkillsのユースケースをいくつか紹介します。
「自分の現場だと何からスキル化すべきか」をイメージするためのヒントとして読んでみてください。

1. テスト実行・エラー調査スキル

もっとも分かりやすいのが、「テスト実行や失敗時の調査」をスキルとして切り出すパターンです。

このスキルでは、例えば次のようなことを担当させます。

• プロジェクト標準のテストコマンドでテストを実行する
• 失敗したテストだけを抽出し、テスト名・ファイル名・メッセージを一覧化する
• よくある失敗パターン（タイムアウト・依存関係エラーなど）をグルーピングして要約する
• 必要に応じて、関連するソースコードや設定ファイルを参照し、次の一手を提案する

CIで落ちたテストの再現や、ローカルでのデバッグ開始までの「最初の数十分」を、大きく圧縮できるパターンです。

2. モノレポ探索・リファクタリング支援スキル

モノレポや大規模なコードベースでは、「どこから読めばいいのか」「どこを直せば影響が最小か」といった把握に時間がかかりがちです。

ここでは、次のようなスキルを用意しておくと便利です。

• レイヤー構造や依存関係をまとめたガイドを参照しながら、影響範囲を示すスキル
• 既存のリファクタリング方針やアンチパターン集をもとに、改善案を提案するスキル
• 変更予定モジュールに関するテストやドキュメントを洗い出し、事前にチェックリスト化するスキル

これらのスキルを組み合わせることで、

• 「この機能を改修するときは、まずここを見て、こういうテストを走らせる」
• 「この依存関係は触らない方がよい」

といった「暗黙知」をClaude Codeに共有しやすくなります。

3. リリース・運用タスクの半自動化スキル

もうひとつ典型的なのが、「リリース前後の定型作業」をスキル化するパターンです。

例えば、次のようなタスクをまとめておきます。

• リリースノートの草案作成（コミットやPRログをもとに要約）
• 変更点のリスク整理（Breaking changeがありそうな箇所の洗い出し）
• 必須チェックリスト（テスト完了・ドキュメント更新・設定の反映など）の確認
• 運用ドキュメントやRunbookの更新支援

リリース作業は「だいたい同じことを毎回やっている」一方で、人的ミスが起きやすい領域です。
Skillsとして切り出しておくことで、メンバーが変わっても最低限の品質ラインを維持しやすくなります。

他のAgent Skills実装との違い・使い分け

Claude CodeのSkillsは、GitHub CopilotやOpenAI CodexのAgent Skills実装と共通のSKILL.mdフォーマットを採用しています。一方で、実際の「紐づくエージェント」や得意領域には違いがあります。

• GitHub Copilot Coding Agent：GitHub Actionsやリポジトリ運用と一体で使いたいときに向く
• OpenAI Codex CLI：複数の言語・クラウド環境をまたいだスクリプト実行に寄せたいときに向く
• Claude Code：ターミナル／VS Code連携＋CLAUDE.md＋Skillsで、1リポジトリ内の開発体験を作り込むのに向く

詳しい比較や使い分けは、関連ドキュメント（GitHub Copilot / Codex解説記事など）で整理しておくと、読者が自分の環境に合った選択をしやすくなります。

Claude Code×Skillsの運用とガバナンス

コードを扱うエージェントに権限を渡す以上、運用とガバナンスの設計は欠かせません。ここでは、個人・チーム・組織それぞれのレイヤーで意識しておきたいポイントを簡単にまとめます。

個人環境で試すときのポイント

個人でSkillsを試す段階では、次のようなガイドラインを置いておくと安全です。

• 最初は小さなリポジトリやサンプルプロジェクトで試す
• 破壊的な操作（削除・リネームなど）が必要なスキルは、最初から作らない
• 変更内容は必ず差分を確認し、手動でコミットする
• 不安なスクリプトは、まず自分で単体実行して挙動を確認する

このフェーズでは、「とりあえず便利かどうか」「どのくらい手間が減るか」を感覚的につかむのが目的です。

チーム導入時のルールづくり

チームで本格的に使い始めるときは、次のようなルール化があると運用しやすくなります。

• 「.claude/skills」 や 「~/.claude/skills」 配下の変更も、通常のコードレビュー対象に含める
• SKILL.mdやスクリプトには、作成者・オーナーを明記する
• CLAUDE.md・スキルの変更は、必ずPull Request経由で行う
• 定期的にスキル一覧を棚卸しし、重複・陳腐化したものを整理する

Anthropicのエンジニアリングガイドやコミュニティの事例でも、CLAUDE.mdやSkills関連ファイルを通常のリポジトリ運用の一部として扱い、バージョン管理とレビューを徹底することが推奨されています。

「AI向けの特別なファイル」ではなく、「チーム全員が読む前提のドキュメント＆スクリプト」として扱うと、品質を維持しやすくなります。

セキュリティと権限設計

最後に、セキュリティ面で意識しておきたい点をまとめます。

• 外部から持ち込んだスキルやスクリプトは、必ず内容をレビューしてから使う
• スキルが触れるファイルパスやディレクトリを明示し、それ以外には触れないように書く
• 機密情報（シークレット、認証情報）は、SKILL.mdやスクリプト内に直接書かない
• 本番環境用スキルと検証用スキルは、リポジトリやブランチを分けるなどして明確に区別する
• SKILL.md のフロントマターで 「allowed-tools」 を指定し、「このスキル実行中に利用してよいツール」をホワイトリスト方式で制限することで、誤ったツール呼び出しや過剰な権限行使を防ぐ

特に、コード実行環境に関する料金・制限・セキュリティポリシーは、Anthropic側のガイドラインも踏まえつつ、組織の規程に合わせて設計しておくことが重要です。

よくあるハマりどころ・アンチパターン

Claude Code×Skillsを試し始めた時に、特に起きやすい失敗パターンをいくつか挙げておきます。

• 1つのSKILL.mdに「あれもこれも」詰め込みすぎる
  → テスト／リリース／リファクタリングなどは、原則「1タスク＝1スキル」に分ける。
  
  
• グローバルなSkillsにプロジェクト固有の前提を書いてしまう
  → プロジェクト固有の前提は 「.claude/skills」側に寄せ、汎用化できる部分だけ 「~/.claude/skills」 に切り出す。
  
  
• CLAUDE.mdとSKILL.mdの役割がごちゃごちゃになる
  → CLAUDE.mdには「リポジトリ全体の前提・ルール」、SKILL.mdには「そのタスクの手順・制約」だけを書く。
  
  
• スキルの変更がレビューされない
  → 通常のコードと同様、Skills配下の変更もPull Request経由でレビューするルールを明文化しておく。

こうしたアンチパターンを最初に共有しておくだけでも、「スキルがカオスになって維持できない」という事態をかなり防ぎやすくなります。

まとめ

Claude CodeのSkills（Agent Skills）は、「賢いチャットボット」だったClaudeを、**「プロジェクトの文脈とルールを理解した、再現性の高い開発メンバー」**に近づけるための仕組みです。

• SKILL.md・スクリプト・テンプレートをまとめたスキルフォルダで、開発タスクをパッケージ化できる
• CLAUDE.mdと組み合わせることで、「このリポジトリでの前提・コマンド・禁止事項」を明示できる
• テスト実行、モノレポ探索、リリース準備など、開発現場の「いつもの作業」を再現性高く任せやすくなる
• 個人→部門PoC→全社カタログ運用と段階的に広げることで、リスクを抑えつつ成果を積み上げられる

まずは、自分のプロジェクトで1つだけ、小さなSkillsを作ってみるところから始めてみてください。
「この作業、もう人間が毎回最初からやらなくてよくない？」と思った瞬間が、スキルとして切り出すベストタイミングです。