メインコンテンツへスキップ
BayashiLab LogoBayashiLab(バヤシラボ)
ブログ一覧

Claude Code Skills完全ガイド — SKILL.mdの書き方から発火制御・チーム共有・自動化まで

Claude CodeSkills開発効率化AI開発ツールチーム開発

Now I have all the information I need. Let me write the article.

Claude Code Skillsとは何か — 拡張の「3本柱」における位置づけ

Claude Codeを使いこなす上で欠かせない拡張機能は、大きく3つに分類できる。

  • Skills: 「この状況ではこう振る舞ってほしい」という知識や手順をMarkdownで定義する
  • Hooks: 「ツール実行の前後に必ずこのスクリプトを走らせる」決定的な自動処理
  • Subagents: 「この作業は別のエージェントに委任する」並列・分業の仕組み

Skillsの特徴は段階的な開示にある。スキルの説明文（description）は常にコンテキストに読み込まれるが、本体の指示内容は実際に発火するまで読み込まれない。これにより、数十個のスキルを定義してもコンテキストウィンドウを圧迫しにくい設計になっている。

2026年1月リリースのv2.1.3で、従来の「カスタムスラッシュコマンド」（.claude/commands/配下のMarkdownファイル）がSkillsシステムに統合された。既存の.claude/commands/review.mdはそのまま動作しつつ、.claude/skills/review/SKILL.mdと同等に扱われるようになった。振る舞いの変更はなく、メンタルモデルが整理された形だ。

SKILL.mdの基本構造

Skillを作るには、SKILL.mdファイルをディレクトリに配置する。構造は2つのパートからなる。

  1. YAMLフロントマター（---で囲む）: メタ情報と発火制御
  2. Markdown本文: Claudeが従う具体的な指示
yaml
---
name: review-pr
description: PRの差分をレビューし、問題点と改善提案をまとめる。コードレビューを依頼されたときに使用する。
---

## レビュー手順

1. `gh pr diff` で差分を取得
2. セキュリティ上の問題がないか確認
3. パフォーマンスへの影響を評価
4. 改善提案をまとめて報告

レビューコメントは具体的なコード行を参照すること。

nameフィールドがそのまま/review-prというスラッシュコマンドになる。nameを省略するとディレクトリ名が使われる。descriptionはClaudeがスキルを自動発火させるかどうかの判断材料になるため、できるだけ具体的に書くことを推奨する。

配置場所とスコープ

スキルの配置場所によって、誰がそのスキルを使えるかが決まる。

配置場所 パス 適用範囲
パーソナル ~/.claude/skills/<skill-name>/SKILL.md 自分の全プロジェクト
プロジェクト .claude/skills/<skill-name>/SKILL.md そのプロジェクトのみ
プラグイン <plugin>/skills/<skill-name>/SKILL.md プラグイン有効時
エンタープライズ マネージド設定で配布 組織全体

同名スキルが複数の階層に存在する場合、エンタープライズ > パーソナル > プロジェクトの優先順で上位が勝つ。プラグインのスキルはplugin-name:skill-nameというネームスペースを持つため衝突しない。

チームで共有する場合は、.claude/skills/をバージョン管理にコミットするだけでよい。正直、この手軽さがSkillsの一番の魅力だと思う。

発火制御 — 誰がスキルを呼び出すか

Skillsの設計で最も重要なのが、disable-model-invocationとuser-invocableの2つのフロントマターフィールドによる発火制御だ。

4つの組み合わせ

設定 ユーザーが呼べるか Claudeが自動発火するか 用途
デフォルト（両方未設定） はい はい 汎用スキル
disable-model-invocation: true はい いいえ デプロイ、コミットなど副作用のある操作
user-invocable: false いいえ はい レガシーシステムの背景知識など
両方設定 いいえ いいえ 実質無効（使わない）

副作用を伴う操作には必ずdisable-model-invocation: trueを付ける。Claudeが「コードが良さそうだからデプロイしよう」と判断してしまう事態を防げる。

yaml
---
name: deploy
description: 本番環境にデプロイする
disable-model-invocation: true
---

デプロイ手順:
1. テストスイートを実行
2. アプリケーションをビルド
3. デプロイターゲットにプッシュ
4. デプロイが成功したか検証

実践的なスキル例

引数付きスキル — GitHub Issue修正

$ARGUMENTSプレースホルダを使うと、スラッシュコマンドに引数を渡せる。

yaml
---
name: fix-issue
description: GitHub Issueを修正する
disable-model-invocation: true
argument-hint: "[issue-number]"
---

