無料相談する

カテゴリー / MCP・スキル・プラグイン

Claude Code スキルとは？SKILL.mdの作り方と起動しない時の確認

NO WAVE公開 更新 読了目安 12分

この記事の目次

Claude Code のスキルは、SKILL.md というファイルに手順や知識を書いておき、Claude が関連する場面で自動的に読み込むか、自分で /スキル名 と打って呼び出す仕組みです。作り方は、スキル名のフォルダを作って SKILL.md を置くだけです。うまく動かないときは、まず「置き場所」「frontmatter の書き方」「description の中身」を確認します。以下、公式ドキュメント（code.claude.com）の記述をもとに、作成手順と、起動しない・起動しすぎる・途中で従わなくなるときの確認順をまとめます。

Claude Code スキルは何をするための機能か

公式はスキル作成の判断の基準として、同じ指示や手順をチャットに何度も貼っているとき、または CLAUDE.md の一部が「事実」ではなく「手順」に育ったときを挙げています。CLAUDE.md と違い、スキルの本文は使われたときだけ読み込まれるため、長い参考資料を入れても使うまではほとんど負担になりません。

前提として知っておきたい点は2つです。

  • カスタムコマンドはスキルに統合済みです。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作ります。既存の .claude/commands/ もそのまま使え、同名ならスキルが優先されます。
  • 同梱スキルがあります。 公式は /doctor、/code-review、/batch、/debug、/loop、/claude-api などを例に挙げています。

既定では名前と description が文脈に入り、本文は呼び出されたときに会話へ入ります。ただし呼び出し設定や一覧の文字数予算、表示の上書き設定によって、説明や名前が省かれることがあります。この仕組みが、後半の「起動しない」「説明が切れる」問題の背景です。

最初のスキルはどう作るか

公式の入門例は、未コミットの変更を要約してリスクを挙げるスキルです。まず個人用スキルの配置場所となるディレクトリを作ります。個人用スキルはそのマシンの全プロジェクトで使えます。

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

次に ~/.claude/skills/summarize-changes/SKILL.md を書きます。--- で囲んだ YAML の frontmatter（いつ使うか）と、その後の Markdown 本文（実行時の指示）の2部構成です。

---
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.

!`git diff HEAD` の行は動的コンテキスト注入で、Claude がスキルを読む前に Claude Code がコマンドを実行し、出力で置き換えます。

最後に、公式の手順どおり git 管理下のプロジェクトでファイルを少し編集し、claude で起動して試します。description に合う質問で自動起動させるか、スキル名で直接呼びます。

What did I change?
/summarize-changes

この例に name がないのは、frontmatter の項目がすべて任意だからです。name を省くとディレクトリ名がコマンド名になり、推奨項目は description だけです。本文は一度読み込まれると以降のターンも会話に残るので、簡潔に書きます。公式は SKILL.md を500行未満に収め、詳しい資料は別ファイルに分けて SKILL.md から「何が書いてあり、いつ読むか」を添えて参照するよう勧めています。

スキルはどこに置けば、どのセッションで使えるか

置き場所 パス 使える範囲
個人 ~/.claude/skills/<skill-name>/SKILL.md そのマシンの全プロジェクト（Cowork とクラウドセッションは除く）
プロジェクト .claude/skills/<skill-name>/SKILL.md そのリポジトリ。コミットすればチームも使える
プラグイン <plugin>/skills/<skill-name>/SKILL.md プラグインが有効な場所。/plugin-name:skill-name で呼ぶ

