Claude Code スキルとは？最小フォルダの作り方と呼び出し方

Claude Code スキルとは何か

Claude Code スキルは、手順を書いた SKILL.md をフォルダごと置いておき、必要な場面で Claude に読ませる仕組みです。毎回打ち直していた前置きの指示を、1か所にまとめられます。呼び出しは /スキル名 の1行で、description が今の作業に合っていれば Claude が自分で読み込むこともあります。自動で使われるかどうかは description の書き方で決まるので、確実に動かしたいときは手動で呼びます。最初の一歩は、最小構成のフォルダを1つ作り、手動で呼べるか試すことです。

スキルの実体は、手順を書いた Markdown ファイル1つです。必要なら、スクリプトや参考資料を同じフォルダに入れます。長い指示を会話のたびに貼る代わりに、必要なときだけフォルダの中身を読ませます。要約の書式、レビューの観点、コミットメッセージの型など、毎回少しずつ中身が変わる定型作業に向いています。

毎回の前置きを1か所にまとめる

手順が決まっていて、毎回少しずつ中身が違う作業が向いています。たとえば決まった書式での要約、決めた観点でのコードレビュー、社内の言い回しに合わせた文面の調整です。指示を1か所に置けば、次のセッションでも同じ始まり方になります。その場限りの質問や一度きりの調べ物は、スキルにしても使う場面がありません。

スキルとプロンプト・プラグイン・MCP ツールは何が違うのか

プロンプトはその場の指示、プラグインは配布とバンドルの単位、MCP ツールは外部データへの接続で、スキルは作業の手順と知識を再利用できる形で置いておくものです。毎回書くのか、配るのか、つなぐのかによって、置き場所が変わります。

プロンプトはその会話の中だけで効く

チャット欄に書いた指示が効くのは、その会話の中だけです。同じ依頼を書式だけ変えて何度も出しているなら、スキルに移したほうが早く済みます。今日だけの条件や一度きりの相談は、プロンプトのままで足ります。

プラグインと MCP ツールは何を担うのか

プラグインは、スキルやフック、MCP サーバーをまとめて配る単位です。チームに配るなら、スキルを1つずつコピーするより更新の手間が少なくなります。MCP ツールは GitHub や社内データベースのような外部につなぐ役割で、データの扱い方を教えるのがスキル、取りに行く口を開けるのが MCP ツールです。両方使うときは、スキルの中にツールを使う順番を書いておけます。

最小のスキルフォルダはどう作るのか

スキルを作るには、作業フォルダの .claude/skills/ の下にスキル名のディレクトリを作り、その中に SKILL.md を置きます。これで Claude Code から呼び出せます。スクリプトや参考資料は、必要になってから同じフォルダに足せば十分です。

.claude/skills/doc-summary/
├── SKILL.md          必須
├── reference.md      任意：詳細な書式などを置く
└── scripts/
    └── helper.sh     任意：実行させる補助スクリプト

SKILL.md は2つの部分でできています。上部の「---」で囲んだ部分がフロントマターというメタデータで、その下が Claude に渡される指示です。

フォルダと SKILL.md を用意する

---
name: doc-summary
description: 指定したファイルを日本語の要点まとめに変換する。新しいコードや仕様書を読み始めるとき、内容を素早く把握したいときに使う。
allowed-tools: Read Grep Glob
---
$ARGUMENTS で指定されたファイルを読んで、日本語の要点まとめを作ってください。
- 何について書かれているか（1〜2文）
- 重要なポイント（3〜5項目）
- 出てくる専門用語と、初めて聞く人向けの短い説明

name は呼び出し名で、name: doc-summary と書けば /doc-summary で呼べます。description は、Claude が使うかどうかを判断するときに読む説明文です。「何をするか」と「どんな場面で使うか」の両方を書くと、判断の精度が上がります。allowed-tools は任意で、このスキルを呼び出したターンの間、許可を求めずに使えるツールを指定します。許可は次のメッセージを送るとクリアされます。読み取りだけの作業なら Read と Grep を挙げておくと、確認のやり取りなしで進みます。

フロントマターに書ける項目

name と description のほかに、目的別の項目があります。

必須か任意か、受け付ける値の範囲はバージョンで変わることがあります。

スキルはどう呼び出され、いつ自動で使われるのか

呼び出しは2通りです。確実に動かしたいときは、メッセージの先頭に /doc-summary のように書きます。任せたいときは普通の依頼文を送るだけで、使うかどうかは description を材料に Claude が判断します。

メッセージ先頭で呼び出す

