背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. これは一言でいうと何か

スキルは、SKILL.md というマークダウンファイルに指示を書いて Claude のツールキットに追加する仕組みです。Claude は関連する場面で自動的に読み込むか、/skill-name で直接呼び出せます。CLAUDE.md と決定的に違うのは、本体が「使われるときにだけ」読み込まれる点です。長いリファレンス資料でも、必要になるまでコンテキストのコストはほぼゼロで済みます。

作るタイミングは明確です。同じプレイブック・チェックリスト・複数ステップの手順をチャットに何度も貼り付けているとき、あるいは CLAUDE.md のセクションが「事実」ではなく「手順」に育ってしまったときです。

なお、カスタムコマンドはスキルに統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動きます。既存の .claude/commands/ は引き続き動作しますが、スキル側にはサポートファイル用のディレクトリ、呼び出し制御のフロントマター、自動読み込みという追加機能があります。

2. どういう場面で役立つか

• レビュー前のセルフチェック：作業ツリーの diff を要約し、リスクにフラグを立てるスキルを置いておく。後述の summarize-changes がそれで、!`git diff HEAD` によって「開いているファイルからの推測」ではなく実際の diff に基づいた応答が返ります。
• 副作用のあるワークフロー（デプロイ、コミット、Slack 送信）：disable-model-invocation: true を付けると、ユーザーしか呼べません。ドキュメントの表現を借りれば、「コードが準備完了に見えるから」という理由で Claude がデプロイを決めるのは望ましくない、という話です。
• モノレポでパッケージごとに手順が違うとき：apps/web/.claude/skills/ のようにネストして置けます。ルートに deploy、apps/web にも deploy がある場合、後者は apps/web:deploy という修飾名で現れ、Claude は作業中のファイルに一致するバリアントを選びます（v2.1.203 以降）。
• コンテキストを汚したくない調査タスク：context: fork を付けるとスキル本体がサブエージェント（独立コンテキストで動くワーカー）のプロンプトになり、会話履歴から切り離して実行されます。
• アプリの起動・検証：バンドルされたスキル /run（アプリを起動して変更が機能することを確認）と /verify（ビルドして実行し、期待通り動くか確認。テストや型チェックにフォールバックしない）が使えます。ただし DB や env ファイル、マルチステップビルドが要るプロジェクトでは推測の信頼性が落ちるため、/run-skill-generator でレシピを記録させます（3 つとも v2.1.145 以降）。

向かないケース・不要なケース。

1. 常に効かせたい事実や規約はスキルではなく CLAUDE.md やルールに置きます。スキルはオンデマンド読み込みなので、「常時オン」が要件なら道具が違います。
2. ガイドラインだけのスキルに context: fork を付けてはいけません。 「これらの API 規約に従う」のようなタスクのない内容をフォークすると、サブエージェントはガイドラインを受け取るものの実行可能なプロンプトがなく、意味のある出力なしで返ってきます（ドキュメントに明示的な警告があります）。
3. 決定論的に強制したいことはスキルでは保証できません。フック（ライフサイクルイベントで発火する仕組み）を使います。

3. コード・コマンドの実例と解説

前提条件

• スキルはディレクトリで、SKILL.md が必須のエントリポイントです。コマンド名はディレクトリ名から決まります（フロントマターの name は表示ラベルで、/ の後に打つ名前は変えません。プラグインルート SKILL.md だけが例外）。
• 置き場所で適用範囲が決まります。Personal ~/.claude/skills/<skill-name>/SKILL.md（全プロジェクト）、Project .claude/skills/<skill-name>/SKILL.md（そのプロジェクトのみ）、Plugin、Enterprise（管理設定）。同名なら enterprise > personal > project の順でオーバーライドし、任意のレベルのスキルはバンドルされたスキルもオーバーライドします。
• バンドルされたスキル（disableBundledSkills で無効化しない限り常時利用可）には /doctor、/code-review、/batch、/debug、/loop、/claude-api があります。これらは固定ロジックの組み込みコマンドとは違い、プロンプトベースです。
• スキルディレクトリのファイル変更は監視されており、再起動なしで現在のセッションに反映されます（セッション開始時に存在しなかった最上位ディレクトリを新設した場合のみ再起動が必要）。

最初のスキルを作る

mkdir -p ~/.claude/skills/summarize-changes

個人用スキルフォルダにディレクトリを作ります。ここに置いたスキルは全プロジェクトで使えます。ディレクトリ名 summarize-changes がそのままコマンド名になります。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

~/.claude/skills/summarize-changes/SKILL.md に保存します。--- で囲んだ YAML フロントマターが「いつ使うか」を Claude に伝え、その下のマークダウンが「実行時に従う指示」です。ポイントは !`git diff HEAD` の行で、これは動的コンテキスト注入です。Claude Code がコマンドを先に実行し、Claude がスキル本体を見る前に出力へ置き換えるため、指示は現在の diff がインライン化された状態で届きます。前処理であって、Claude が実行するわけではありません。

呼び出しは 2 通りです。説明に一致することを尋ねて自動で呼ばせる（例：What did I change?）か、/summarize-changes と直接打つかです。

スキルはディレクトリで育てる

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