ほかに組織が配布する企業用の場所もあります。同名のスキルは企業 > 個人 > プロジェクトの順で優先されるため、プロジェクトのスキルを直したのに反映されないときは、同名の個人スキルを疑います。

  • Cowork とクラウドセッションは手元の ~/.claude/skills/ を読みません。クラウドセッションはリポジトリの .claude/skills/ を読むので、クラウドでも使うならプロジェクト共有のためにコミットします。
  • 起動した場所より下のサブディレクトリにある .claude/skills/ は、Claude がそのサブディレクトリのファイルを読むか編集するまで読み込まれません。
  • セッション中の編集は再起動なしで反映されます。ただし、セッション開始時に存在しなかったトップレベルのスキル置き場（.claude/skills/ など）を新設した場合は /reload-skills を実行します。

スキルをフックや MCP サーバーとまとめて配るときの形式は、プラグインの使い方ガイドで扱っています。

誰がいつ起動するかは frontmatter でどう決めるか

既定では自分も Claude もスキルを起動できます。これを変える項目が2つあります。

frontmatter 自分で呼べるか Claude が呼べるか 説明の読み込み
（既定） はい はい 常に文脈にある
disable-model-invocation: true はい 自分からは呼ばない 文脈に入らない
user-invocable: false いいえ はい 常に文脈にある

公式は、デプロイやコミットのような副作用のある手順には disable-model-invocation: true を付けるよう勧めています。コードが整って見えたからといって、Claude が自分の判断でデプロイを始めては困るからです。

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

user-invocable: false は、古いシステムの解説のように、コマンドとして打つ意味はないが Claude には知っていてほしい背景知識に使います。

ほかに押さえておきたい項目です。

  • allowed-tools: 呼び出したそのターンだけ、確認なしで使えるツールを指定します。次のメッセージで解除され、使えるツールを絞る機能ではありません。ワークスペースの信頼確認はこの項目を止めないため、公式はリポジトリに入っているスキルの allowed-tools を事前に確認するよう注意しています。
  • context: fork: サブエージェントで実行します。会話履歴は渡らないので、単体で完結する具体的な作業指示が要ります。
  • when_to_use: 起動条件になる具体的な言い回しを足す欄です。description と合わせて1,536字で一覧から切られます。

項目名の表記が一致しないと、エラーも出ずに無視されます。項目名はハイフン区切りの小文字で、例外は when_to_use だけです。

CLAUDE.md・サブエージェント・MCP・フックとどう使い分けるか

機能 読み込みと役割 向いている内容
CLAUDE.md 毎セッション自動 規約、ビルドコマンド、常に守る前提
スキル 必要なときだけ ときどき使う参考資料、/名前 で呼ぶ手順
サブエージェント 別のコンテキストで動く 多数のファイルを読む作業、並列作業
MCP 外部サービスへの接続 ツールとデータアクセスの提供。使い方の知識はスキル側に書ける
フック イベントごとに毎回実行 毎回守らせたい規則

境界で迷いやすいのはフックです。公式は、CLAUDE.md やスキルに書いた「.env を編集しない」は依頼であって強制ではなく、毎回守らせる規則はフックにするよう書いています。各機能の書き方は CLAUDE.md の書き方ガイド、サブエージェントの使い方ガイド、MCP の導入ガイド、フックの使い方ガイドにあります。

スキルが起動しないときは何を順に確認するか

本記事では、公式の確認項目を「一覧に出ていない」のか「出ているのに Claude が使わない」のかで分け、次の順に並べ直しています。

  1. /skills に出ているか。 出ない場合、.claude/skills/name.md のようにファイルを直接置いていないかを見ます。正しくは .claude/skills/name/SKILL.md です。同梱スキルも含めて文脈に何が入っているかは /context で確認できます。
  2. 名前が拒否されていないか。 /スキル名 でも呼べないなら、ゼロ幅スペース、< や >、先頭や末尾のスペースなど使えない文字を疑います。claude --debug で起動し、デバッグログで [names] を検索すると拒否された名前が分かります。
  3. frontmatter が読めているか。 frontmatter はファイルの1行目が --- のときだけ読まれます。YAML が壊れていると項目が空のまま読み込まれ、/スキル名 では動くのに description で照合できず自動起動しません。--debug でパースエラーを確認できます。v2.1.233 以降なら次のコマンドでまとめて探せます（個人スキルは ~/.claude/skills を指定）。
