こんにちは、サーバーワークスで生成AIの活用推進を担当している針生です。
Claude Code を使っていて、こんな経験はありませんか？
- 「API レスポンスはこの形式で返して」と毎回指示している
- コードレビューの時に「簡潔に要点だけ教えて」と毎回伝えている
- プロジェクト固有のコーディング規約を何度も説明している
これらの「毎回同じ指示」を解決するのが Agent Skills です。
本記事では、Agent Skills とは何か、どう使うのか、具体例を交えて紹介します。
Agent Skills とは
一言で言うと
「Claude への専門的なマニュアル」 です。
新しく入ったメンバーに「うちのプロジェクトではこうやって作業してね」というマニュアルを渡すように、Claude にも同じようなマニュアルを渡せる機能です。
従来の方法との違い
従来、Claude Code に作業ルールを伝えるには CLAUDE.md に書くか、毎回プロンプトで指示する必要がありました。
# 従来のやり方
あなた: ユーザー取得APIを作って。
レスポンスは { success, data, error } 形式で、
エラーコードも統一してね...
Agent Skills を使うと、この指示を一度書いておけば Claude が自動的に適用 してくれます。
# Skills を使ったやり方
あなた: ユーザー取得APIを作って
Claude: (api-response Skill を自動適用)
統一されたレスポンス形式でAPIを生成
Skills の仕組み
Skills は以下の3ステップで動作します。
1. Discovery（発見）
Claude Code 起動時に、Skill の名前と説明を読み込む
↓
2. Activation（有効化）
ユーザーのリクエストが Skill の説明に一致したら
「この Skill を使っていいですか？」と確認
↓
3. Execution（実行）
Skill の指示に従って作業を実行
重要なポイントは モデル起動型（model-invoked） であること。ユーザーが明示的に呼び出さなくても、Claude がリクエストの内容を判断して適切な Skill を自動で選んでくれます。
具体例で理解する Agent Skills
例1: API レスポンス形式 Skill
最もシンプルな例として、API レスポンスの形式を定義する Skill を作ってみましょう。
ファイル構成
~/.claude/skills/
└── api-response/
└── SKILL.md
SKILL.md の内容
name: api-response description: API のレスポンス形式を統一する。API作成、エンドポイント実装時に使用。 # API レスポンス形式ガイド ## 基本構造 すべての API レスポンスは以下の形式で返す： { "success": boolean, "data": object | null, "error": { "code": string, "message": string } | null } ## 成功時 { "success": true, "data": { ... }, "error": null } ## エラー時 { "success": false, "data": null, "error": { "code": "NOT_FOUND", "message": "User not found" } } ## エラーコード一覧 - VALIDATION_ERROR: 入力値不正 - NOT_FOUND: リソースが存在しない - UNAUTHORIZED: 認証エラー - FORBIDDEN: 権限エラー - INTERNAL_ERROR: サーバーエラー
使い方
あなた: ユーザー取得APIを作って
Claude: APIを作成しますね。
(api-response Skill を自動適用)
async function getUser(id: string) {
try {
const user = await db.users.findById(id);
if (!user) {
return {
success: false,
data: null,
error: { code: "NOT_FOUND", message: "User not found" }
};
}
return { success: true, data: user, error: null };
} catch (e) {
return {
success: false,
data: null,
error: { code: "INTERNAL_ERROR", message: e.message }
};
}
}
description に「API」というキーワードが含まれているため、Claude は自動的にこの Skill を適用します。
例2: コードレビュー Skill
コードを見てもらう時に、簡潔なフィードバックを返す Skill です。
ファイル構成
~/.claude/skills/
└── code-review/
└── SKILL.md
SKILL.md の内容
name: code-review description: コードをレビューする。「このコード見て」「レビューして」と言われた時に使用。 # コードレビュー ## レビュー方針 - 要点を3つ以内に絞る - 良い点と改善点をバランスよく伝える - 具体的な修正案を示す ## 出力フォーマット **良い点**: （1つ） **改善点**: （1-2つ、具体的な修正案付き）
使い方
あなた: このコード見てもらえる？
Claude: コードを確認しますね。
(code-review Skill を自動適用)
**良い点**: エラーハンドリングが適切に実装されています
**改善点**:
- L12: `any` 型を使っています → `User` 型を定義しましょう
- L25: ネストが深いです → early return で整理できます
例3: ツールを制限した安全な Skill
allowed-tools を使うと、Skill が有効な間に Claude が許可なく使えるツールを指定できます。指定されていないツールを使う場合は、通常通りユーザーに許可を求めます。
ファイル構成
~/.claude/skills/
└── code-explorer/
└── SKILL.md
SKILL.md の内容
name: code-explorer description: コードの調査や分析を行う。ファイルを変更せずに調べたい時に使用。 allowed-tools: Read, Grep, Glob # コード調査モード このモードでは読み取り専用でコードを調査します。 ## できること - ファイルの内容を読む（Read） - コード内を検索する（Grep） - ファイルを探す（Glob） ## できないこと - ファイルの編集・作成・削除 - コマンドの実行 安心してコードベースを探索できます。
使い方
あなた: このプロジェクトの認証周りを調べて
Claude: コードを調査しますね。
(code-explorer Skill を自動適用)
認証関連のファイルを確認しました：
- src/auth/login.ts: ログイン処理
- src/auth/session.ts: セッション管理
- src/middleware/auth.ts: 認証ミドルウェア
これにより、「コードを調べてほしいけど、勝手に変更されたくない」という場面で安全に使えます。
トークン使用量の削減
Agent Skills を使うと、コンテキストウィンドウの使用量を大幅に削減できます。
プログレッシブディスクロージャー
Skills は プログレッシブディスクロージャー という設計原則を採用しています。すべての情報を最初から読み込むのではなく、必要な時に必要な情報だけを読み込みます。
従来の方法（MCP など）: 全情報を常に読み込み → 7,000 トークン以上 Skills: 必要な時だけ読み込み → 90〜500 トークン程度
ある開発者の検証では、16,000 トークン消費していた MCP を、同等の機能を持つ Skill に置き換えることで、約 500 トークンまで削減できたという報告もあります。
なぜトークン量が減るのか
- 起動時: Skills の名前と説明文（数十トークン）だけを読み込む
- 作業時: マッチした Skill の指示だけを読み込む
- 詳細情報: 別ファイルに分離しておけば、必要な時だけ読み込む
トークン使用量が減ることで、より長いセッションでの作業が可能になります。
Skills の保存場所
Skills は保存場所によって適用範囲が変わります。
| 保存場所 | パス | 適用範囲 |
|---|---|---|
| Personal | ~/.claude/skills/ |
自分のすべてのプロジェクト |
| Project | .claude/skills/ |
そのリポジトリで作業する全員 |
| Plugin | プラグイン内 | プラグインをインストールした人 |
| Enterprise | 管理設定 | 組織全体 |
使い分けの例
- Personal Skills: 自分好みのコードスタイル、個人的なコーディング習慣
- Project Skills: チーム共通のレビュー基準、プロジェクト固有のアーキテクチャルール
- Enterprise Skills: 会社全体のセキュリティガイドライン、コンプライアンス要件
他の機能との違い
Claude Code には Skills 以外にも設定をカスタマイズする方法があります。それぞれの特徴を整理します。
| 機能 | 用途 | 呼び出し方 |
|---|---|---|
| Skills | 特定の作業時の専門知識 | 自動（Claude が判断） |
| Slash Commands | 再利用可能なプロンプト | 明示的（/command） |
| CLAUDE.md | プロジェクト全体の設定 | 常に読み込み |
| Hooks | ツール実行時のスクリプト | 自動（イベント発火時） |
| MCP | 外部ツール・データ連携 | Claude が必要に応じて |
Skill を作成するときのポイント
1. description が最重要
Claude は description を見て Skill を使うかどうか判断します。ユーザーが言いそうなキーワードを含めましょう。
# 悪い例 description: ドキュメント作成 # 良い例 description: README やドキュメントを作成・更新する。 「README書いて」「ドキュメント作って」「説明を追加して」と言われた時に使用。
2. 具体的な指示を書く
曖昧な指示ではなく、具体的なルールと例を書きます。
# 悪い例 統一されたレスポンスを返してください。 # 良い例 ## 構造 { success, data, error } 形式で返す ## 成功時の例 { "success": true, "data": { "id": 1 }, "error": null } ## エラー時の例 { "success": false, "data": null, "error": { "code": "NOT_FOUND", "message": "..." } }
3. 長くなりすぎたら分割
SKILL.md は 500 行以内が推奨です。詳細なリファレンスは別ファイルに分けて、必要な時だけ読み込ませます。
my-skill/ ├── SKILL.md # 概要と基本ルール（500行以内） ├── reference.md # 詳細なAPIリファレンス └── examples.md # 豊富な使用例
Agent Skills 対応ツール
Agent Skills はオープンスタンダードとして公開されており、Claude Code 以外のツールでも利用できます。
| ツール | 提供元 | 備考 |
|---|---|---|
| Claude Code | Anthropic | オリジナル実装 |
| Antigravity | エージェント優先 IDE | |
| VS Code | Microsoft | 拡張機能として対応 |
| GitHub Copilot | Microsoft | Agent Skills 仕様を採用 |
| Cursor | Cursor | 対応済み |
| Windsurf | Codeium | 対応済み |
| Goose | Block | オープンソース |
| Amp | Sourcegraph | 対応済み |
| OpenCode | - | オープンソース |
| Codex CLI | OpenAI | skills.md として対応 |
| Gemini CLI | v0.23.0で対応 |
一度作成した Skill は、これらのツール間で再利用できます。チームで異なるツールを使っていても、同じ Skills を共有できるのがオープンスタンダードの利点です。
まとめ
Agent Skills は、Claude Code に「作業のやり方」を教える仕組みです。
- 何度も同じ指示をしている → Skill にして自動化
- チームで作業ルールを統一したい → Project Skills として共有
- 特定の作業では安全に動いてほしい →
allowed-toolsで制限
一度設定すれば Claude が自動で適用してくれるので、毎回の指示が不要になり、作業効率が上がります。
まずは「毎回同じことを指示している」作業を1つ見つけて、Agent Skills を試してみてみてください。
参考リンク
- Agent Skills - Claude Code Docs
- Equipping agents for the real world with Agent Skills
- Agent Skills Best Practices
針生 泰有(執筆記事の一覧)
サーバーワークスで生成AIの活用推進を担当
