Case Studies · Parhum Khoshbakht

スキル階層化: 80 以上のスキルをコンテキスト外に保つ 4 バケットモデル

段階的開示は、80 のスキルが 3,200 トークンのメタデータを消費することも、ゼロに抑えることも意味します。Statnive リポジトリのすべてのスキルをどのように always-on、auto-invocable、manual-only、fork に分類しているか、そしてバケット選定に使う 1 つの質問テストをご紹介します。

なぜスキルが多くてもコンテキストが少なくなる必要はないのか

Statnive の Claude Code セットアップは、プロダクトマネジメント、バックエンドのスキャフォールド、QA、セキュリティ監査、WordPress 固有のパターン、リリースパッケージングなどを扱う 80 以上のスキルを読み込みます。私たちが基盤としているフレームワーク (jaan.to) は 141 件を出荷します。素朴な読み: スキルが多い、コンテキストオーバーヘッドが多い、実作業の余地が少ない。

実際の数学はもっと興味深いものです。80 のスキルは、3,200 トークンの恒久的なメタデータを消費することも、ゼロにすることもあります。それぞれの設定次第です。違いは、Claude Code のスキルシステムが定義する 4 バケットの階層化モデルと、適切なバケットを選ぶための 1 つの質問テストです。

本記事は、4 つのバケットすべてを Statnive の実際のスキル分布、判断に使うテスト、私たちが正しく行えるまでに 3 度間違えたことと共に紹介します。

段階的開示: 下にあるメカニズム

階層化モデルが意味を成す前に、読み込みメカニズムを理解する必要があります。Claude Code はスキルに対して3 層の段階的開示を使います。

層読み込まれるものいつコスト
1 — メタデータYAML フロントマターの name + description起動時に常にスキルあたり 〜30〜50 トークン
2 — 本体完全な SKILL.md の内容スキルが呼び出されたときAnthropic の推奨は ≤ 500 行 / 〜5K トークン
3 — 同梱リソース参照されるスクリプト、テンプレート、参考資料アクセス時のみベースラインコストはゼロ

これが階層化モデルが活用するレバーです。メタデータ層は常にコンテキスト内にある唯一のものです。それ以外はオンデマンドです。

141 スキルのフレームワークでは、メタデータだけで 4,200〜14,100 トークンの恒久的なオーバーヘッドとなり、スキル数に対して線形に増加します。説明が冗長ならさらに大きく、特定のスキルにメタデータレジストリ全体をスキップするよう指示すれば小さく — またはゼロに — なります。

