CLAUDE.mdをSkillsに移行してコストを削減する方法

このTipsでできること

CLAUDE.mdはセッション起動のたびに丸ごとcontextへ読み込まれます。Bashのフォーマットを直すだけの作業でも、300行のCLAUDE.mdに書かれたPRレビュー手順やDBマイグレーション手順を毎回読み込むことになります。無関係な作業のたびにこのトークンを払い続けているなら、その指示はSkillsへ移すことでコストを構造的に下げられます。

公式ドキュメントは、複数ステップの手順やコードベースの一部にしか関係しない項目をCLAUDE.mdに書かず、Skillかパス限定のruleに移すよう勧めています。CLAUDE.mdは200行未満に保つのが目安です。Claude Codeのシステムプロンプトを8割以上削った背景は、Claude 5世代のcontext engineeringで読み解いています。

CLAUDE.mdとSKILL.mdの違い

CLAUDE.mdが肥大化する原因は、常時要る事実と特定タスクの手順を同じファイルに書き足していくことです。違いは次の表のとおりで、どちらに置くかは「毎回要るか」で決まります。

自分のCLAUDE.mdは重いのか、先に確かめる

移行を始める前に、いまのCLAUDE.mdが実際に重いかを確認します。Claude Codeには、確認のための入口がいくつかあります。

• 推奨の長さ(1ファイル200行)を超えると、起動時と/statusを実行したときに警告が出ます。個々には収まっていても、合計が上限を超えると別の警告が出ます。CLAUDE.md・rulesファイル・@pathのimportは、それぞれ別のファイルとして数えられます
• /doctorは、チェックイン済みのCLAUDE.mdについて削れる箇所を提案します。ディレクトリ構成や依存の一覧のように、コードベースから読み取れる内容を削る提案で、落とし穴・理由づけ・ツール既定と違う規約は残す方針です。この確認にはv2.1.206以降が必要です
• /doctor prompt-auditは、古いモデル向けに書かれた指示や、存在しないファイル・コマンドへの参照、矛盾する指示を探します。v2.1.283以降で使え、CLAUDE.mdに加えて.claude/配下のrules・Skill・サブエージェントなども対象です。移行後の見直しにも使えます

重さの基準は行数より中身で見たほうが実用的です。コードを読めば分かる情報は、Claudeが自分で読み取れるので、CLAUDE.mdに置く理由が薄くなります。手順書のような長い文章が混じっていれば、それがSkillへ移す候補です。

症状別の見分け方

どの指示をSkillへ動かすかは、CLAUDE.mdが膨らんだ理由から逆算すると判断しやすくなります。公式ドキュメントが挙げる追記のきっかけは次の4つです。

• Claudeが同じ間違いを2回目にしたとき
• コードレビューで、このコードベース特有の知識が指摘されたとき
• 前回のセッションで打ったのと同じ訂正・補足をチャットにまた打ったとき
• 新しいメンバーが生産的に動くために同じ文脈が必要になるとき

どれも一度きりの追記としては合理的です。問題は、書いた内容がその後ずっと毎セッションのcontextに残り続けることです。1年前に対応した移行手順や、特定パッケージでしか使わない規約が消えずに残れば、無関係な作業のたびにそのぶんのトークンを払います。

仕分けの基準は次のとおりです。

• 事実として毎回要るもの(ビルドコマンド・テストコマンド・命名規則・プロジェクト構成、「常にXをする」型のルール)はCLAUDE.mdに残す
• 複数ステップの手順は、Skillへ移す
• コードベースの一部にしか関係しない項目は、パス限定ruleかSkillへ移す

過剰実装を防ぐスコープ指示のような恒常ルールは、前者の層に置けます。書き方はClaudeの過剰実装を防ぐプロンプトの書き方にまとめました。

CLAUDE.mdとSkillsのコスト構造の違い

表で見たとおり、常時コストになるのはCLAUDE.mdの本文と、Skillsの一覧部分です。Skillsの本文は呼び出された時点で入り、呼び出し後は会話に残り続けます。

Skillsの一覧部分も無料ではありません。一覧に載るdescriptionとwhen_to_useの合計は1,536文字で切り詰められます。一覧に載るSkillはすべて、毎ターン分のcontextを使います。disable-model-invocation: trueのSkillは説明文が一覧に入らないため、この常時コストの対象外です。使われていないSkillが溜まっていると、それ自体が常時コストになります。

使っていないSkillの洗い出しには/skill-doctorを使います。各Skillのcontext上のコストと呼び出し頻度が分かるレポートが出ます。一覧全体の見積もりは/doctorで確認できます。

Skillsの前に検討したい中間の選択肢

