Claude Code Skills完全ガイド：SKILL.md の書き方と実行制御
Claude Code の Skills 機能を徹底解説。SKILL.md の書き方、allowed-tools・context:fork・disable-model-invocation などのフロントマター、引数展開、チーム共有の方法まで2026年4月の最新仕様でまとめました。
TL;DR
Claude Code の Skills は、Markdown ファイル 1 枚でカスタムスラッシュコマンドを定義できる拡張機能です。/commit・/review・/deploy のようなよく使うワークフローをチーム全員で共有できます。
Skills でできること：
/skill-nameで即呼び出せるカスタムコマンドを定義- 使用するツール、実行モデルをスキル単位で制限
- 引数（
$ARGUMENTS/$0から始まる位置引数 / 名前付き引数）を受け取る動的なコマンド - サブエージェントとして独立したコンテキストで実行（
context: fork） - Claude が自動判断で呼び出す「バックグラウンド知識」として機能させる
カスタムコマンドとの関係
公式ドキュメントで、カスタムスラッシュコマンドは Skills へ統合されました。slash-commands の独立ページは廃止され、本ページへ統合されています。
Custom commands have been merged into skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deployand work the same way. Your existing.claude/commands/files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant. — Skills | Claude Code Docs
押さえるべき差分は3点です。
.claude/skills/<name>/SKILL.md | .claude/commands/<name>.md | |
|---|---|---|
| 位置づけ | 推奨 | 動作するが互換パス |
name / paths | 有効 | 無視される |
サポートファイル（scripts/ references/） | 使える | 使えない |
**同名の skill と command が両方ある場合、skill が優先されます。**移行途中に両方置くと command 側は無効になります。
Skills の保存場所
Skills ファイルはスコープに応じて 4 か所に置けます。優先度は下ほど高くなります（プロジェクトスコープがグローバルを上書き）。
| スコープ | パス | 用途 |
|---|---|---|
| 個人（全プロジェクト共通） | ~/.claude/skills/<name>/SKILL.md | 自分だけが使う汎用コマンド |
| プロジェクト | .claude/skills/<name>/SKILL.md | チーム共有のワークフロー |
| プロジェクト（旧形式） | .claude/commands/<name>.md | 後方互換で引き続き動作 |
| エンタープライズ | Managed Settings 経由 | 組織全体へのポリシー配布 |
Tips: プロジェクトの
.claude/skills/に置いて Git 管理すると、チームメンバー全員が同じスラッシュコマンドを使えるようになります。
Skills のディレクトリ構造
Skill は SKILL.md 単体でも動きますが、本格的に育てる場合はディレクトリにして補助ファイルを並べる構成が定番です。
.claude/skills/<skill-name>/
├── SKILL.md # エントリーポイント（必須）
├── references/ # 仕様書・サンプルコード・テンプレ等の参照素材
│ ├── api-spec.md
│ └── style-examples.md
└── scripts/ # 補助スクリプト（任意）
└── lint.shreferences/ 配下のファイルは SKILL.md から @references/api-spec.md の形で取り込めます。SKILL.md 本体に長い仕様や設定値を書き込むとトークンを毎回消費するので、「初動で読み込む指示」だけ SKILL.md に残し、参照される素材は references/ に分離するのが定石です。
scripts/ は Skill 内から実行する補助コマンド置き場です。allowed-tools: Bash(./scripts/*) のようにスクリプト経由に絞ると、許可ツールの管理が一気にシンプルになります。
SKILL.md の基本構造
---
name: fix-github-issue
description: GitHub Issue を番号で指定して修正する。TDD で実装し PR を作成する。
---
GitHub Issue #$ARGUMENTS を修正してください。
手順：
1. `gh issue view $ARGUMENTS` でイシューの内容を確認する
2. 関連するコードを読み、原因を特定する
3. テストを先に書く
4. 実装を行う
5. `npm test` を実行してすべてのテストが通ることを確認する
6. PR を作成する（タイトルに Issue 番号を含める）呼び出し方：/fix-github-issue 123
フロントマター一覧
**すべて任意です。**推奨されるのは description だけで、これがないと Claude がいつ使うか判断できません。
呼び出しと表示
| フィールド | デフォルト | 説明 |
|---|---|---|
name | ディレクトリ名 | 一覧に出す表示ラベル。個人 / プロジェクト skill ではコマンド名を決めない（コマンド名はディレクトリ名から決まる）。プラグイン skill でのみコマンドの最終セグメントを決める |
description | 本文の第1段落 | Claude がいつ使うかを判断するためのメタ説明。when_to_use との合計が 1,536 文字で切り詰められる |
when_to_use | — | いつ呼ぶべきかの追加文脈（トリガーフレーズや例）。description に連結される |
argument-hint | — | オートコンプリートで表示する引数ヒント。例 [issue-number] |
disable-model-invocation | false | true で Claude の自動ロードを禁止し、手動起動専用にする |
user-invocable | true | false で Claude だけが呼べる。/ メニューから隠れる |
実行の制御
| フィールド | デフォルト | 説明 |
|---|---|---|
arguments | — | $name 置換用の名前付き位置引数。宣言順に位置へ対応 |
allowed-tools | 全ツール | 起動したターンの間だけ許可なしで使えるツール |
disallowed-tools | — | この skill がアクティブな間、利用可能プールから除去するツール |
model | セッションのモデル | この skill がアクティブな間のモデル。inherit も指定可 |
effort | セッションから継承 | low / medium / high / xhigh / max |
context | インライン | fork で独立コンテキストのサブエージェントとして実行 |
agent | general-purpose | context: fork 時のサブエージェント種別 |
background | true | context: fork 時のみ有効。false で起動ターン内に結果を待つ |
hooks | — | 起動時に登録され、以降そのセッション中ずっと有効な hooks |
paths | 無制限 | 一致するファイルを扱っているときだけ自動ロードする glob |
shell | bash | 本文中の !`command` を実行するシェル。powershell も指定可 |
メタデータ（Claude Code は動作に使わない）
| フィールド | 説明 |
|---|---|
metadata | 自由形式のキー・値。カタログ管理などに使う |
license | ライセンス。Agent Skills 仕様の一部 |
compatibility | 想定環境の要件（最大500文字） |
**
nameの扱いは誤解されやすい点です。**個人 / プロジェクト skill では、nameを書いてもコマンド名は変わりません。.claude/skills/deploy-staging/SKILL.mdは、nameが何であれ/deploy-stagingで呼び出します。
呼び出し名の決まり方
| 置き場所 | コマンド名の決まり方 | 例 |
|---|---|---|
.claude/skills/<dir>/SKILL.md | ディレクトリ名 | /deploy-staging |
入れ子の .claude/skills/（名前が衝突する場合） | 作業ディレクトリからの相対パス + ディレクトリ名 | /apps/web:deploy |
.claude/commands/<file>.md | 拡張子を除いたファイル名 | /deploy |
プラグインの skills/<dir>/ | name またはディレクトリ名に、プラグイン名の接頭辞 | /my-plugin:review |
claude.ai へアップロードする場合の制限
claude.ai の skill アップロード、Skills API、package_skill.py によるパッケージングで使えるのは
name / description / license / compatibility / metadata / allowed-tools の6つだけです。
argument-hint などを含めるとハードエラーになります。
引数の展開
スキル本文中では以下の変数が使えます。
インデックスは 0 始まりです。
$0が第1引数、$1が第2引数になります。公式ドキュメントの原文は次のとおりです。
$N— Shorthand for$ARGUMENTS[N], such as$0for the first argument or$1for the second. — Skills | Claude Code Docsスキル名やコマンド名を参照する変数は存在しません。
| 変数 | 意味 |
|---|---|
$ARGUMENTS | 呼び出し時に渡された引数全体（入力されたままの文字列） |
$ARGUMENTS[0] | 第1引数（0 始まりのインデックス） |
$0 $1 $2… | $ARGUMENTS[N] の短縮形。$0 が第1引数 |
$name | arguments フロントマターで宣言した名前付き引数 |
${CLAUDE_SESSION_ID} | 現在のセッションID |
${CLAUDE_EFFORT} | 現在の effort（ultracode は xhigh として報告される） |
${CLAUDE_SKILL_DIR} | SKILL.md を含むディレクトリ |
${CLAUDE_PROJECT_DIR} | プロジェクトルート |
${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} | プラグイン skill でのみ置換される |
---
name: pr-review
description: PR を番号またはURLで指定してコードレビューする
arguments: [pr]
---
PR $pr をレビューしてください。
- セキュリティ上の問題がないか確認する
- パフォーマンスへの影響を評価する
- コーディング規約（CLAUDE.md を参照）への準拠を確認する
- `gh pr view $pr --comments` で既存コメントも確認する位置番号は取り違えやすいので、引数が複数あるなら arguments で名前を付けるのが安全です。
置換されなかったときの挙動
| 記法 | 対応する引数が無いとき |
|---|---|
$0 $1 などの位置指定 | 置換されず、そのまま残る |
arguments で宣言した $name | 空文字列に展開される |
複数語をひとつの引数として渡すにはクォートで囲みます。/my-skill "hello world" second なら $0 が hello world、$1 が second です。
リテラルの $ を書きたい場合は \$1.00 のようにバックスラッシュでエスケープします。
allowed-tools でツールを制限する
スキル実行中に使えるツールを絞り込むと、意図しない操作を防げます。
---
name: read-only-audit
description: コードベースを読み取り専用で監査する（変更は一切行わない）
allowed-tools: Read Glob Grep
---
以下の観点でコードベースを監査してください：
- 認証ロジックの問題点
- 入力バリデーションの漏れ
- ハードコードされた認証情報
変更は一切行わないこと。監査レポートのみ出力する。ツール名は Read・Bash(git *)（コマンドを絞り込む）・Edit|Write のようにパターン指定も使えます。
context: fork — 独立コンテキストで実行
context: fork を指定すると、スキルがサブエージェントとして実行されます。メインセッションのコンテキストを汚さずに独立したタスクを実行したい場合に使います。
---
name: dependency-check
description: 依存関係の脆弱性チェックを独立して実行する
context: fork
allowed-tools: Bash(npm audit) Bash(yarn audit) Read
---
プロジェクトの依存関係をセキュリティ面で監査してください。
1. `npm audit` または `yarn audit` を実行する
2. CRITICAL・HIGH の脆弱性を一覧化する
3. 修正方法（バージョンアップで解決するもの / 手動対応が必要なもの）を区別する
4. 修正方法を Markdown テーブルで出力する
修正は行わない。レポートのみ作成する。disable-model-invocation — Claude に勝手に使わせない
デプロイや DB マイグレーションのような副作用が大きいスキルは、disable-model-invocation: true で Claude が自動判断で使えないようにします。
---
name: deploy-production
description: 本番環境にデプロイする（必ずユーザーが明示的に指示すること）
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(npm run deploy)
---
本番環境へのデプロイを実行します。
1. `git log --oneline -5` で最新コミットを確認する
2. `npm run build` でビルドを実行する
3. テストが通っていることを確認する
4. `npm run deploy` を実行する
5. デプロイ後のヘルスチェック URL にアクセスして動作確認する
⚠️ 元に戻せない操作です。実行前に必ずコミット内容を確認してください。user-invocable: false — Claude 専用の知識として使う
user-invocable: false にすると、スラッシュコマンドとして一覧に表示されなくなり、Claude が文脈に応じて自動的に参照するバックグラウンド知識として機能します。コーディング規約・アーキテクチャ決定記録・よくある失敗パターンなどを Claude に常時読み込ませたい場合に使います。
---
name: error-handling-guidelines
description: このプロジェクトのエラーハンドリング規約。エラー処理を書く際に必ず参照する。
user-invocable: false
---
## エラーハンドリング規約
### 基本方針
- エラーは握りつぶさない。必ず catch して意味のあるメッセージをつけて再スロー
- 外部 API エラーは `ExternalServiceError` でラップする
- バリデーションエラーは `ValidationError` を使う
- DB エラーは直接ユーザーに見せない（内部エラーを隠蔽する）
### 禁止パターン
```typescript
// NG: エラーを握りつぶす
try { ... } catch (e) {}
// NG: any でキャッチする
catch (e: any) { console.error(e) }推奨パターン
// OK: 意味のあるメッセージをつけて再スロー
catch (error: unknown) {
throw new DatabaseError('ユーザー取得に失敗しました', { cause: error })
}
---
## シェルコマンドの動的実行（`` !`command` `` 構文）
スキル本文中で `` !`command` `` を使うと、スキルがロードされた時点でコマンドを実行して、その出力を本文に注入できます。
```markdown
---
name: review-pr
description: 現在チェックアウト中のブランチの PR をレビューする
---
現在の PR をレビューしてください。
## 関連ドキュメント
- Skills をチームでどう設計・配布するか: [Skills アーキテクチャ](/knowledge/harness-engineering/skills-architecture)
- スラッシュコマンドとの違いと使い分け: [カスタムスラッシュコマンド実践](/knowledge/ai-tools/claude-code/custom-commands)
- Codex 側の Skills: [Codex の Agent Skills](/knowledge/ai-tools/codex/agent-skills)
## 差分
!`git diff main...HEAD`
## 変更ファイル
!`git diff --name-only main...HEAD`
上記の変更について、セキュリティ・パフォーマンス・コーディング規約の観点でレビューしてください。paths — ファイルパターンに応じた自動ロード
特定のファイルを操作している時だけ自動的に読み込まれるスキルを作れます。
---
name: prisma-best-practices
description: Prisma を使ったDBアクセスの規約。*.prisma や DB 操作ファイルで自動ロード。
user-invocable: false
paths: ["**/*.prisma", "**/repositories/**/*.ts", "**/db/**/*.ts"]
---
## Prisma の使い方規約
- N+1 問題を避けるため、関連エンティティは `include` で一括取得する
- トランザクションは `prisma.$transaction()` を使う
- 生 SQL は原則禁止（パフォーマンス上やむを得ない場合は `$queryRaw` を使い、引数は必ずバインド変数にする）実践的なスキル集
/commit — 規約に従ったコミットメッセージを生成
---
name: commit
description: ステージングされた変更を Conventional Commits 形式でコミットする
allowed-tools: Bash(git *) Bash(npm test)
---
ステージングされている変更をコミットしてください。
1. `git diff --staged` で変更内容を確認する
2. `npm test` を実行してテストが通ることを確認する（失敗したらコミットしない）
3. Conventional Commits 形式でコミットメッセージを作成する
- 形式: `type(scope): 件名（日本語）`
- type: feat / fix / refactor / test / docs / chore
4. `git commit -m "..."` を実行する/generate-tests — テスト自動生成
---
name: generate-tests
description: 指定ファイルのユニットテストを生成する
---
`$ARGUMENTS` のユニットテストを書いてください。
- テストフレームワークはプロジェクトの設定（package.json を確認）に従う
- 正常系・異常系・境界値をカバーする
- テストファイルは `$ARGUMENTS` と同じディレクトリに `*.test.ts` として作成する
- モックは最小限にする（統合テストを優先する）/explain — コードの解説
---
name: explain
description: コードやアーキテクチャを日本語で解説する
allowed-tools: Read Glob Grep
context: fork
---
`$ARGUMENTS` について日本語で解説してください。
- 引数が空の場合は現在の会話で話題になっているコードを解説する
- 「なぜそう実装されているか」の背景まで含める
- ジュニア開発者にも分かりやすい言葉を使うSkills とサブエージェントの使い分け
「結局 Skills とサブエージェントはどう使い分けるのか」は最も混乱しやすいポイントです。役割が異なるので、判断軸を明確にしておきます。
| 観点 | Skills | サブエージェント |
|---|---|---|
| 主目的 | 知識・手順の提供（Claude に「どう動くか」を教える） | タスクの委譲（独立コンテキストで実行させる） |
| コンテキスト | メインと共有 | 独立（メインを汚さない） |
| モデル | セッションのデフォルト or model 指定 | サブごとに自由（Haiku で節約も可） |
| 並列性 | 直列（メインの中で展開） | 並列実行可能 |
| 典型用途 | コミット規約、デプロイ手順、コーディング規約 | コードベース調査、レビュー、テスト生成 |
判断のコツは「渡したいのは知識か、それとも仕事そのものか」です。コミットメッセージの書き方を統一したい → Skills、認証周りの実装を独立コンテキストで一式調査させたい → サブエージェント、という切り分けになります。
サブエージェントの skills フィールドで Skill を持たせる
サブエージェントの定義から特定の Skill だけを使わせることもできます。サブの責務を絞りつつ、共通ノウハウは Skill 側に集約できる組み合わせ方です。
---
name: pr-reviewer
description: |
Use PROACTIVELY when reviewing pull requests.
PR の差分を読み、コーディング規約とセキュリティ観点でレビューする。
tools: Read Glob Grep Bash(gh *)
skills: coding-standards, security-checklist
model: claude-sonnet-4-6
---サブエージェントごとに「使う Skill だけ」をホワイトリスト化できるので、関係ない Skill が誤発火することがなくなります。チームで Skill を増やしていくときの衛生面でも有効です。
自動呼び出しされない時の切り分け
Skill を作ったのに Claude が呼んでくれない、というのは初期によくある詰まりどころです。確認順序をテンプレ化しておきます。
/で一覧に出ているか … 出ていなければ配置パス（.claude/skills/<name>/SKILL.md）かnameフィールドを再確認descriptionに具体的な発動条件が書かれているか … 「コードをレビューする」のような汎用すぎる説明だと自動選択されにくい。「PR レビュー時に使用」「Conventional Commits でコミットを作る時」のように when を書くPROACTIVELY/MUST BE USEDキーワード … 似た用途の Skill が複数ある場合は優先度を引き上げるpaths制約と作業ファイルが整合しているか …paths: ["**/*.prisma"]を指定したのに対象外ファイルで使おうとしていないか- 明示呼び出しで動くか …
/skill-nameで手動実行して機能自体は動くか確認。動けば「自動選択精度」の問題、動かなければ Skill の中身の問題
「自動で呼ばれない」と「手動でも動かない」は原因が全く違うので、最初に手動呼び出しで切り分けると最短で原因に辿り着けます。
ハマりポイント・注意事項
SKILL.md のファイル名がそのままコマンド名になる
~/.claude/skills/fix-issue/SKILL.md なら /fix-issue で呼び出せます。ハイフン区切りのケバブケースが推奨です。
allowed-tools の省略はリスクになりうる
指定しないと Claude Code が使えるすべてのツールを使います。副作用のあるスキルには必ず allowed-tools を設定してください。
disable-model-invocation と user-invocable: false は別物
前者は「ユーザーだけが使える（Claude は使えない）」、後者は「Claude だけが使える（ユーザーは使えない）」です。両方指定すると誰も呼び出せないので注意。
プロジェクトスキルはグローバルスキルを上書きしない（マージされる）
同名のスキルがある場合はプロジェクト側が優先されます。意図的に無効化したい場合は disable-model-invocation: true を使うか、同名でファイルを上書きしてください。
/ コマンドで一覧確認
利用可能な全スキルは / を入力すると一覧表示されます。設定が反映されているか確認するのに使えます。
組み込みの Skills（bundled skills）
自分で作らなくても、Claude Code には最初からいくつかの Skill が入っています。プロンプトベースで、Claude に詳細な指示を与えてツールで作業させる仕組みです（固定ロジックを実行する組み込みコマンドとは別物）。
主なものです。
| Skill | 用途 |
|---|---|
/doctor（別名 /checkup） | セットアップの総合点検 |
/code-review（別名 /review） | 差分や PR のレビュー。ultra で深度を上げる |
/debug | 不具合の切り分け |
/batch | 同じ指示を複数対象へ一括適用 |
/loop（別名 /proactive） | 一定間隔での繰り返し実行 |
/run | アプリを起動して変更の動作を確認する |
/verify | ビルドして実行し、変更が意図どおりか確認する |
/run-skill-generator | /run と /verify にプロジェクトの起動方法を教える |
/fewer-permission-prompts | 権限確認を減らす許可リストを提案 |
/claude-api | Claude API まわりの移行・監査 |
/dataviz | データ可視化 |
一覧は /help で確認できます（上記が網羅とは限りません）。自分で Skill を作る前に、既にあるか確認する習慣をつけると無駄が減ります。
無効化する
組織のポリシーなどで組み込み Skill を止めたい場合は2通りあります。
まとめて無効化：
{ "disableBundledSkills": true }ただし /doctor だけは残ります（セットアップ点検を潰さないため）。隠したい場合は環境変数 DISABLE_DOCTOR_COMMAND か、後述の skillOverrides で "doctor": "off" を指定します。
個別に制御：
{
"skillOverrides": {
"legacy-context": "name-only",
"deploy": "off"
}
}| 値 | Claude への提示 | / メニュー |
|---|---|---|
"on"（既定） | 名前と説明 | 出る |
"name-only" | 名前のみ | 出る |
"user-invocable-only" | 隠す | 出る |
"off" | 隠す | 隠す |
/skills メニューで Skill を選び Space で状態を巡回、Enter で .claude/settings.local.json に保存されます。
プラグイン由来の Skill は skillOverrides の対象外です（/plugin で管理します）。
権限ルールでも制御できます。Skill(commit) は完全一致、Skill(review-pr *) は引数付きの前方一致です。