文書化されたバグ (Claude Code GitHub issue #14882) は、一部のプラグインスキルが起動時にフロントマターだけでなく本体全体を消費する可能性があると報告しています。私たちは自分たちの /context 出力でこれを監視します。スキルメタデータの行が、auto-invocable スキル数 × 〜50 トークンよりはるかに高い数値を示すなら、これに当たっています。

4 つのバケット

Statnive リポジトリのすべてのスキルは 4 つのバケットのいずれかに収まります。それぞれを定義するフロントマターフィールド:

バケット 1 — Always-On (デフォルトのフロントマター)

---
name: simplify
description: Review changed code for reuse, quality, efficiency. Auto-fixes issues.
---

これらは、モデルが自動でルーティングすべきコアワークフロースキルです。標準のフロントマター — 特別なフラグはありません。メタデータは起動時に読み込まれ、本体は呼び出し時に読み込まれます。

Statnive の例: simplify、statnive-release、statnive-release-zip。これらはほとんどのリリース関連作業で発火します。

スキルあたりのコスト: メタデータ 〜40 トークンが恒久的にコンテキスト内にあります。

バケット 2 — Auto-Invocable (デフォルトのフロントマター、簡潔な説明)

Claude Code から見れば Always-On と同じ設定です。区別は編集上のもので、これらはトリガーキーワードがマッチするときだけ発火するドメインスキルです。規律は、説明をトリガー指向で短く保つことにあります。

---
name: wp-rest-api
description: Use when building REST endpoints in WordPress plugins.
---

悪い説明 (動作はするが、コストが高い):

description: A comprehensive skill for working with the WordPress REST API,
  including endpoint registration, controller patterns, schema validation,
  authentication, response shaping, and CPT/taxonomy exposure...

良い説明 (上): 13 トークン。悪い説明: 38 トークン。60 以上の auto-invocable スキル全体で、差は概ね 1,500 トークンの恒久的なメタデータ節約です。

Statnive の例: wp-rest-api、wp-plugin-development、wp-performance、react-best-practices、wp-block-development、すべての jaan-to:* プランニングスキル。

スキルあたりのコスト: メタデータ 〜30〜50 トークンが恒久的にコンテキスト内にあります。

バケット 3 — Manual-Only (disable-model-invocation: true)

---
name: statnive-emergency-rollback
description: Emergency-only rollback procedure for a botched deploy.
disable-model-invocation: true
---

スキルは存在し、スラッシュコマンドは動作します (/statnive-emergency-rollback) が、メタデータが <available_skills> レジストリに入ることはありません。ユーザーが明示的に呼び出さない限り、Claude はその存在を知りません。

スキルあたりのコスト: 0 トークン。 これが魔法のバケットです。

いつ使うか: まれなワークフロー、破壊的な操作、モデルが自動でルーティングしてほしくないものすべて。スキルを manual-only にすることでワークフローが完了できなくなるなら、代わりにバケット 1 か 2 に属します。

Statnive の例: 緊急ロールバック、手動データベース手術、1 回限りのマイグレーションスクリプト、「念のため」存在するが日和見的に発火すべきでないものすべて。

私たちは概ね半分のスキルを disable-model-invocation: true とマークしています。80 以上のスキル全体で、これは 〜1,800 トークンのベースラインメタデータ回収です。さらに、残りの auto-invocable スキルのルーティング品質も実際に向上しました。Claude が似た選択肢の間で迷うことがなくなったためです。

バケット 4 — Fork / Subagent (context: fork)

---
name: simplify
description: Review changed code for reuse, quality, efficiency. Auto-fixes issues.
context: fork
---

Fork モードはスキルを独自の会話履歴と独自の 200K トークンウィンドウを持つ分離されたサブエージェントコンテキストで実行します。作業出力はメインのコンテキストウィンドウから外に出ます。サマリーだけが返されます。

コードレビュー、セキュリティ監査、マルチステップ研究のような自己完結ワークフローには、これは変革的です。Anthropic は、サブエージェントが大量の読み取りと処理を行った複雑なタスクで、内部作業 10,000 トークン以上から 〜500〜1,000 トークンを返すことを文書化しており、概ね 37% のメインコンテキスト削減になります。

Statnive の例: simplify (3 つの並列レビューエージェント、サマリーを返す)、jaan-to:backend-pr-review、jaan-to:sec-audit-remediate、jaan-to:detect-dev。多数のファイルを読み、結論を返すものすべて。

スキルあたりのコスト: メタデータ 〜40 トークン、ただし作業自体は分離環境で発生します。

1 つの質問テスト

4 つのバケットは 4 つの判断のように聞こえます。実際は 1 つです。メインの会話はスキルの中間作業を見る必要があるか?

答えバケット
はい — メインセッションが編集を続けるコードをスキルが書くAlways-on または Auto-invocable
いいえ — スキルが結論、サマリー、レポートを返すFork / subagent
たぶん — ただし自動発火はすべきでない (まれ、破壊的、変わったもの)Manual-only

「いいえ」なら、context: fork を設定してください。メインコンテキストは清潔に保たれ、メインセッションが Sonnet または Opus を使う一方で、サブエージェントの読み込み重視の作業に Haiku 4.5 ($1/$5 per MTok) を使えます。これはコンテキストの勝利の上に 3 倍のコスト勝利です。

「はい」なら、バケット 1 か 2 に入ります。Always-On と Auto-Invocable の選択は編集上のものです。Claude が自然言語の手がかりからこれをどれだけ自信を持ってトリガーできるか? 強く曖昧でないトリガーは Auto-Invocable に。モデルがほとんどのセッションで考慮すべきワークフローは Always-On に。

スキルが存在しても自動発火すべきでないなら、Manual-Only にマークしてメタデータコストを回収します。

Statnive の実際のスキル分布

〜85 スキル全体での当社の現在の内訳:

バケット数総メタデータコスト備考
Always-On8〜320 トークンリリース、simplify、スプリントプランニング、PR レビュー
Auto-invocable38〜1,520 トークン強いトリガーキーワードを持つドメインスキル
Manual-only320 トークンスラッシュコマンド専用
Fork / subagent7〜280 トークンレビュー、監査、ディテクト
総メタデータコスト85〜2,120 トークンコンテキストの約 1%

階層化なし — 85 件すべてがデフォルトの場合 — では、概ね 3,400 トークンの恒久的なメタデータを支払うことになります。32 件の manual-only スキルだけで 〜1,280 トークンが節約されます。単独では小さく見えますが、CLAUDE.md の削減と MCP Tool Search と重ねると効いてきます。

本体の上限: なぜ 500 行が正しい数字なのか

メタデータ側は恒久的なオーバーヘッドです。本体側は呼び出しごとのオーバーヘッドで、同じく制御が重要です。

Anthropic は各 SKILL.md を 500 行 (〜5K トークン) 未満に保つことを推奨しています。積極的な最適化に関する研究はこれをスキル本体あたりのハードキャップ 600 行まで押し進め、それを超えるものは参照抽出を要求します。テンプレート、長いチェックリスト、マルチスタックの比較、アンチパターンカタログを SKILL.md から取り出し、明確なポインタ経由で参照される別ファイルに置きます。

パターンはこう見えます。

.claude/skills/wp-plugin-development/
├── SKILL.md                          # 380 lines — execution core only
└── references/
    ├── activation-deactivation-patterns.md   # Loaded only when needed
    ├── settings-api-patterns.md
    ├── nonce-and-capability-checklist.md
    └── release-packaging-checklist.md

実行コアはコンパクトかつ決定的に保たれます。参照はオンデマンドで読み込まれ、アクセスされるまでトークンコストはゼロです。私たちは最も重い 3 つのスキルをこの方法で再構築し、典型的な呼び出し予算から 〜12,000 トークンを削減しました。

利用価値のある他の本体制御フィールド:

allowed-tools: ["Read", "Grep", "Glob"]

これはスキルがアクセスできるツールを制限し、トークンオーバーヘッドと実行表面領域の両方を削減します。コードを読むだけのスキルは Write、Bash、MCP ツールアクセスを持つべきではありません。ツールセットを狭めることでスキル発火時に注入されるスキーマが狭まり、偶発的な振る舞いのクラス全体が取り除かれます。

最初の 3 回で間違えたこと

正直な注意点、シリーズの他の部分と同じパターンです。

  1. 冗長な説明から始めた。 当社の最初の波のスキルは、人間の読み手向けに最適化された 60 トークン以上の説明を持っていました。動作はしましたが、必要量の 2 倍のコストがかかっていました。トリミング 1 周目で auto-invocable バケット全体で 〜1,400 トークンのメタデータが削減されました。
  2. 似たことをするスキルが 3 つあった。 Auto-invocable バケットに重複するトリガーで pm-roadmap-add、pm-roadmap-update、pm-sprint-plan がありました。ルーティングがコイントス的になりました。統合してトリガーを明確にしました。ルーティング精度が上がり、メタデータコストが下がりました。
  3. 重いスキルが fork モードを使っていなかった。 simplify は元々インラインで動いていました。30 以上のファイルを読み、3 つのレビューパスを実行し、2,000 トークンのレポートを返していました。その内部作業のすべてがメインコンテキストを汚していました。context: fork に切り替えたことで、リリースセッションあたりの典型的なメインコンテキスト使用量を 〜9,000 トークン削減しました。

計測ステップ

シリーズの他の部分と同じです。/context が診断ツールです。スキル階層化のために見る行は、スキルメタデータのトークン数を表示する行です。当社が使う目標値:

ソース目標ハードキャップ
スキルメタデータ≤ 2,500 トークン5,000
Auto-invocable スキル数≤ 60—
任意の単一 SKILL.md 本体≤ 500 行 / 〜5K トークン600 行 / 〜8K トークン

スキルメタデータの行が 5K トークンを大きく超え、スキル数が 100 未満なら、おそらく冗長な説明 (バケット 2 の問題) か、先に述べた読み込みバグ (バケット 1 の問題) のいずれかです。

これが Statnive の他の部分にどう繋がるか

私たちは すべてのコミットで 141 件の PHP ユニットテストをテストします。リリースは、どのバージョンも出荷前に 31 件のコンプライアンスチェックを通過します。これらすべてをオーケストレートするスキル — statnive-release、simplify、wp-plugin-development、QA ジェネレーター — は概ね 2,100 トークンの恒久的なメタデータに収まります。作業は発生し、コンテキストは清潔に保たれ、チームは小さく保たれます。

4 バケットモデルは学術的な演習ではありません。これが、5 人のチームを背後に持たずに 5KB トラッカー予算下で WordPress アナリティクスプラグインを出荷できる理由です。

Statnive を試す

/help より頻繁に /context を実行するチームによって構築された、プライバシー重視の WordPress アナリティクス。WordPress.org から Statnive を無料インストール — データはサーバーに留まり、当社のスキルライブラリはトークン予算内に十分収まります。

Statnive を無料で入手