CLAUDE.mdとSkillsの間には、.claude/rules/によるパス限定ルールという中間層があります。

分割の代替としてよく試されるのが@path/to/fileによるCLAUDE.mdのimportですが、これは起動時のコストを下げません。importされたファイルは起動時に展開されて本体と同じくcontextに入るため、300行を複数ファイルに分けて束ねても、読み込まれるトークン量は変わりません。importは整理には役立ちますが、contextは減りません。

CLAUDE.mdが起動時に読まれるのは、作業ディレクトリより上位の階層にあるものです。サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリのファイルを読んだときにオンデマンドで入ります。

.claude/rules/配下にapi-design.mdのようなファイルを置き、frontmatterのpathsにglobパターンを書きます。

---
paths:
  - "src/api/**/*.ts"
---
 
# API開発ルール
 
- 全エンドポイントに入力バリデーションを必須にする
- エラーレスポンスの形式を統一する

pathsを書かないルールファイルはCLAUDE.mdと同じく無条件で読み込まれるので、コスト面の効果を出すにはpathsの指定が前提です。手順を伴わない領域限定の恒常ルールはこの層に、特定タスクの長い手順はSkillsに、と切り分けます。

実際に移行する手順

PRレビュー手順を例にします。CLAUDE.mdの該当箇所を削り、同じ内容をSkillとして書き直します。

mkdir -p .claude/skills/pr-review

.claude/skills/pr-review/SKILL.md に、CLAUDE.mdへ書いていた手順本体を移します。

---
description: PRレビューの手順。ユーザーがPRのレビューを頼んだとき、レビューコメントの分類方法を聞かれたときに使う。
---
 
## レビュー手順
 
1. 差分を `git diff origin/main...HEAD` で確認する
2. Must / Want / 良い点の3分類でコメントを整理する
3. セキュリティに関わる指摘を最優先で報告する

descriptionにレビューを頼むときの言い回しを具体的に書いておくと、名前を呼ばなくてもClaudeが自動で選びます。要件定義書の作成手順のような別分野の定型手順も、同じ要領でSkill化できます。具体例はClaude CodeとCoworkで要件定義書をSkill化する手順で扱っています。

動作確認は新しいセッションで行います。/compactをかけた場合、プロジェクトルートのCLAUDE.mdはディスクから読み直されて再注入されます。つまり編集後に/compactを挟むだけでも内容は入れ替わります。ただしpathsつきruleやサブディレクトリのCLAUDE.mdは、該当ファイルをClaudeが読むまで再読み込みされません。確実に比べたいときは、新しいセッションを開くのが早道です。

手順そのものが長大な場合は、SKILL.md自体も分割できます。API仕様やサンプル集のような詳細資料は、reference.mdやexamples.mdのような別ファイルに切り出し、SKILL.mdからは参照だけを書きます。Claudeは必要になったときだけそのファイルを読みます。

pr-review/
├── SKILL.md          (必須。概要と各ファイルへの導線)
├── review-checklist.md (詳細なチェック項目、必要時のみ読み込み)
└── scripts/
    └── format-diff.sh  (実行されるだけで読み込まれないスクリプト)

手元のClaude Codeで確認できる入口(v2.1.287で確認)

移行後の挙動を調べるときに使うフラグは、claude --helpにそのまま載っています。インストール済みのv2.1.287で出力を確認しました。

claude --version
claude --help | grep -E "debug-file|disable-slash-commands|bare"