/doc-summary task.py と打つと、SKILL.md の中の $ARGUMENTS が task.py に置き換わって Claude に渡されます。複数のファイルはスペースで区切って並べます。$0 や $1 のような番号を使えば、1つ目と2つ目を別々に扱えます。名前をメッセージの先頭以外に書いた場合は、その場では実行されず、そのメッセージの中での許可として扱われます。

定型作業なら、引数に何を渡すかを先に決めておくと迷いません。ファイル名を渡すスキル、レビューの観点を渡すスキルというように、引数の意味を1つに決めれば、呼び出し文も短く済みます。

自動で使われる条件

通常の依頼文では、Claude はまず全スキルの name と description を見て、関係がありそうなものの本文を読み込みます。reference.md のような追加ファイルは、必要になった時点で読みます。最初から全部を読むわけではないので、説明文の書き方がそのまま使い勝手に効きます。

スキル一覧では、description と when_to_use を合わせたテキストが 1,536 文字で切り詰められるので、主要なユースケースは先頭に置きます。切り詰められるのは一覧に渡されるテキストで、SKILL.md の中身は切られません。SKILL.md が長くなってきたら、詳細を別ファイルに分けて、SKILL.md には概要と参照先だけを残すと見通しが良くなります。

自動で呼ばれたくないときの設定

デプロイや送信のように副作用があって、実行のタイミングを自分で決めたい作業は、フロントマターに disable-model-invocation: true を書きます。Claude だけでは呼び出せなくなり、/名前 と打ったときだけ動きます。反対に、ユーザーが実行する意味のない背景知識は user-invocable: false にして、Claude の判断だけに任せます。どちらも任意で、書かなければユーザーと Claude の両方から呼べます。

呼び出しを確認できたら、自分の定型作業を1つ選んでスキルにします。コードを書く作業と組み合わせるなら、AI と一緒にコードを書くときの進め方が参考になります。

作ったスキルが動いているか、どう確かめるのか

確認は、一覧に出ているか、手動で呼べるか、自動で拾われるかの3段階で、上から順に進めます。置き場所の問題か説明文の問題かが、途中で分かれます。

1. ~/.claude/skills/ か .claude/skills/ の下にスキルフォルダがあるか。
2. フォルダ名が予約名と重なっていないか。
3. /スキル名 で手動実行できるか。動けば、中身と引数の渡し方は問題ありません。
4. 通常の依頼文で拾われないなら、description に依頼文と重なる言葉が入っているか。
5. SKILL.md が長すぎないか。手順と参照先だけを残し、詳細は別ファイルに分けます。

動かない原因になりやすい予約名

synced は予約名です。Claude Code が claude.ai からダウンロードしたスキルの置き場所に使うため、enterprise、personal、project のどの場所で作っても、同名のスキルは読み込まれません。大文字と小文字は区別されません。プラグインの外では、anthropic-skills という名前のスキルフォルダやコマンドファイル、anthropic-skills: で始まる名前も読み込まれません。

手動で動くのに自動で拾われないなら、見直すのは説明文です。どちらも動かないなら、置き場所か名前です。この順に見れば、直す場所を毎回探し回らずに済みます。

スキルの中からモデルを呼ぶとき、接続先はどうするのか

スキルの中のスクリプトがモデルを呼ぶときの接続先は、スクリプト側の設定です。MixRoute は Anthropic 互換の Messages API を用意しているので、Anthropic SDK なら api_key と base_url を差し替えるだけで、同じ client と client.messages.create のまま呼び出せます。

リクエストは POST https://api.mixroute.ai/v1/messages に送ります。ヘッダーは Authorization: Bearer（MixRoute のキー）と anthropic-version: 2023-06-01 で、ボディには model、messages、max_tokens が必須です。

Anthropic SDK の接続先を差し替える

変えるのは api_key と base_url の2か所です。api_key は MixRoute のキーに、base_url は https://api.mixroute.ai にします。base_url に /v1 は付けません。リクエストの組み立てやレスポンスの受け取り方は、書き直す必要がありません。OpenAI SDK の場合は、base URL を https://api.mixroute.ai/v1 に向ければ、モデル名はそのままで移行できます。

MixRoute は 250+ のモデルを1つのエンドポイントから提供していて、料金はモデルごとのトークン単価、プラットフォーム手数料はかかりません。同じエンドポイントのモデルなら、スキルの中のモデル名を変えるだけで、呼び出し方もコードもそのまま別のモデルを試せます。スキルは何度も呼ぶものなので、使うモデルは料金を見て選びたいところです。MixRoute の料金体系とプラットフォーム手数料を確認する