Claude Code エージェントスキルガイド

Claude Code のスキル機能は、Claude に特定のタスクに関する専門知識を教えるマークダウンファイルです。

スキルとは

スキルは以下のような特定のタスクを実行できるようにする機能拡張です：

•チーム標準に基づいた PR レビュー
•好みのフォーマットでのコミットメッセージ生成
•社内データベーススキーマのクエリ
•図やアナロジーを用いたコード説明

重要な特徴: スキルは モデル呼び出し型 — Claude がリクエストに基づいて自動的に使用するタイミングを判断します。明示的なコマンドは不要です。

スキルの動作

3段階のプロセス：

•Discovery（発見）: Claude は起動時に利用可能なスキルの名前と説明のみをロード
•Activation（有効化）: リクエストがスキルの説明と一致すると、完全な SKILL.md をロードする前に確認を求める
•Execution（実行）: Claude はスキルの指示に従い、必要に応じて参照ファイルをロード

ファイル構造

必須ファイル

すべてのスキルには2つのパートからなる SKILL.md ファイルが必要：

yaml

---
name: skill-name
description: スキルが何をするか、いつ使用すべきか
---

# スキル名

## 指示
Claude に対して明確で段階的なガイダンスを提供。

## 例
具体的な例を示す。

オプションのサポートファイル

段階的な情報開示のため、追加ファイルを含めることができます：

code

my-skill/
├── SKILL.md (必須 - 概要)
├── reference.md (詳細ドキュメント - 必要時にロード)
├── examples.md (使用例 - 必要時にロード)
└── scripts/
    └── helper.py (ユーティリティスクリプト - 実行用、ロードしない)

段階的開示の原則: SKILL.md は500行未満に保ち、詳細な参照資料は別ファイルに配置し、Claude が必要な時のみ読み込むようにする。

YAML メタデータフィールド

フィールド	必須	説明
`name`	はい	スキル名（小文字、ハイフン、最大64文字）
`description`	はい	何をするか＆いつ使うか（最大1024文字）
`allowed-tools`	いいえ	Claude が許可なしで使用できるツール
`model`	いいえ	使用する特定の Claude モデル
`context`	いいえ	分離されたサブエージェントコンテキストには `fork` を設定
`agent`	いいえ	`context: fork` 時のエージェントタイプ（例: `Explore`, `Plan`）
`hooks`	いいえ	ライフサイクルフック（PreToolUse、PostToolUse、Stop）
`user-invocable`	いいえ	スラッシュコマンドメニューの表示制御（デフォルト: `true`）

ツールアクセスの制限

allowed-tools を使用して、Claude が使用できるツールを制限：

yaml

---
name: reading-files-safely
description: 変更を加えずにファイルを読み取る
allowed-tools: Read, Grep, Glob
---

または YAML リスト構文で：

yaml

allowed-tools:
  - Read
  - Grep
  - Glob

スキルの配置場所

場所	パス	スコープ
企業	管理設定を参照	組織内のすべてのユーザー
個人	`~/.claude/skills/`	すべてのプロジェクトで利用可能
プロジェクト	`.claude/skills/`	リポジトリ内の誰でも
プラグイン	プラグインにバンドル	プラグインを持つ誰でも

優先順位: 管理 > 個人 > プロジェクト > プラグイン

初めてのスキル作成

例: コード説明スキル

ステップ 1: ディレクトリ作成

bash

mkdir -p ~/.claude/skills/explaining-code

ステップ 2: SKILL.md 作成

yaml

---
name: explaining-code
description: ビジュアル図やアナロジーを使ってコードを説明。コードの動作を説明する際、コードベースについて教える際、またはユーザーが「これはどう動く？」と尋ねた際に使用。
---

コードを説明する際は、常に以下を含める：

1. **アナロジーから始める**: コードを日常的なものに例える
2. **図を描く**: ASCII アートでフロー、構造、関係を示す
3. **コードを順を追って説明**: 何が起こるかをステップバイステップで説明
4. **落とし穴を強調**: よくある間違いや誤解は？

説明は会話的に保つ。複雑な概念には複数のアナロジーを使用。

ステップ 3: ロードとテスト

•スキルは作成時に自動的にロードされる
•Claude に尋ねる：「利用可能なスキルは？」で確認
•テスト：「このコードはどう動く？」

スキルの可視性制御

設定：

yaml

# スラッシュメニューから非表示だが、Claude はプログラム的に使用可能
user-invocable: false

# ユーザーは呼び出せるが、Claude はプログラム的に呼び出せない
disable-model-invocation: true