SKILL.md 以外は任意です。テンプレート、期待する出力形式の例、Claude が実行できるスクリプト、詳細なリファレンスなどを同梱できます。重要なのは、サポートファイルは必要なときにだけ読まれること。SKILL.md からリンクして「何が書いてあり、いつ読むか」を Claude に伝えます。目安は SKILL.md を 500 行以下に保つことです。

副作用のあるワークフローは人間だけが引く

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

disable-model-invocation: true により、Claude はこのスキルを自動で読み込めなくなり、ユーザーが /deploy と打ったときだけ実行されます。副次的な効果として、説明文がコンテキストに載らなくなるため、コンテキストコストもゼロになります。逆に「Claude だけが使う背景知識」にしたい場合は user-invocable: false を使います（/ メニューから隠れます）。

$ARGUMENTS はスキル名の後ろに続けた文字列に置換されます。/fix-issue 123 なら $ARGUMENTS が 123 になる、という具合です。位置指定の $ARGUMENTS[0] や短縮形 $0 も使えます。

ツールを事前承認する

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

allowed-tools は、このスキルがアクティブな間だけ、列挙したツールを承認なしで使えるようにします。ツールを制限するものではない点に注意してください（他のツールも呼べますし、通常の権限設定が引き続き効きます）。逆にブロックしたいなら権限設定の拒否ルールを使います。

セキュリティ上の注意が 1 つあります。プロジェクトの .claude/skills/ にチェックインされたスキルの allowed-tools は、そのフォルダのワークスペーストラストを受け入れた後に有効化されます。スキルは広範なツールアクセスを与え得るので、リポジトリを信頼する前にプロジェクトスキルを確認してください。

調査をサブエージェントに逃がす

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

context: fork で新しい分離コンテキストが作られ、スキル本体がそのままサブエージェントへのプロンプトになります。agent フィールドが実行環境（モデル、ツール、権限）を決め、省略時は general-purpose です。組み込みの Explore と Plan は CLAUDE.md と git status を読み込まないため、コンテキストが小さく保たれます。結果は要約されてメイン会話に返ります。

押さえておくべき挙動：スキルは呼ぶと居座る

呼び出されたスキルのレンダリング済み本体は、会話に 1 つのメッセージとして入り、セッションの残りの間ずっとコンテキストに留まります。後のターンで再読み込みされることはありません。だから本体は簡潔に書き、「1 回限りの手順」ではなく「タスク全体に効くスタンディング指示」として書きます。1 行ごとが繰り返しのトークンコストになります。

自動コンパクション（コンテキストが埋まったときの要約）との関係も知っておく価値があります。Claude Code は各スキルの最新の呼び出しを要約の後に再アタッチし、先頭 5,000 トークンを保持します。再アタッチ分は合計 25,000 トークンの予算を共有し、直近に呼ばれたものから埋めていくため、多くのスキルを呼んだセッションでは古いスキルが完全に落ちることがあります。圧縮後にスキルが効かなくなったように見えたら、呼び直して本体を復元してください。

その他（フロントマター全フィールド、${CLAUDE_SKILL_DIR} などの文字列置換、skillOverrides による可視性制御、Skill(name) 形式の権限ルール、複数行の ```! ブロック、disableSkillShellExecution、skill-creator プラグインによる eval、スクリプトを同梱して HTML 可視化を生成する例）は公式ドキュメントを参照してください。

4. まとめと次回予告

• スキルは「手順」を資産化する仕組み。本体は使うときだけ読み込まれるので、長いリファレンスも安く持てます。
• 副作用があるものは disable-model-invocation: true でユーザー専用に。調査は context: fork で分離。
• ただし一度呼べばセッション中ずっと居座ります。SKILL.md は 500 行以下・簡潔に。

トラブルシュートで効く事実 2 点。 スキルがトリガーされないときは、まず説明文にユーザーが自然に使うキーワードが入っているかを確認します。それと、フロントマターの YAML が壊れていると、Claude Code は本体を空のメタデータで読み込みます。この状態でも /skill-name は動くのに、Claude は照合すべき description を持たないため自動呼び出しだけが効かなくなります。--debug でパースエラーを確認してください。

もう 1 点。スキルが増えると、スキル一覧（名前と説明）の文字予算に収まらなくなり、説明が切り詰められることがあります。予算はモデルのコンテキストウィンドウの 1% でスケールし、溢れると呼び出し回数の少ないスキルから説明が削られます。/doctor で一覧のコンテキストコストと最大の寄与元を確認できます。説明は「主要なユースケースを前置きする」書き方が有利です。

次回予告：スキルと並ぶ拡張レイヤーのもう一方、「Hooks」を取り上げます。

関連ページ（本記事で触れた概念の詳細）：CLAUDE.md とルール →「メモリ」、コンパクションと agentic ループ →「Claude Code の仕組み」、context: fork の相方 →「サブエージェント」、決定論的な強制 →「Hooks」、Skill(...) の権限ルール →「権限」、組み込みコマンドとバンドルされたスキルの一覧 →「コマンド」、配布 →「プラグイン」。

---

本記事は執筆時点の公式ドキュメント（スキルで Claude を拡張する）に基づきます。最新は公式ドキュメントをご確認ください。