Claude Code Skills：必要な機能を保ちながらコンテキストを管理する

Claude Codeを使い込むと、専用スクリプト、書式規約、型検査、フレームワークのテンプレートが増えていきます。すべてを常時読み込む指示にすると、最初の依頼より前にコンテキストを消費します。ここではSkillsを棚卸しし、常時必要な規則と必要時だけの手順を分け、モデルが必要なスキルを発見できるか確認します。

起動時に何がコンテキストへ入るのか

通常のセッションでは、on のスキルの名前と description がモデルに渡されます。name-only は名前だけ、user-invocable-only または disable-model-invocation: true は説明をモデルから隠し、off はスキル自体を隠します。SKILL.md の本文は呼び出した後に読み込まれ、同じセッションに残ります。補助ファイルは必要時に読み、スクリプトはツールとして実行します。仕様は公式Skills文書で確認できます。

負荷は、一覧用の名前・説明・トリガー、呼び出し後の本文、必要時に使う参照資料とスクリプトの三つに分けて考えます。巨大なAPI仕様やコード生成規約を description やグローバルの CLAUDE.md に入れると、作業開始前からコンテキストを圧迫します。

自分のBetterToken API Keyで試す場合は、Dashboardでモデル、時刻、ステータス、input・output・cache Tokenを照合できます。実際のAPI呼び出しを確認するための情報であり、どのローカルスキルがコンテキストを使ったかは分かりません。/context とは別に扱い、接続設定はBetterToken Docsで確認してください。

Skillsが増えすぎたら /skill-doctor から始める

一覧を手作業で判断しにくくなったら、ローカルのClaude Codeセッションで /skill-doctor を実行します。スキルのコンテキストコストと呼び出し頻度を示し、読み込まれているのに使われていない項目を見つけられます。対話型レポートは /plugin 管理画面のStatsタブに開きます。組み込みスキルと企業スキルは対象外です。レポートの仕様も確認してください。

1. 普段使うプロジェクトを選び、一覧を典型的な作業と照合します。呼び出し履歴がないことは不要の証明ではありません。復旧手順は数か月に一度しか使わないこともあります。
2. 低頻度の個人用・プロジェクト用スキルは、/skills で user-invocable-only（表示は user-only）にします。その環境で不要になったものは off を選べます。プラグインのスキルは /plugin で管理します。
3. 新しいセッションで /context を比較し、通常の作業を一つと、残した低頻度スキルの明示呼び出しを試します。必要な作業を実行できることが、負荷削減の前提です。

このコマンドはv2.1.261のリリースノートに記載されていますが、現在の文書は最低バージョンをv2.1.252としています。claude --version で確認してください。利用可否はfeature flagsの取得にも依存します。Remote Controlではレポートを利用できないため、セッションが動いているマシンの端末で実行します。コマンドがなければ、次の手動棚卸しを続けます。

用途と使用頻度で棚卸しする

プロジェクトの .claude/skills/ と個人用の ~/.claude/skills/ を一覧にします。下位ディレクトリのスキルは、その配下のファイルを初めて読んだり変更した後に使えるようになるため、起動時にすべて見えるとは限りません。プラグインのスキルは名前空間を持ち、skillOverrides の管理対象外です。同期したスキルの発見方法もローカル、Cowork、cloudで異なります。実際に使う各環境でファイル一覧と /skills を照合してください。

頻度	作業例	配置
毎日	コード規約、テスト、git status	短い CLAUDE.md 規則か基本スキル
作業に応じて	DB移行、OpenAPI生成、リリース確認	用途の狭い description を持つスキル
低頻度・設計作業	初回の安全監査、新サービスの展開	user-onlyのスキル、明示コマンド、scripts

安全・復旧・リリースの手順は、低頻度でも明示的に呼び出せる状態にします。無効化するかどうかは、実際の用途を確認してから判断します。

常時読み込む必要のない規則をどこへ置くか