例:

yaml

---
name: internal-review-standards
description: 内部コードレビュー基準を適用
user-invocable: false
---

フォークコンテキストでスキルを実行

スキルを別のサブエージェントコンテキストで分離：

yaml

---
name: code-analysis
description: コードを分析して詳細なレポートを生成
context: fork
agent: Explore
---

スキル vs その他のオプション

使用するもの	目的	実行タイミング
スキル	Claude に専門知識を与える	Claude が関連性を判断して選択
スラッシュコマンド	再利用可能なプロンプトを作成	`/command` を入力
CLAUDE.md	プロジェクト全体の指示を設定	すべての会話
サブエージェント	別のコンテキストに委任	Claude が委任または手動呼び出し
フック	イベント時にスクリプトを実行	特定のツールイベント時
MCP サーバー	外部ツールに接続	Claude が必要に応じて呼び出し

ベストプラクティス

効果的な説明の書き方

良い説明は2つの質問に答える：

•何をするか？ 具体的な機能をリスト
•いつ Claude は使うべきか？ トリガーキーワードを含める

✅ 良い例:

yaml

description: PDF からテキストとテーブルを抽出、フォーム入力、ドキュメントのマージ。
PDF ファイルを扱う際、またはユーザーが PDF、フォーム、ドキュメント抽出に言及した際に使用。

❌ 悪い例:

yaml

description: ドキュメントのサポート

複数ファイル構造の例

code

pdf-processing/
├── SKILL.md              # 概要とクイックスタート
├── FORMS.md              # フォームフィールドマッピング
├── REFERENCE.md          # 完全な API 詳細
└── scripts/
    ├── fill_form.py      # フォーム入力用ユーティリティ
    └── validate.py       # バリデーションチェッカー

SKILL.md:

markdown

---
name: pdf-processing
description: テキスト抽出、フォーム入力、PDF マージ。PDF ファイル、フォーム、
ドキュメント抽出を扱う際に使用。
allowed-tools: Read, Bash(python:*)
---

# PDF 処理

## クイックスタート

テキスト抽出：
\`\`\`python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

フォーム入力については [FORMS.md](FORMS.md) を参照。
詳細な API リファレンスは [REFERENCE.md](REFERENCE.md) を参照。

トラブルシューティング

スキルがトリガーされない

•説明をトリガーキーワードでより具体的にする
•ユーザーが言及するアクション（抽出、レビュー、分析）を含める
•ユーザーリクエストからの明確なキーワードを使用

スキルがロードされない

•ファイルパスを確認: .claude/skills/my-skill/SKILL.md
•YAML 構文を確認: --- の前に空白行がないこと
•インデントにはスペースを使用（タブは使わない）
•claude --debug を実行してエラーメッセージを確認

複数のスキルが競合

•説明を特定のトリガー用語で区別する
•各スキルの目的に異なるキーワードを使用

プラグインスキルが表示されない

bash

rm -rf ~/.claude/plugins/cache
# その後、プラグインを再インストール

配布

•プロジェクトスキル: .claude/skills/ をバージョン管理にコミット
•プラグイン: プラグイン内にスキルフォルダを含む skills/ ディレクトリを作成
•組織全体: 管理設定を使用（管理者設定）

まとめ

スキルは Claude Code に専門知識を追加する強力な機能です。主なポイント：

✅ 説明のマッチングに基づく自動呼び出し ✅ コンテキスト管理のための段階的開示 ✅ セキュリティのためのツール制限 ✅ プロジェクト、プラグイン、組織設定を介した配布 ✅ フックとフォークされたサブエージェントコンテキストのサポート

まずはシンプルな SKILL.md ファイルから始め、必要に応じてサポートドキュメントやユーティリティスクリプトを追加して拡張してください。

参考リンク

•公式ドキュメント: https://code.claude.com/docs/en/skills

Claude Code エージェントスキル ガイド

スキルとは

スキルの動作

3段階のプロセス：

ファイル構造

必須ファイル

オプションのサポートファイル

YAML メタデータフィールド

ツールアクセスの制限

スキルの配置場所

初めてのスキル作成

例: コード説明スキル

スキルの可視性制御

設定：

フォークコンテキストでスキルを実行

スキル vs その他のオプション

ベストプラクティス

効果的な説明の書き方

複数ファイル構造の例

トラブルシューティング

スキルがトリガーされない

スキルがロードされない

複数のスキルが競合

プラグインスキルが表示されない

配布

まとめ

参考リンク

Claude Code エージェントスキルガイド