Skills（スキル）

Skills は、Claude Code に新しい能力を教える仕組みです。SKILL.md ファイルに指示を書くと、Claude のツールキットに追加され、/スキル名 で呼び出したり、会話の流れに応じて Claude が自動的に使ったりできます。

Skills とは

身近な例えで理解する

なぜ Skills が必要なのか

1. カスタムコマンドの上位互換

Skills は .claude/commands/ のカスタムコマンドを包含する機能です。公式ドキュメントでも「Custom commands have been merged into skills」と明記されています。カスタムコマンドに加えて以下ができます:

• ディレクトリ内に複数ファイルを持てる（テンプレート、スクリプト、参考資料）
• Claude が自動的に呼び出せる（手動 /コマンド だけでなく）
• サブエージェントで隔離実行できる（context: fork）
• ツール制限ができる（allowed-tools）

2. Claude が状況に応じて自動で使ってくれる

カスタムコマンドは /コマンド名 と明示的に打つ必要がありますが、Skills は description を元に Claude が「今この場面で使うべきだ」と判断して自動的に適用できます。

例えば explain-code スキルの description に「コードの仕組みを解説する」と書いておけば、ユーザーが「この関数どう動くの？」と聞いただけで自動的に図解付きの解説を返します。

3. テンプレートやスクリプトを同梱できる

1つのスキルがディレクトリになるので、SKILL.md（本体）に加えて、テンプレートファイル、サンプル出力、ヘルパースクリプトなどをまとめて管理できます。

Skills の公式フォーマット

ディレクトリ構成

.claude/skills/
└── my-skill/
    ├── SKILL.md           # メイン指示ファイル（必須）
    ├── template.md        # テンプレート（任意）
    ├── examples/
    │   └── sample.md      # サンプル出力（任意）
    └── scripts/
        └── helper.sh      # ヘルパースクリプト（任意）

SKILL.md のみ必須です。他のファイルは任意で、SKILL.md から参照します。

SKILL.md の構造

---
name: my-skill
description: このスキルが何をするか、いつ使うか
---

ここにスキルの指示をマークダウンで記述

YAML フロントマター（--- で囲まれた部分）+ マークダウン本文の構成です。

フロントマターフィールド

フィールド	必須	説明
name	いいえ	スキル名。省略時はディレクトリ名を使用
description	推奨	スキルの説明。Claude が自動呼び出しの判断に使う
argument-hint	いいえ	引数のヒント。[issue-number] のように表示される
disable-model-invocation	いいえ	true で Claude の自動呼び出しを禁止（手動のみ）
user-invocable	いいえ	false で / メニューから非表示（Claude のみ使用）
allowed-tools	いいえ	スキル実行中に許可するツール
model	いいえ	使用するモデル
context	いいえ	fork でサブエージェントとして隔離実行
agent	いいえ	context: fork 時のエージェント種別（Explore, Plan 等）

引数の受け渡し

変数	説明
$ARGUMENTS	ユーザーが渡した全引数
$ARGUMENTS[0], $ARGUMENTS[1]	位置引数（0始まり）
$0, $1, $2	位置引数の短縮形
${CLAUDE_SKILL_DIR}	SKILL.md があるディレクトリのパス
${CLAUDE_SESSION_ID}	現在のセッション ID

動的コンテキスト注入

!`command` 構文でシェルコマンドの出力をスキル内容に埋め込めます。コマンドはスキル送信前に実行され、出力で置換されます。

---
name: pr-summary
context: fork
agent: Explore
---

PR の差分: !`gh pr diff`
変更ファイル: !`gh pr diff --name-only`

呼び出し制御

設定	ユーザー呼び出し	Claude 自動呼び出し	用途
（デフォルト）	可	可	汎用スキル
disable-model-invocation: true	可	不可	デプロイ等の副作用があるタスク
user-invocable: false	不可	可	背景知識（ユーザーが直接実行する意味がないもの）

Commands との違い

	カスタムコマンド	Skills
配置	.claude/commands/name.md	.claude/skills/name/SKILL.md
同名時の優先	-	Skills が優先
ディレクトリ構成	単一ファイル	ディレクトリ（テンプレート、スクリプト同梱可）
自動呼び出し	不可	description に基づき Claude が自動判定
サブエージェント実行	不可	context: fork で隔離実行可能
ツール制限	不可	allowed-tools で制限可能

カスタムコマンドは引き続き動作しますが、新規作成は Skills が推奨されています。

サンプルとして用意しているスキル