GitHub Issue $ARGUMENTS をコーディング規約に従って修正する。

1. Issueの内容を読み取る
2. 要件を理解する
3. 修正を実装する
4. テストを書く
5. コミットを作成する

/fix-issue 123と実行すると、$ARGUMENTSが123に置換される。位置引数も使え、$ARGUMENTS[0]や短縮形$0でアクセスできる。

動的コンテキスト注入 — シェルコマンドの埋め込み

!`command` 構文を使うと、スキル本文がClaudeに送られる前にシェルコマンドが実行され、その出力で置換される。

yaml
---
name: pr-summary
description: PRの変更内容をサマリーする
context: fork
agent: Explore
---

## PRコンテキスト
- PR差分: !`gh pr diff`
- 変更ファイル一覧: !`gh pr diff --name-only`

## タスク
このPRの変更内容を要約してください。

サブエージェントで実行するスキル

context: forkを指定すると、スキルが独立したサブエージェントで実行される。メインの会話コンテキストを汚さずに、重い調査や分析を委任できる。

yaml
---
name: deep-research
description: コードベースを深く調査する
context: fork
agent: Explore
---

$ARGUMENTS について徹底的に調査する:

1. GlobとGrepで関連ファイルを探す
2. コードを読み解析する
3. 具体的なファイル参照付きで所見をまとめる

ツール制限とパーミッション

allowed-toolsフィールドで、スキル実行中にClaudeが使えるツールを制限できる。読み取り専用のスキルを作りたい場合に便利だ。

yaml
---
name: safe-reader
description: ファイルを読み取るが変更はしない
allowed-tools: Read, Grep, Glob
---

また、パーミッション設定で特定スキルのClaude自動実行を制御することもできる。

text
# 特定スキルのみ許可
Skill(review-pr *)

# 特定スキルを拒否
Skill(deploy *)

コンテキストバジェットとホットリロード

動的バジェット

スキルのdescriptionはコンテキストに常時読み込まれるが、そのバジェットはコンテキストウィンドウの2%で動的にスケーリングされる（フォールバック値は16,000文字）。スキルが多すぎてバジェットを超えた場合、一部のスキルが除外される。/contextコマンドで警告を確認できる。

環境変数SLASH_COMMAND_TOOL_CHAR_BUDGETで上限をオーバーライドすることも可能だ。

ホットリロード

.claude/skills/内のファイルはライブ変更検出に対応しており、セッション中にスキルを編集しても再起動不要で反映される。これは地味に便利で、スキルの調整をトライ&エラーで繰り返すときのストレスが大幅に減る。

Skills・Hooks・Subagentsの使い分け

最後に、Claude Code拡張の3本柱をどう使い分けるかの指針をまとめる。

観点 Skills Hooks Subagents
定義方法 Markdown（SKILL.md） JSON（settings.json） Markdown（.claude/agents/）
実行タイミング ユーザー指示 or Claude自動判断 ツールイベント前後に確定実行 Claudeが委任を判断
決定性 非決定的（Claudeの判断に依存） 決定的（必ず実行される） 非決定的
主な用途 手順書、規約、ワークフロー定義 lint、フォーマット、ログ記録 並列調査、重い分析の委任
コンテキスト メイン会話と共有（forkも可） コンテキスト外 独立したコンテキスト

判断基準:

  • 「必ずこの処理を実行したい」→ Hooks
  • 「この知識や手順をClaudeに教えたい」→ Skills
  • 「重い作業を別プロセスに委任したい」→ Subagents

たとえば、コミット前に必ずlintを走らせるのはHooksの仕事であり、PRレビューの観点や手順を定義するのはSkillsの仕事だ。そして、大規模なリファクタリングを複数ファイルに並列適用するのはSubagentsの出番になる。これらは排他的ではなく、組み合わせて使うことで真価を発揮する。

まとめ

Claude Code Skillsは、繰り返し作業の自動化とチーム内のワークフロー標準化において強力な仕組みだ。ポイントを整理すると:

  • SKILL.mdにYAMLフロントマター＋Markdownで定義する
  • disable-model-invocationとuser-invocableで発火制御を細かく設定できる
  • .claude/skills/をリポジトリにコミットするだけでチーム共有できる
  • コンテキストバジェット（2%）の範囲で段階的に読み込まれる
  • ホットリロードにより再起動なしで編集が反映される
  • Hooks・Subagentsと組み合わせることで、Claude Codeの拡張性を最大限に引き出せる

まずは自分がよく繰り返している作業を1つ選び、それをSKILL.mdとして書き出してみるところから始めるとよいだろう。

もっと読む他の技術記事も読む