この記事は2026年3月時点の情報に基づいている。
Anthropicが公式で「The Complete Guide to Building Skills for Claude」というPDF（33ページ）を出した。
中身を読んで、自分のスキル構成に反映した。結果から言うと、SKILL.mdのトークン消費が約40%減った。体感でもレスポンスが速くなった。
:::details 初心者向け: トークン消費とは
AIに文章を送ると、AIはその文章を「トークン」という小さな単位に分割して処理します。日本語だと1文字が1〜3トークンくらい。送る文章が長いほどトークンを多く消費し、処理時間もコストも増えます。つまり「トークン消費を減らす」＝「AIに読ませる文章量を減らして、速く安くする」という意味です。
:::
原文（英語PDF）: The Complete Guide to Building Skills for Claude
ここでは、33ページの中身を日本語で要約しつつ、実際に適用して効いた部分を書く。
Skillとは何か
Skillは「フォルダ」だ。中身はこう:
your-skill-name/
├── SKILL.md # 必須。メインの指示ファイル
├── scripts/ # 任意。実行可能コード
├── references/ # 任意。詳細ドキュメント
└── assets/ # 任意。テンプレート等
Claude Code、Claude.ai、APIのどれでも動く。一度作れば全環境で使い回せる。
Progressive Disclosure — これが核心
:::details 初心者向け: Progressive Disclosureとは
直訳すると「段階的な開示」。情報を一度に全部見せるのではなく、必要なタイミングで必要な分だけ見せる設計手法です。スマホアプリの「詳細を見る」ボタンを想像してください。最初は概要だけ表示して、タップしたら詳細が出る——あれと同じ考え方です。
:::
ガイドの中で最も重要な概念。3層構造。
| レベル | 何が入る | いつ読み込まれる |
|---|---|---|
| 第1層 YAMLフロントマター | スキル名、説明、トリガー条件 | 常にシステムプロンプトに載る |
| 第2層 SKILL.md本文 | 手順、例、トラブルシューティング | スキルが関連すると判断されたとき |
| 第3層 references/ | API仕様、詳細例、補足資料 | Claudeが必要と判断したとき |
身近な例えで言うと、レストランのメニューに似ている。第1層は店頭の看板（「イタリアン」「ランチ￥1,000〜」）。通りすがりの全員が見る。第2層はテーブルのメニュー表。店に入った人だけが見る。第3層はスタッフに聞けば出てくるアレルギー情報や産地一覧。聞かれたときだけ出す。
第1層は「常に読み込まれる」。だから短くないといけない。
逆に第3層は「必要なときだけ読み込まれる」。重い情報はここに置く。
この分離だけで、不要なトークン消費が40〜45%減る。 ツイートで40%削減を報告していた人がいたが、自分の環境でも同じ結果になった。
YAMLフロントマターの書き方
:::details 初心者向け: YAMLフロントマターとは
YAML（ヤムル）はデータを書くための書式の一つで、設定ファイルによく使われます。「フロントマター」はファイルの冒頭に --- で囲んで書くメタ情報のこと。ブログ記事の冒頭にタイトルや日付を書くのと同じ感覚です。
:::
第1層。ここが最も重要。
---
name: your-skill-name
description: 何をするか。「〜したい」「〜して」と言われたときに起動する。
---
name: kebab-caseのみ（ハイフン - 区切り。例: my-skill-name）。スペース、アンダースコア、大文字は不可。フォルダ名と一致させる。
description: 簡潔に書く（v2.1.86以降、一覧表示では約250文字に切り詰められる）。「何をするか」と「いつ起動するか」の両方を書く。
悪い例:
description: プロジェクトを管理する。
良い例:
description: Linearのスプリント計画を自動化する。「スプリント作って」「タスク整理して」「Linear計画」と言われたときに起動。
トリガーフレーズを具体的に書くと、スキルの発火精度が上がる。
references/フォルダの使い方
第3層。詳細情報を分離する場所。
やる前（全部SKILL.mdに書いていた）:
your-skill/
└── SKILL.md # 15,000文字。API仕様も手順も全部入り
やった後:
your-skill/
├── SKILL.md # 5,000文字。核心の手順だけ
└── references/
├── api-guide.md # API仕様の詳細
├── examples/ # 具体例集
└── errors.md # エラーパターンと対処法
SKILL.md本文には「詳細はreferences/api-guide.mdを参照」と書くだけでいい。Claudeは必要なタイミングで自分でファイルを開く。
Troubleshootingセクション
ガイドで強く推奨されている構造:
## Troubleshooting
### エラー: Connection refused
原因: MCPサーバーが起動していない
対処: Settings > Extensions で接続状態を確認
### エラー: Rate limit exceeded
原因: API呼び出し頻度が高すぎる
対処: 1秒待ってリトライ。3回失敗したら報告
「エラー → 原因 → 対処」の3点セット。これがあるとClaude が自律でエラーを解決してくれる率が上がる。
実際に適用した
自分の最大のスキル（記事投稿スキル、15,885バイト）に適用した。
6プラットフォーム（Zenn、note、Qiita、はてな、dev.to、Twitter）の投稿手順が1ファイルに全部入っていた。Qiitaに投稿するときも、noteの手順15,885バイト分が全部読み込まれていた。
やったこと:
- 共通のフライトチェックとDoDをSKILL.md本文に残した
- 各プラットフォームの手順をreferences/に分離した
- SKILL.mdには「Zennの場合はreferences/zenn.mdを参照」と書いた
結果: SKILL.md本文が15,885 → 約6,000バイトに減少。プラットフォーム固有の手順は、使うときだけ読み込まれるようになった。
3つのカテゴリ
ガイドはスキルを3種類に分類している:
- ドキュメント・アセット生成型: フロントエンドデザイン、ドキュメント作成、コード生成
- ワークフロー自動化型: 複数ステップの手順を自動化
- MCP拡張型: MCPサーバーの使い方をスキル化
自分のスキルは2番（ワークフロー自動化）に該当した。
テストの3観点
- トリガーテスト: 正しいタイミングで発火するか。パラフレーズでも発火するか。無関係な質問では発火しないか
- 機能テスト: 正しい出力が出るか。エラー処理が動くか
- パフォーマンス比較: スキルあり/なしでツール呼び出し数とトークン消費量を比較
まとめ
Progressive Disclosureの3層構造:
- 第1層（フロントマター）: 常に読み込まれる → 短く、トリガー明示
- 第2層（SKILL.md本文）: スキル発火時に読み込まれる → 核心の手順のみ
- 第3層（references/）: 必要時のみ → 詳細・API仕様・エラーパターン
やることは単純。重い情報をreferences/に移す。SKILL.mdは核心だけにする。それだけで40%のトークン削減。
33ページのPDFを全部読む時間がない人は、この3層分離だけ覚えておけば十分だ。
Skills以外にも、Claude Codeの自律運用で押さえておくべきポイントをまとめています:
- Claude Code Agent Teamsで複数エージェントを並列稼働させる方法 — Skills × Teamsの組み合わせ
- Claude Codeを108時間無人で走らせて起きた全事故と、そこから作った安全装置 — 長時間運用のリアル
- Claude CodeのPreToolUseフックで危険な操作を自動ブロックする — Hooksの具体的な実装
トークン消費をもっと減らしたい方へ
この記事のSkills分離以外にも、トークンを食う原因は10以上あります。700時間の自律運用で見つけた診断パターンをZenn Bookにまとめました:
- Claude Codeを本番品質にする——700+時間の自律稼働から生まれた実践ガイド（¥800・第3章まで無料）— 「9つのやらかしパターン」の章で、キャッシュ汚染・MCP肥大化・コンテキスト爆発など、トークンを食う10の原因と対策を解説