はじめに
同じ手順を毎回チャットに貼り付けている、あるいはCLAUDE.mdの一部が「事実」ではなく「手順」のように膨らんできた——そんなときに使えるのがSkills（スキル）です。
この記事で分かること
- Skillsとは何か、なぜ「意図通りに呼ばれない」ことがあるのか
- 段階的開示（Progressive Disclosure）というトークン消費を抑える3段階の仕組み
-
SKILL.mdの基本構造とディレクトリ構成 -
name・descriptionの書き方（良い例・悪い例）とオプションフィールド - 応用編：
referencesフォルダと、おまけのskill-creatorプラグイン
① Skillsとは何か
Skillsは、SKILL.mdというファイルに指示を書いておくと、Claude Codeがそれを「道具箱」に追加してくれる仕組みです。
ここで注意したいのが、Skillsは「Claudeが自動的に選ぶ」仕組みだという点です。descriptionの内容とユーザーの依頼が噛み合わないと、意図したSkillが読み込まれないことがあります。公式ドキュメントは「Skillが期待通り動かないとき」の対処法として、次の4つを挙げています。
-
descriptionにユーザーが使いそうな言葉を含める -
What skills are available?とClaudeに聞いて、一覧に出てくるか確認する - 依頼の言い回しを
descriptionに近づけて言い直してみる -
/skill-nameで直接呼び出す
② 段階的開示（Progressive Disclosure）で無駄なく読み込む
「自動的に選ばれる」仕組みを支えているのが、知識を3段階に分けて読み込む段階的開示です。以下のトークン数は、Claude Codeが従うAgent Skills一般仕様のドキュメントに載っている目安値です。
| レベル | 内容 | トークン消費 |
|---|---|---|
| 第1段階: メタデータ |
name・descriptionのみ |
約100トークン/Skill |
| 第2段階: 本文 | SKILL.md全体（指示・例） | 5,000トークン未満 |
| 第3段階以降: 追加リソース | スクリプト・テンプレート・データ | 必要時のみ（アクセスするまで0） |
起動時は全Skillのnameとdescriptionだけが読み込まれるため、多数のSkillsを入れてもコンテキストをほぼ消費しません。実際に使われて初めてSKILL.md本文が、さらに必要になって初めて追加ファイルが読み込まれます。
③ 基本構造とディレクトリ構成
Skillは、SKILL.mdを入口とする1つのフォルダです。置き場所は、自分の全プロジェクトで使うなら~/.claude/skills/<skill名>/、このプロジェクトだけなら.claude/skills/<skill名>/です。
my-skill/
├── SKILL.md # 本体の指示（必須）
├── template.md # Claudeが埋めるテンプレート
├── examples/
│ └── sample.md # 期待する出力の例
└── scripts/
└── validate.sh # Claudeが実行できるスクリプト
SKILL.mdはYAMLフロントマター（---で囲んだ設定）と、その下のMarkdown本文で構成されます。
---
name: my-skill
description: このSkillが何をするか、いつ使うか
---
指示の本文...
Claude Codeではフロントマターの項目はすべて任意で、descriptionだけが「推奨」とされています（nameを省略するとフォルダ名が使われます）。ただしSkillsが従う一般規格（Agent Skills）ではname・descriptionが必須項目とされ、nameは「64文字以内・小文字と数字とハイフンのみ・予約語（anthropic, claude等）禁止」という制約があるため、この形式で書いておくのが無難です。
④ 良いdescriptionの書き方とオプションフィールド
descriptionはClaudeが「このSkillをいつ使うか」を判断する唯一の手がかりです。「何をするか」と「いつ使うか」の両方を、三人称で具体的に書きます。
| 良い例 | 悪い例 | |
|---|---|---|
| 内容 | PDFファイルからテキストと表を抽出する。PDFを扱うとき、またはユーザーがPDFに言及したときに使う | ドキュメント作業を助けます |
| 視点 | 三人称（「Excelファイルを処理してレポートを生成する」 | 一人称（「お手伝いします」 |
Claude Codeにはname・descriptionを含めて全17個の任意フロントマターフィールドがあります（2026年7月時点、一部を紹介）。
| フィールド | 内容 |
|---|---|
disable-model-invocation |
trueで、Claudeの自動判断では呼ばれず/nameでのみ実行 |
allowed-tools |
このSkill実行中、確認なしで使えるツール |
argument-hint |
補完時に表示される引数のヒント（例: [issue-number]） |
context: fork |
サブエージェント（Claudeが呼び出す、会話履歴を引き継がない別スレッド）の中で独立して実行 |
⑤ 応用編：referencesフォルダとskill-creator
SKILL.md本文を簡潔に保ちつつ、詳しい参考資料は別ファイルに分けて、必要なときだけ読み込ませられます。公式の解説記事にある例（分野ごとにファイルを分ける構成）を元にすると、次のようになります。
bigquery-skill/
├── SKILL.md
└── reference/
├── finance.md # 売上・請求に関する指標
└── sales.md # 商談・パイプライン
SKILL.md側からファイル名をリンクしておくと、Claudeは関係するファイルだけを開きます（例: 売上の質問ならfinance.mdだけ）。
作ったSkillが期待通り動くか確かめたいときは、公式が提供するskill-creatorプラグインが使えます。
/plugin install skill-creator@claude-plugins-official
/reload-plugins
/reload-pluginsを忘れると、インストールしたばかりのプラグインが今のセッションで使えません。導入後、「evaluate my ◯◯ skill with skill-creator」のように頼むと、テストケースの作成からSkillあり/なしの比較（ベンチマーク）まで、一連の検証を自動化してくれます。
まとめ：まず1つ、繰り返している指示をSkillにする
Skillsは、繰り返し貼り付けている指示や、CLAUDE.mdで膨らみすぎた手順を、必要なときだけ読み込まれる形で切り出す仕組みです。まずは次の最小構成から試してみてください。
---
name: my-first-skill
description: (何をするか)。Use when (いつ使うか)。
---
## Instructions
(手順をここに書く)