2.1.287 (Claude Code)
  -d, --debug [filter]                  Enable debug mode with optional category
  --debug-file <path>                   Write debug logs to a specific file path
  --disable-slash-commands              Disable all skills
  --bare                                Minimal mode: skip hooks (those defined

--disable-slash-commandsはヘルプ上「Disable all skills」と説明されています。Skillを無効にしたセッションと通常のセッションで/contextの表示を見比べれば、Skillの一覧が占める分の目安を取れます。/contextのSkills行は、予算を適用したあとの一覧のサイズです。

--debug-fileにログの保存先を渡すと、Skillの一覧が予算を超えたときの警告をファイルで確認できます。claude --helpのサブコマンド一覧にはpluginも出ています。SKILL.mdのfrontmatterの検査にも使えます(v2.1.233以降)。

移行しても効果が薄いケースに注意

Skillへ移してもコストが下がらない、あるいは増えるケースが2つあります。

毎セッション必ず呼び出す手順は、移行の効果が薄くなります。Skillの内容は一度呼び出されると会話に残り続け、以後のターンでもcontextを占有します。ほぼ全セッションで使う指示なら、CLAUDE.mdに置いたときと大差ありません。移行が効くのは、使うセッションと使わないセッションが分かれる指示です。

圧縮(auto-compaction)後の扱いにも制約があります。会話が要約されるとき、直近に呼び出した各Skillは先頭5,000トークンまで、複数Skillの合計は25,000トークンまでという予算の中で再添付されます。1セッションで多数のSkillを呼び出していると、古いものから圧縮後に脱落します。

公式の対処は、Skillを呼び出し直すことと、重要な指示をSKILL.mdの先頭近くに置くことです。同じ内容がすでにcontextにあるときの再呼び出しは、全文の二重投入ではなく「読み込み済み」の短い注記になります。引数や動的な出力が変わった場合は、全文が改めて追加されます。

ここまでの条件を満たしていても、「必ず守らせたい規則」はSkillに向きません。Skillの指示はClaudeが従うかどうかに依存するため、毎回確実に実行したい処理はHooksが受け持つ領域です。

移行後にSkillが呼ばれないときの対処

CLAUDE.mdから指示を抜いたのに、期待した場面でSkillが自動的に呼ばれないことがあります。原因は主に3つです。

1. descriptionのキーワードが実際の言い回しとずれている。ユーザーが自然に使う言葉をdescriptionに含めます
2. フロントマターのYAMLが壊れている。壊れた場合はSkill本体は読み込まれ、メタデータだけが空になります。/skill-nameでの呼び出しは動きますが、Claudeはdescriptionで照合できません。--debugで起動するとパースエラーを確認できます
3. Skillの数が多く、一覧が文字数予算を超えて説明文が省略されている。予算はモデルのcontext windowの1%が基準で、超えると呼び出し頻度の低いSkillから順にdescriptionが削られます。予算はskillListingBudgetFraction設定(例: 0.02で2%)か環境変数SLASH_COMMAND_TOOL_CHAR_BUDGETで引き上げられます。優先度の低いSkillはskillOverridesで"name-only"にすると、名前だけの掲載にして予算を空けられます

明示呼び出し専用にしたいSkillにはdisable-model-invocation: trueを付けると、自動判定の対象から外して/skill-nameでだけ呼び出せます。逆に呼ばれすぎる場合は、このフラグを付けるか、descriptionをより具体的に絞り込みます。

プロジェクトの下位ディレクトリ(packages/web/.claude/skills/など)に置いたSkillは、起動時には読み込まれません。そのディレクトリのファイルをClaudeが読む、または編集した時点で初めて使えるようになります。モノレポで「呼ばれない」と感じたときは、このタイミングも疑う価値があります。

CLAUDE.mdを削るだけでは半分の対策でしかない理由

CLAUDE.mdの分割はcontext削減策の1つに過ぎません。コスト削減の同じ章では、ログファイルの選別をHooksに任せる方法も挙げています。10,000行のログをClaudeに読ませてエラー行を探すより、フックでERRORをgrepし、一致した行だけを返すほうが、数万トークンを数百トークンまで圧縮できます。

CLAUDE.mdとSkillsの使い分けは、常時必要な短い事実と、特定タスクの長い手順を分ける設計判断です。Skillsは「Claudeに読ませる知識・手順」を持たせる仕組みで、Hooksは「Claudeが読む前にデータを機械的に加工する」仕組みです。判断の余地なく決まった処理を挟みたいならHooks、状況に応じてClaudeが参照する手順ならSkillsです。Claude Code Hooks完全ガイドで両者の境界を扱っています。

CLAUDE.mdが長すぎるときは、まず.claude/rules/で種別やサブディレクトリごとに分けます。それでも収まらない多段の手順は、Claude Code Skills完全ガイドに沿ってSkill化します。分割の具体例はCLAUDE.mdの実用パターンにあります。memoryの三層構造はCLAUDE.md・自動メモリ・セッションの役割分担を扱い、長時間セッションでのcontextの積み上がりは長時間セッションでコストが増える理由で扱っています。

よくある質問

Skillsに移した指示はチームで共有できますか

プロジェクトの.claude/skills/配下にコミットすれば、CLAUDE.mdと同じようにバージョン管理を通じてチームに配布されます。個人用に留めたいなら~/.claude/skills/に置きます。こちらはこのマシン上の自分のすべてのプロジェクトで使えますが、Coworkやクラウドのセッションは対象外です。

CLAUDE.mdを完全に空にしてもいいですか

空にしてよいかを断定できる材料は公式にありません。公式が/doctorで削ってよいとしているのは、ディレクトリ構成や依存の一覧のようにコードベースから分かる内容です。ビルドコマンドや、ツールの既定と違う規約のような、読み取れない事実は残す側に分類されています。