スキル	呼び出し	自動呼び出し	説明
gen-doc	/gen-doc <パス>	不可	ソースコードからドキュメントを自動生成
pr-summary	/pr-summary [PR番号]	不可	PR の差分を分析して構造化サマリーを作成
explain-code	/explain-code [パス]	可	コードの仕組みを図解と例え話で解説
fix-issue	/fix-issue <Issue番号>	不可	GitHub Issue に基づいて実装〜PR 作成
scaffold-feature	/scaffold-feature <機能名>	不可	Claude Code 機能ディレクトリの雛形生成
gen-site	/gen-site	不可	.claude/ のマークダウンから docs/ の HTML ドキュメントサイトを生成

サンプルスキル全文

以下にサンプルスキルの SKILL.md 全文を掲載します。

explain-code

---
name: explain-code
description: コードの仕組みを図解と例え話で解説する。「これはどう動くの？」「この処理の流れを教えて」のような質問に使用する。
argument-hint: [ファイルパス or コード概念]
---

$ARGUMENTS について、以下の構成で分かりやすく解説してください。

## 解説の構成

1. **身近な例えから始める**: コードの仕組みを日常のものに例える
2. **図を描く**: ASCII アートでデータの流れ、構造、関係性を表現する
3. **ステップごとの説明**: 処理の流れを順番に解説する
4. **ハマりポイント**: よくある間違いや誤解しやすい点を指摘する

## ルール

- 専門用語を使う場合は必ず簡単な説明を添える
- 複雑な概念は段階的に分解して説明する
- 具体的なコード例を含める
- 解説は日本語で行う

fix-issue

---
name: fix-issue
description: GitHub Issue の内容を読み取り、実装を行う。
argument-hint: <Issue番号>
disable-model-invocation: true
---

GitHub Issue $ARGUMENTS に基づいて修正・実装を行ってください。

## 手順

1. `gh issue view $ARGUMENTS` で Issue の内容を取得・解析する
2. 関連するコードベースの既存実装を調査する
3. CLAUDE.md や .claude/rules/ のプロジェクトルールを確認する
4. メインブランチで `git pull` してソースを最新化する
5. `feature/#$ARGUMENTS-概要` または `fix/#$ARGUMENTS-概要` のブランチを作成する
6. TDD でテストを先に書き、実装する
7. 影響範囲のテストを実行して通ることを確認する
8. 日本語のコミットメッセージでコミットする
9. リモートにプッシュする
10. `gh pr create` で日本語の PR を作成し、`Closes #$ARGUMENTS` で Issue を連携する

## 完了報告

実装・更新されたファイルパスと内容を日本語で要約して報告する。

gen-doc

---
name: gen-doc
description: ソースコードからドキュメントを自動生成する。関数・クラスの一覧、引数、戻り値、使用例を含むマークダウン形式のドキュメントを作成する。
argument-hint: <ファイルパス or ディレクトリパス>
disable-model-invocation: true
---

$ARGUMENTS で指定されたファイルまたはディレクトリのソースコードを解析し、ドキュメントを生成してください。

## 手順

1. 対象ファイルを読み取り、言語を特定する
2. 全ての関数・クラス・メソッドを抽出する
3. 以下のフォーマットでドキュメントを生成する
4. 対象ファイルと同じディレクトリに `<ファイル名>.docs.md` として出力する

## 出力フォーマット

```markdown
# <ファイル名>

## 概要
[ファイルの役割を1〜2文で説明]

## 関数一覧

### `functionName(param1, param2)`
[関数の説明]

**引数:**
| 名前 | 型 | 説明 |
|-----|-----|------|
| param1 | string | ... |

**戻り値:** `型` - 説明

**使用例:**
```言語
// コード例
```
```

## 注意事項

- 既存のドキュメントコメント（JSDoc、docstring 等）があれば活用する
- 内部実装の詳細ではなく、利用者視点で記述する
- ディレクトリが指定された場合は、各ファイルごとにドキュメントを生成する

pr-summary

---
name: pr-summary
description: プルリクエストの変更内容を要約する。差分、コメント、変更ファイルを取得して構造化されたサマリーを作成する。
argument-hint: [PR番号]
context: fork
agent: Explore
disable-model-invocation: true
allowed-tools: Bash(gh *)
---

## PR コンテキスト

- PR の差分: !`gh pr diff $ARGUMENTS`
- PR のコメント: !`gh pr view $ARGUMENTS --comments`
- 変更ファイル一覧: !`gh pr diff $ARGUMENTS --name-only`

## タスク

上記の PR 情報を分析し、以下のフォーマットで日本語の要約を作成してください。

### 出力フォーマット

