Claude Code Skills入門｜仕組みと自作ガイド2026

Claude Codeには.claude/agents/と.claude/commands/という拡張の入り口がすでにある。そこに.claude/skills/という3つ目の入り口が加わった。名前は似ているが、中身はまったく別物だ。

公式ドキュメントを読むと、実は3つ目というより統合に近い。「カスタムコマンドはスキルに統合された」と明記されている。.claude/commands/deploy.mdも.claude/skills/deploy/SKILL.mdも、どちらも/deployという同じコマンドを作る。既存のcommandsファイルは動き続ける。スキルはそこに補助ファイル置き場と、呼び出し方を制御するfrontmatterを追加しただけだ。

本記事は公式ドキュメント（code.claude.com/docs/en/skills）の一次情報と、実行環境にある20件以上のSKILL.mdファイル・検証スクリプトを実際に読んで動かした結果をあわせた独立ガイドだ。frontmatterの全フィールド、コンテキストのライフサイクル、コマンド・サブエージェントとの使い分けまで、既存の日本語記事が薄い領域を中心に書く。

Claude Code Skillsとは何か

Claude Code Skillsとは、SKILL.mdというMarkdownファイル1枚に「いつ使うか」を書いたdescriptionを添えることで、Claudeが必要な場面だけ自動でそのファイルを読み込む拡張機能だ。CLAUDE.mdの一部が長い手順書に育ってしまった時、その部分を切り出す先として使う。CLAUDE.mdは常に全文がコンテキストに乗るが、スキルの本体は呼ばれた時にしか乗らない。だから長い参照資料を書いても、普段のコストはほぼゼロで済む。

似た機能にRAGを思い浮かべる人もいるだろうが、Skillsはもっと素朴だ。ベクトル検索もインデックスも要らない。descriptionの文字列的な近さでClaude自身が「これは使えそうだ」と判断し、該当ファイルだけを読みにいく。仕組みの新しさより、運用のシンプルさに価値がある。

Claude Codeのスキルは、複数のAIツールで共通する「Agent Skills」というオープン標準に準拠している。そのうえで、呼び出し制御・サブエージェント実行・動的コンテキスト注入という3つの拡張機能をClaude Code独自に足している。この3つが、後述する差別化ポイントの核になる。

SKILL.mdの実物構造とfrontmatter全フィールド

実行環境の/mnt/skills/配下で実際に稼働している20件以上のSKILL.mdを確認すると、frontmatterの書き方はシンプルなものが大半だった。

---
name: frontend-design
description: Guidance for distinctive, intentional visual design when building
  new UI or reshaping an existing one. Helps with aesthetic direction,
  typography, and making choices that don't read as templated defaults.
license: Complete terms in LICENSE.txt
---

name・description・licenseの3行で足りている。だがこれは公式ドキュメントが定義する全フィールドのごく一部でしかない。表にすると次のようになる。

必須はどれもない。descriptionだけは書くことが推奨されている。これがないとClaudeは何のスキルか判断できず、事実上呼ばれなくなる。

ここで一つ、見落としがちな注意点がある。上の表はClaude Code内で使えるfrontmatterの全フィールドだが、スキルをパッケージ化してSkills APIやclaude.aiにアップロードする場合は事情が違う。配布用のバリデーションスクリプトを実際に2件のSKILL.md（正常なものと、わざと壊したもの）で動かして確認した。

$ python3 quick_validate.py /tmp/test-skill
Unexpected key(s) in SKILL.md frontmatter: when_to_use.
Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

配布用フォーマットが許すのはname・description・license・allowed-tools・metadata・compatibility の6つだけで、when_to_useやcontext: forkのようなClaude Code固有のフィールドは弾かれる。ローカルで動かす分には自由度が高いが、外部に配布するなら書けるフィールドが狭まる。配布用は6フィールドしか通らない。

自作SKILL.mdの書き方

手順は4つ。重さは均等ではない。最初の2つに時間をかける価値がある。

