Claude CodeのSkills設計：コンテキストを圧迫せずに必要な機能を維持する方法

Skillsがセッションの初期コンテキストに与える影響

Claude Codeにおいて、skillsはエージェントの機能を拡張するための構造化ディレクトリおよびMarkdownドキュメント（主にSKILL.md）です。セッション起動時、エージェントは利用可能なskillsの名前と簡潔な説明文を読み込み、どのようなタスクに対応できるかを把握します。

Skillが消費するコンテキストは、主に以下の3つの要素に分かれます：

1. システムアナウンス（名前とtrigger）： SKILL.mdのfrontmatterにあるnameとdescriptionです。ユーザーのプロンプトを適切なツールにルーティングするため、常にメモリ内に保持されます。
2. メイン指示本文： 詳細な手順、ルール、実装例です。該当するskillが呼び出されたタイミングでのみ読み込まれます。
3. 外部スクリプトと参照資料： scripts/配下の実行ファイルやreferences/配下の仕様書で、CLIコマンドを通じて確定的に実行されます。

よくある設計の誤りは、膨大なAPIドキュメントや長いスタイルガイドをそのままdescriptionやトップレベルのCLAUDE.mdに書き込んでしまうことです。これにより、毎回の会話ターンに不要なトークンが上乗せされます。

BetterTokenなどのプロバイダー経由でAPIを利用する場合、ダッシュボード（Dashboard）上でリクエストごとのinput、output、cache tokensの利用量を視覚的に確認できます。ただし、サーバー側の監視は送信された通信量を記録するものであり、ローカル環境の設定ファイル自体の最適化を代替するものではありません。詳しい接続設定やエンドポイント情報はBetterToken Docsで確認できます。

使用頻度に応じたSkillsの棚卸し

作業環境を整理するために、リポジトリ内およびユーザーのグローバル設定（~/.claude/skills/）にあるすべてのactiveなskillsをリストアップします。

利用頻度に応じて以下のように分類します：

基本的な目安として、10〜15回のセッションで1回程度しか使わない機能は、常駐メモリに置くべきではありません。

基本ルールとオンデマンドリソースの分離

トークン消費を抑えつつ高い再現性を確保するために、各skillの入口をシンプルにし、実際の処理は確定的なスクリプトに委譲します。

1. YAML frontmatterの最適化

descriptionフィールドには、トリガーとなる条件と要点のみを記載します：

---
name: db-migrator
description: >-
  スキーマ変更時にPrismaデータベースのマイグレーションを検証・適用する場合に使用します。
---

ヘッダー内に長いコード例を含めることは避け、詳細なテーブルや定義はreferences/ディレクトリに移動させます。

2. 確定的なスクリプトへの処理委譲

モデルに自然言語の指示から複雑な検証コマンドを推論させるのではなく、実行可能なスクリプトを用意します：

<!-- SKILL.mdの記述例 -->
スキーマの整合性を検証するには、以下のコマンドを実行します：
```bash
python3 scripts/validate_schema.py --strict

これにより、`SKILL.md`のテキスト量を大幅に削減しながら、正確な結果を得ることができます。トークンを節約するためにセキュリティチェッカーや型検証を省略してはいけません。決定論的なチェックは常に厳格に維持する必要があります。

検出テストと実行確認

Skillsを再構築したら、エージェントが必要なタイミングで指示を正しく認識できるかテストします。

ステップ1: 構文と相対パスの確認

すべてのSKILL.mdが有効なYAMLで記述されており、スクリプトのパスが正しいことを確認します：

# skillファイルとスクリプトの存在確認
test -f .claude/skills/db-migrator/SKILL.md && echo "SKILL.md OK"
test -x .claude/skills/db-migrator/scripts/validate_schema.py && echo "Script executable OK"

ステップ2: クリーンなセッションでのトリガー検証

新しいセッションを起動し、skill名を直接指定せずにタスク内容を入力します：

「PrismaスキーマのUserモデルを更新して、マイグレーションの整合性を確認してください。」

エージェントが以下を実行することを確認します：

1. db-migratorのdescriptionから該当タスクを識別する。
2. SKILL.mdの指示本文を読み込む。
3. 用意された検証スクリプトの実行を提案する。

ステップ3: 初期コンテキストの評価

セッション全体の挙動を確認します。この最適化の目的は、単に数値を削減することではなく、作業に必要な対話履歴の容量を確保し、余計なノイズを排除することです。現在の開発サイクルに必要なskillsのみを有効にして運用しましょう。