```markdown
# PR サマリー

## 変更の概要
[この PR が何をするのか、なぜ必要なのかを2〜3文で説明]

## 変更ファイル
| ファイル | 変更種別 | 概要 |
|---------|---------|------|
| path/to/file | 追加/修正/削除 | 変更内容の要約 |

## 主な変更点
- [変更点1]
- [変更点2]

## 影響範囲
[この変更が影響する機能やモジュール]

## レビュー時の注目ポイント
- [レビュアーが特に確認すべき点]
```

scaffold-feature

---
name: scaffold-feature
description: Claude Code の機能ディレクトリ（commands, agents, skills, rules, hooks, mcp 等）のスキャフォールドを生成する。ディレクトリ作成、サンプルファイル配置、README.md 生成を一括で行う。
argument-hint: <機能名> [オプション]
disable-model-invocation: true
---

$ARGUMENTS で指定された Claude Code の機能ディレクトリを `.claude/` 配下にスキャフォールド（雛形生成）してください。

## 対応する機能タイプ

以下のタイプを認識し、適切なディレクトリ構成とサンプルを生成します。

### `command <コマンド名>`
`.claude/commands/<コマンド名>.md` を作成する。
- `$ARGUMENTS` を使った引数受け取りのサンプル
- 使用方法セクション

### `agent <エージェント名>`
`.claude/agents/<エージェント名>.md` を作成する。
- YAML フロントマター（name, description, model）
- 基本方針、ワークフロー、出力フォーマットのテンプレート

### `skill <スキル名>`
`.claude/skills/<スキル名>/SKILL.md` を作成する。
- YAML フロントマター（name, description, argument-hint）
- 手順、出力フォーマットのテンプレート

### `rule <ルール名>`
`.claude/rules/<ルール名>.md` を作成する。
- パス別ルールが必要か確認し、必要なら `paths` フロントマターを含める
- 簡潔な箇条書き形式

### `hook <フック名>`
`.claude/hooks/<フック名>.sh` を作成する。
- `jq` で stdin を解析するテンプレート
- 終了コード 0（許可）/ 2（ブロック）のサンプル
- 実行権限を付与する（`chmod +x`）

### `mcp <サーバー名>`
`.mcp.json` にサーバー設定を追加する（既存設定がある場合はマージ）。
- stdio / http のどちらかを確認
- `.claude/mcp/README.md` にサーバー情報を追記

## 共通ルール

1. 既にファイルが存在する場合は上書きせず、ユーザーに確認する
2. 作成するファイルには日本語でコメント・説明を記述する
3. 既存ファイル（同ディレクトリの README.md や他のサンプル）のフォーマットに合わせる
4. 作成完了後、作成したファイル一覧と次にやるべきこと（内容のカスタマイズ等）を報告する

## 使用例

```
/scaffold-feature command deploy
/scaffold-feature agent test-runner
/scaffold-feature skill generate-migration
/scaffold-feature rule api-design
/scaffold-feature hook block-dangerous-commands
/scaffold-feature mcp github
```

## 複数同時生成

スペース区切りで複数指定も可能：

```
/scaffold-feature command deploy agent deployer skill deploy-check
```

スキルの作り方

1. ディレクトリを作成する

mkdir -p .claude/skills/my-skill

2. SKILL.md を作成する

---
name: my-skill
description: このスキルが何をするか、いつ使うかを書く
---

## タスク
$ARGUMENTS に対して以下を実施してください。

1. ステップ1
2. ステップ2
3. ステップ3

3. テスト

# 直接呼び出し
/my-skill 引数

# 自動呼び出し（description にマッチする質問をする）
「○○について教えて」

スキル作成のコツ

• description を具体的に書く - Claude が自動呼び出しの判断材料にする。キーワードを含める
• 副作用があるスキルは disable-model-invocation: true - デプロイ、コミット、メッセージ送信など
• 読み取り専用スキルは allowed-tools で制限 - allowed-tools: Read, Grep, Glob
• 重い処理は context: fork で隔離 - メインの会話コンテキストを消費しない
• SKILL.md は 500行以内 - 詳細な参考資料は別ファイルに分けて参照する
• 引数のヒントを argument-hint に書く - ユーザーが何を渡すべきかわかる

配置場所

スコープ	パス	対象
プロジェクト	.claude/skills/name/SKILL.md	このプロジェクトのみ
個人	~/.claude/skills/name/SKILL.md	全プロジェクト共通
組織	マネージド設定で配布	組織全員

同名スキルがある場合の優先度: 組織 > 個人 > プロジェクト