Step 1: descriptionを発火条件として設計する

要約文ではなく、検索クエリに近い発想で書く。「何をするスキルか」ではなく「ユーザーがどう言ったら発火してほしいか」を列挙する。

---
name: pdf
description: Use this skill whenever the user wants to do anything with PDF
  files. This includes reading or extracting text/tables from PDFs, combining
  or merging multiple PDFs into one, splitting PDFs apart, rotating pages,
  adding watermarks, creating new PDFs, filling PDF forms, encrypting/
  decrypting PDFs, extracting images, and OCR on scanned PDFs.
license: Proprietary. LICENSE.txt has complete terms
---

単語ではなく操作を列挙している。結合・分割・回転・透かし・OCR。ここを1行で済ませると、想定外の言い回しで頼まれた時に発火しない。Anthropic公式のskill-creatorガイドも「Claudeは発火不足になりがちなので、descriptionは少し"押しが強い"くらいでちょうどいい」と書いている。

Step 2: 本体を軽く保つ

SKILL.md本体は500行未満が目安。詳細な手順・エッジケース・APIリファレンスは別ファイルに切り出し、本体には「必要ならこのファイルを読め」という一文だけ残す。実際に読んだPDF処理スキルは本体314行、詳細情報のREFERENCE.mdが611行。本体1に対して詳細情報2の比率で、"必要な時だけ読む"側に約2倍を逃がしていた。

Step 3: 補助ファイルを役割ごとに分ける

REFERENCE.md（詳細仕様）、scripts/（実行コード）、templates/（雛形）というように、ファイルの役割を混ぜない。1ファイル1目的にしておくと、Claudeが必要なものだけをピンポイントで読みに行ける。

Step 4: 配置してテストする

個人利用なら~/.claude/skills/、プロジェクト単位でチーム共有するなら.claude/skills/にディレクトリごと置く。スキルディレクトリの変更はセッション再起動なしで即座に反映される。ただし、それまで存在しなかったスキルディレクトリを新規に作った場合だけは、Claude Codeの再起動が必要になる。

スキルはいつまでコンテキストに残るのか

結論から言う。一度発火したスキルの中身は、会話が続く限りコンテキストに残り続ける。毎ターン読み直されるわけではない。

スキルを呼ぶと、そのSKILL.mdの内容は1つのメッセージとして会話に入り、以降のターンでも保持される。同じ内容のスキルをもう一度呼んでも、Claude Codeは全文を重複させず「すでに読み込み済み」という短い注記だけを足す。引数が変わったり、動的コンテキスト注入の出力が変わったりして中身が変化した場合だけ、フルコンテンツが再度追記される。

オートコンパクション後は25,000トークンの共有予算

会話が長くなりコンテキストが要約される（オートコンパクション）と、Claude Codeはそれぞれのスキルの直近の呼び出しを、要約の後に再アタッチする。ただし無制限ではない。再アタッチされるスキルは合計25,000トークンという共有予算の中に収まる分だけ。各スキルにつき先頭5,000トークンまでが対象で、直近に呼んだスキルから順に予算を埋めていくため、1つのセッションで多くのスキルを呼んでいると、古いものから丸ごと落ちることがある。

この挙動を知らずに「さっき効いていた指示が急に効かなくなった」と感じたら、疑うべきはスキルの中身が消えたことではなく、Claudeが別の選択肢を優先している可能性の方が高い。それでも直らないなら、該当スキルを再度呼び直してフルコンテンツを復元するのが確実だ。

サブエージェントとして走らせる: context: fork

frontmatterにcontext: forkを足すと、スキルは独立したサブエージェントとして実行される。会話履歴にはアクセスできず、SKILL.mdの中身がそのままサブエージェントへのタスク指示になる。

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

## Your task
Summarize this pull request...

!`command`という記法は動的コンテキスト注入と呼ばれる。Claudeがこの中身を実行するのではなく、スキルの内容がClaudeに渡される前にシェルコマンドが先に実行され、出力がその場に埋め込まれる。上の例なら、PRの差分とコメントが実際のテキストとしてすでに埋まった状態でClaudeに渡る。