claude plugin validate .claude/skills
  1. 自動起動が止められていないか。 /skills に「user-only」と出ていれば disable-model-invocation: true が付いており、Claude は自分からは起動しません。
  2. description が依頼と合っているか。 ユーザーが自然に使う言葉が入っているか、依頼の言い回しを寄せると起動するかを試します。あいまいだったり他のスキルと重なったりすると、別のスキルが読まれるか取りこぼされます。

スキルが多いと、description そのものが一覧から落ちることがあります。一覧の文字数予算はモデルのコンテキストウィンドウの1%に比例し、超えると使用頻度の低いスキルから説明が外れます。skillListingBudgetFraction 設定で予算を上げるか、優先度の低いスキルを skillOverrides で "name-only" にします。/skill-doctor（v2.1.252 以降）では、スキルごとのコンテキストコストと使用頻度を確認できます。

起動しすぎる、途中で従わなくなるときはどうするか

意図しない場面で起動するなら、description をより具体的にするか、手動でだけ使うスキルに disable-model-invocation: true を付けます。共有スキルのファイルを編集したくなければ、/skills で対象を選び Space で状態を切り替え、Esc で .claude/settings.local.json に保存できます。状態は "on"、"name-only"、"user-invocable-only"、"off" の4つで、プラグインのスキルには効かないため /plugin から管理します。

途中から従わなくなる場合は、公式が挙げる3つの原因に当てはめます。

  • 毎回守るべき規則を飛ばした: フックへ移します。フックは Claude がスキルに従っているかに関係なく、イベントのたびに実行されます。
  • 判断で適用する指示を飛ばした: 「テストを実行する」ではなく「編集のたびにテストを実行する」のように、タスク全体にかかる書き方にします。スキルの内容は呼び出し時に一度会話へ入り、以降のターンでファイルは読み直されません。
  • 会話が圧縮された: スキルを呼び直すと全文が戻ります。自動圧縮後に再添付されるのは各スキルの先頭5,000トークンで、全体の予算は25,000トークンです。重要な指示は SKILL.md の上のほうに置きます。

作ったスキルが効いているかをどう確かめるか

公式は、スキルが起動したことは「Claude が見つけた」ことを示すだけで、意図どおりに動いた証明ではないとしています。起動すべき依頼で起動するかと、出力結果が期待どおりかを分けて確かめます。

方法は、現実的な依頼文をいくつか用意し、新しいセッションでスキルあり・なしの両方を実行して比べることです。新しいセッションを使うのは、スキルを書いていたときの会話が残っていると、指示の書き漏れが見えなくなるからです。個人・プロジェクトのスキルは skillOverrides で "off" にして「なし」の状態を作ります。

この比較は skill-creator プラグインで自動化できます。ターミナルで claude を起動し、プロンプトで次を入力します。

/plugin install skill-creator@claude-plugins-official

Marketplace "claude-plugins-official" not found と出たら、/plugin marketplace add anthropics/claude-plugins-official を実行してから再度インストールします。skill-creator はケースごとに独立したサブエージェントで実行して採点し、スキルあり・なしを集計します。起動すべき依頼とすべきでない依頼で命中率を測り、description の修正案も出します。

公式の記述が変わりうる点

公式ドキュメントとの照合日は2026年10月18日で、主な参照先は公式の「Extend Claude with skills」です。claude plugin validate（v2.1.233 以降）や /skill-doctor（v2.1.252 以降）のように、バージョンに依存する機能があります。手元で動かないときは、まず Claude Code のバージョンを確認してください。

権限設定やチームでの運用ルールまで含めて体系的に学びたい場合は、月額1,980円から参加できる学習コミュニティ AI駆動ラボ に講座があります。

CONTINUE THE SESSION

関連記事