生成ドキュメントをソースとジェネレーターから更新する作業なら、次のように役割を分けられます。

必要なこと	仕組み	確認すること
毎回更新方法を思い出させる	短い CLAUDE.md 規則	新しいセッションで読まれたか
更新時だけ手順を実行する	専用スキル	明示呼び出しでソースと生成コマンドを見つけるか
実行前に特定の書き込みを拒否する	PreToolUse Hook	対象ツールが拒否され、ファイルが変わらないか
結果を独立して確認する	必要なツールを持つSubagent	検証結果があり、権限が作業範囲内か
外部システムのデータを得る	MCP接続	必要なサーバーで許可されたリクエストを一つ実行できるか

CLAUDE.md とスキルはモデルへの指示です。「generatedを編集しない」という文だけでは書き込みの拒否を証明できません。Hookのイベント、matcher、実際の拒否を確認してください。Write を拒否してもBash経由の書き込みは制限されません。Subagentも別コンテキストだからといって自動的にread-onlyにはなりません。仕組みの概要とHooksリファレンスに違いが説明されています。

同じ手順を五か所へ複製せず、CLAUDE.md には短い規則とスキルへの参照を残します。具体例はCLAUDE.mdの規則、Stop Hookによる完了確認、MCPとコマンドの選択を参照してください。Stop Hookは作業の終了を確認するもので、書き込み前の PreToolUse の代わりにはなりません。

短い入口と補助リソースに分ける

1. YAML frontmatterを短くする

description には用途と明確なトリガー条件を書きます。次の設定例では、Prismaのスキーマ変更時に移行を検査・適用する用途を示しています。

---
name: db-migrator
description: >-
  Prismaのスキーマ変更時にマイグレーションを検証・適用するために使用する。
---

説明欄へ長いコード例を並べず、詳しい表や例は references/ に移します。

2. 繰り返す検査をスクリプトへ移す

長い自然言語の指示から毎回複雑な解析コマンドを作らせる代わりに、skillの scripts/ にshellやPythonの処理を置きます。本文はその実行経路と判断基準を示します。

<!-- SKILL.md 内 -->
スキーマの整合性を検査するには、次を実行する：
```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/validate_schema.py" --strict
```

同じ入力で呼び出し、スクリプト自体もテストしてあれば、検査を再現しやすくなります。Tokenを節約するために安全検査、リンター、型検査を無効にしないでください。

発見と呼び出しを四段階で検証する

1. 四つの検査を分ける

test -f はYAMLの検証ではありません。SKILL.md の存在、空でない description を含むfrontmatterのYAML解析、skillディレクトリを基準にした references/・examples/・scripts/ の参照先、安全な入力でのスクリプトの終了コードを別々に確認します。python3 で実行するPythonファイルに実行ビットは必須ではありません。

2. 表示と明示呼び出しを確認する

新しいセッションで /skills を開き、名前、出所、呼び出しモードを確認します。その後、安全な試験作業で /db-migrator を明示的に呼びます。これで、発見の失敗と指示そのものの問題を分けられます。

3. 自動トリガーを試す

もう一つ新しいセッションを開き、スキル名を言わずに「データベースのユーザーモデルを更新して移行を検査したい」と依頼します。モデルが description から用途を判断し、db-migrator の本文を読み、用意した検査スクリプトの実行を提案することを確認します。

4. 一覧と起動時のコンテキストを測る

未使用スキルの発見には前述の /skill-doctor を使います。/doctor で一覧のコストと大きな寄与要因を確認し、/context のSkills行を記録します。説明の短縮やuser-onlyへの変更を一つだけ行い、新しいセッションで同じ比較をします。

Tokenだけでなく、該当する依頼では呼ばれ、該当しない依頼では呼ばれず、作業の検査にも通るか確認してください。always-on、auto-triggered、user-only、name-only、off を区別し、安全・復旧スキルは使用頻度だけを理由に削除しません。