Explore/Planエージェントと組み合わせる場合の注意

agentフィールドで指定できるのはExplore・Plan・general-purpose、または.claude/agents/配下のカスタムサブエージェントだ。省略時はgeneral-purposeになる。ExploreやPlanはCLAUDE.mdやgitの状態を読み込まずコンテキストを小さく保つ設計のため、これらをagentに指定したforkスキルは、SKILL.mdの中身とエージェント自身のシステムプロンプトだけを見ることになる。会話の背景を前提にした指示を書くと、意図が伝わらないまま実行される。

エージェント・コマンド・スキルの違い

3つとも「.claude/」配下に置くMarkdownという点で似ているが、呼び出され方がまるで違う。このブログ自身のリポジトリを見ても、agents/とcommands/は使っているがskills/はまだ置いていない。3つを混同すると、同じ意図のファイルを重複して作ってしまう。

呼び出しの違いを1文で言うなら

一番近いのは、本棚に専門書を並べておく感覚だ。呼ばれなくても勝手に手が伸びる可能性がある分、descriptionを甘く書くと本棚の本は最後まで開かれない。要約止まりのdescriptionと、操作を具体的に列挙したdescriptionとでは、発火率がまったく違う。

つまずきやすいポイント・トラブルシューティング

実物のSKILL.mdを横断して読み、意図的に壊したテスト用SKILL.mdを1件作って検証すると、失敗しやすい箇所は共通していた。

SKILL.mdは1つのスキルフォルダに1つしか許されない

配布用フォーマットでは、1つのスキルフォルダに複数のSKILL.mdがあると弾かれる。ローカルのClaude CodeはネストしたSKILL.mdも読み込むが、Skills APIやclaude.aiへのアップロードは1つのSKILL.mdしか受け付けない。補助的なMarkdownを書く時は、ファイル名をSKILL.md以外（例えばreference.md）にしておくのが安全だ。

スキルが発火しない時のチェックリスト

ここは見落としがちだが、frontmatterのYAMLが壊れていても、Claude Codeはスキル自体は読み込む。ただしdescriptionが空扱いになるため、Claudeの自動判断からは事実上見えなくなる。--debugフラグを付けて起動すればパースエラーを確認できる。もう一つ意外だったのは、スキルの数が増えるとdescriptionの一覧そのものが文字数上限で切り詰められる点だ。この上限はモデルのコンテキストウィンドウの1%が基準になっており、既定のままだとスキルを増やすほど後から追加した説明文が削られやすくなる。

実務でどう使うか

個人利用なら、説明コストを消すために使う。

スキルとコマンドのどちらを選ぶかは、副作用の有無で決めるとぶれない。

このブログの運用に当てはめると、記事の品質チェックや内部リンク提案はsrc/quality_check.pyやsrc/site_db.pyというPythonスクリプトに固定化している。今はコマンド側で明示的に呼んでいるが、状況判断が絡む呼び出しタイミングの部分だけをSKILL.mdの形にラップし直せば、いつ呼ぶかの判断までClaude自身に任せられる。

よくある質問

まとめ

Claude Code Skillsは、CLAUDE.mdやコマンドでは対応しきれなかった「状況次第で必要になる専門知識」の置き場所だ。descriptionを発火条件として書き、本体を軽く保ち、詳細は別ファイルに逃がす。この3点さえ押さえれば自作できる。

自分なら、まずはコーディング規約かデザインガイドラインのような「毎回説明するのが面倒だが、常にコンテキストに乗せておくほどではない」情報からスキル化する。失敗してもコンテキストの無駄遣い以上の実害がなく、descriptionの書き方を試行錯誤する練習台として最適だからだ。エージェント・コマンド・スキルの3つを揃えたら、次はどれをどこに割り振るかという設計そのものが腕の見せどころになる。