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

このTipsでできること

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

公式ドキュメントは、その場限りの手順やコードベースの一部にしか関係しない項目をCLAUDE.mdに書かず、Skillかパス限定のruleに移すよう勧めています。CLAUDE.mdは200行未満に保つのが目安です。

CLAUDE.mdが膨らみやすい理由

CLAUDE.mdへの追記自体は、どれも正当な動機から始まります。公式ドキュメントは追記のタイミングとして次の4つを挙げています。

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

いずれも一度きりの追記としては合理的です。問題は、CLAUDE.mdに書いた内容がその後ずっと毎セッションのcontextに残り続けることです。1年前に対応した1回限りの移行手順や、特定パッケージでしか使わない規約が消えずに残っていれば、無関係な作業のたびにそのぶんのトークンを払い続けます。追記するたびに、その指示が「常時必要」か「特定タスクだけで必要」かを分けて置く発想がないと、CLAUDE.mdは一方的に肥大化します。

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

両者の違いは「いつcontextに乗るか」です。

セッション開始時にはSkillsのdescription一覧も読み込まれますが、これは1行程度の要約です。負担は小さく、手順本体は呼び出されるまでcontextに入りません。

移す指示をどう見分けるか

公式の判断基準は次の4つです。いずれかに当てはまる指示は、CLAUDE.mdからSkillへ移す候補になります。

• 複数ステップの手順(PRレビュー手順、DBマイグレーション手順など)
• コードベースの一部でしか関係しない知識(特定パッケージの規約など)
• 毎回のセッションでは使わず、特定タスクでだけ必要になる知識
• 同じ訂正を2回目に入力した、単発的な訂正

CLAUDE.mdに残すのは、どのタスクでも共通して必要な事実です。ビルドコマンド・テストコマンド・命名規則・プロジェクト構成がこれにあたります。

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

CLAUDE.mdとSkillsの間には、.claude/rules/によるパス限定ルールという中間層があります。大規模プロジェクトでは、この3層で読み込みタイミングを段階的に絞り込めます。

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

また、CLAUDE.mdが毎セッション読み込まれるのは作業ディレクトリより上位にあるものに限ります。サブディレクトリに置いたCLAUDE.mdは、Claudeがそのディレクトリのファイルを実際に読んだときだけオンデマンドで読み込まれます。上の早見表の「毎セッション起動時」は、この上位ファイルの場合の話です。

.claude/rules/配下にapi-design.mdのようなファイルを置き、frontmatterのpathsにglobパターンを書きます。該当パターンに一致するファイルをClaudeが読んだときだけ、そのルールが読み込まれます。

---
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. セキュリティに関わる指摘を最優先で報告する

CLAUDE.mdの側は「PRレビューはpr-reviewスキルに従う」という1行の参照だけを残すか、何も書かずdescriptionだけで自動呼び出しを待ちます。descriptionにレビューを頼むときの言い回しを具体的に書いておくと、明示的に名前を呼ばなくてもClaudeが自動で選びます。

動作確認は新しいセッションで行ってください。CLAUDE.mdはセッション開始時に一度だけ読み込まれ、そのままメモリに保持されます。移行作業中にCLAUDE.mdを編集しても、そのセッションの動作には反映されません。/clearか/compact、あるいは再起動を挟んだ次のセッションから新しい内容が有効になります。

手順そのものが長大な場合は、SKILL.md自体も分割できます。API仕様やサンプル集のような詳細資料は、reference.mdやexamples.mdのような別ファイルに切り出します。SKILL.mdからは「詳しいAPI仕様はreference.mdを参照」のように、参照だけを書きます。Claudeは必要になったときだけそのファイルを読むので、Skillを呼び出した瞬間に詳細資料までまるごとcontextへ乗ることはありません。

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

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

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

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

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

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

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

1. descriptionのキーワードが実際の言い回しとずれている。ユーザーが自然に使う言葉をdescriptionに含めます
2. フロントマターのYAMLが壊れている。パースに失敗するとdescriptionが空になり、Claudeは照合対象を失います。--debugで起動するとパースエラーを確認できます
3. Skillの数が多く、一覧が文字数予算を超えて説明文が省略されている。この一覧はモデルのcontext windowの1%を目安にした予算で管理され、超えた分は呼び出し頻度の低いSkillから順にdescriptionが削られます。/doctorで一覧のコスト見積もりを確認できます

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

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

CLAUDE.mdの分割はcontext削減策の1つに過ぎません。公式ドキュメントは同じ節で、ログファイルの選別をHooksに任せる方法も挙げています。10,000行のログをClaudeに読ませてエラー行を探すより、PreToolUseフックでgrepしてから返すほうが、数万トークンを数百トークンまで圧縮できます。

CLAUDE.mdとSkillsの使い分けは「常時必要な短い事実」と「特定タスクの長い手順」を分ける設計判断です。実行結果を絞り込む問題はHooksの領分で、両者は競合しません。memoryの三層構造はCLAUDE.md・自動メモリ・セッションの役割分担を扱っているので、CLAUDE.mdの設計そのものを見直すときはあわせて確認してください。長時間セッションでcontextがどう積み上がっていくかは長時間セッションでコストが増える理由で扱っています。

よくある質問

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

.claude/skills/配下にコミットすれば、CLAUDE.mdと同じようにバージョン管理を通じてチーム全員に配布されます。個人用に留めたいなら~/.claude/skills/に置くと、自分のすべてのプロジェクトでだけ使えます。

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

いいえ。ビルドコマンドやテストコマンドのような、どのタスクでも参照する共通ルールはCLAUDE.mdに残すのが向いています。空にすると、その情報が必要なたびにClaudeがコードを読んで推測することになり、かえってトークンを消費します。

CLAUDE.mdが長すぎるときは

まず.claude/rules/でファイル種別やサブディレクトリごとにルールを分割できないか検討します。それでも収まらない多段の手順は、Claude Code Skills完全ガイドの手順に沿ってSkill化するのが次の選択肢です。CLAUDE.mdの実用パターンも分割の具体例を扱っています。

HooksとSkillsはどう使い分けますか

役割が違うので競合しません。Skillsは「Claudeに読ませる知識・手順」を持たせる仕組みで、Hooksは「Claudeが読む前にデータを機械的に加工する」仕組みです。ログ出力の選別や特定コマンドの強制停止のように、判断の余地なく決まった処理を挟みたいならHooks、状況に応じてClaudeが参照する手順ならSkillsが向いています。Claude Code Hooks完全ガイドで両者の境界を扱っています。