SKILL軽量化

[mapserver2007]

Skills 冗長性調査報告

結論: スキル統合・手順削除より、Progressive Disclosure の徹底（SKILL.md の常時ロード量削減）が本命。意図的な冗長（Hard Stop / 不変条件 / Mode B 再注入）は性能劣化防止のため削減禁止。推定削減余地は invoke 時で約 350〜400 行相当、うち安全に取れるのは約 200〜250 行。

---

1. 調査範囲と前提

項目	内容
対象	.cursor/skills/ 配下 14 スキル
目的	冗長箇所の特定と、性能劣化なしで短縮できる候補の整理
非対象	実装変更、スキル統合の実行
SoT 制約	生成物の直接編集は禁止。最適化は manifest.yaml / templates/ 経由（AGENTS.md > Boundaries）

評価の性能モデルは Cursor create-skill ガイドラインに準拠:

1. description — 発見用でほぼ毎ターン消費（discovery コスト）
2. SKILL.md — スキル起動時に全文ロード（invoke コスト）
3. references/ — 必要時のみ Read（Progressive Disclosure）

公式指針: SKILL.md は 500 行未満、詳細は references へ。

---

2. 規模インベントリ（runtime）

スキル	SKILL.md	refs	Progressive Disclosure	disable-model-invocation	起動頻度感
agent-code-review	287 (~7k tok)	10 / 2066行	あり（ただし SKILL 自体が厚い）	否	高
agentic-workflow-foundation	458 (~12k tok)	2	弱（本文に巨大フェーズ記述）	はい	低（基盤生成時）
maintenance-docs-workflow	202	0	なし	否	中
agent-github-issue	209	2	部分的	否	中
agent-github-pr	205	1	部分的	否	中
workflow-orchestrator	172	1	あり（step docs 委譲）	否	高
maintenance-gotchas-workflow	166	0	なし	否	中
requirement-analysis	119	3	良好	はい	高（内部）
session-planning	89	0	不要（短文）	はい	Hook/手動
cross-repository-knowledge-link	88	3	良好	否	暗黙・中
agentic-workflow-engine	86	0	n/a（scripts 中心）	はい	低
session-handover	79	0	良好（scripts 分離）	はい	Hook
deep-thinking	65	4	優良	はい	条件付き
agent-kaizen	63	5	優良	否	低〜中

参照実装として優れているのは agent-kaizen / deep-thinking / requirement-analysis（薄い SKILL + 厚い references）。

---

3. 冗長パターン分類

A. 構造的ツイン（同一骨格のコピペ）

maintenance-docs-workflow と maintenance-gotchas-workflow がほぼ同型:

• Phase 1〜6（スキャン → 判定 → 実行 → 検証 → PR → レビュー）
• 責務境界テーブル / 安全制約 / Context Budget / 再開 Phase 表

Context Budget 節は Jaccard ≈ 0.50 の行重複。ドメイン固有部（判定基準・検証マトリクス）以外は共通化余地あり。

注意: スキル統合は非推奨。トリガー・入力キュー・昇華処理が異なり、誤発火リスクが増える。

B. Progressive Disclosure 未達（全部 SKILL に載っている）

スキル	問題
maintenance-docs / gotchas	references/ が無い。判定表・再開表まで常時ロード
agent-github-pr	bash レシピが SKILL の約 28%。pr-commands.md と役割が重なる
agent-github-issue	承認フロー・mktemp 手順が SKILL 本体に長い
agentic-workflow-foundation	458 行・フェンス約 74%。500 行上限に近い

C. 意図的冗長（削減すると性能＝品質が劣化する）

agent-code-review の以下は 設計上の二重化:

要素	目的
Step Gate Matrix	踏み外し防止の早見表
不変条件（暗記必須）	refs 未読でも守る契約
Hard Stop（refs 全文 Read）	判定・投稿前の強制再注入
mode-b-reminder.md	Lost in the middle 対策

ここを「重複だから消す」と、レビュー誤判定・未承認 reply 投稿などの機能性能劣化に直結する。トークン削減対象外。

D. 上位ドキュメントとの再掲

複数スキルが AGENTS.md > Context Budget Protocol を再記述。SoT は既に docs/CONTEXT_BUDGET.md / AGENTS.md。3 行ポインタで足りる。

workflow-orchestrator Step ① は requirement-analysis の要約再掲（約 20 行）。Matrix + リンクのみでも制御は成立する。

E. discovery コスト（description）

毎ターン載る description はおおむね 80〜150 tok。異常に長いのは agentic-workflow-foundation（~220 tok）だが disable-model-invocation: true で誤発火は抑制済み。優先度は低い。

---

4. 最適化候補（優先度 × 劣化リスク）

P0 — 推奨（低リスク・中〜高効果）

#	対象	施策	効果目安	劣化リスク
1	maintenance-docs / gotchas	共通節（Context Budget・安全制約の共通項・再開表骨格）を references/shared-delivery.md 相当へ。SKILL は Phase 概要 + ドメイン表 + リンク	−30〜50 行×2	低（契約文は残す）
2	同上	「反映/修復判定基準」「検証マトリクス」を references/ へ。SKILL は入口条件と Hard Rule のみ	−50〜70 行×合計	低〜中（判定表を起動直後に読ませる指示を残す）
3	agent-github-pr / issue	bash・テンプレ本文を references に寄せ、SKILL は Gate Matrix + 分岐判断 + wrapper 呼び出し契約	−60〜70 行×2	低（コマンド SoT が refs に既にある）
4	複数スキル	Context Budget 節を「AGENTS.md / CONTEXT_BUDGET.md に従う」3 行化	−20〜30 行合計	極低

P1 — 条件付き推奨（中リスク・高効果）

#	対象	施策	効果目安	劣化リスクと緩和
5	agent-code-review	「レビューレポート」命名規則・段階的作成表（約 52 行）を review-report-format.md へ移し、SKILL は要約 + Hard Rule	−40〜50 行	中。Step 3/4/7 で「refs を読め」を明示維持
6	agent-code-review	各 Step の長文説明を 3〜5 bullet に圧縮。Matrix・不変条件・Hard Stop は残す	−60〜80 行	中〜高。圧縮しすぎると手順踏み外し。Mode B reminder は維持必須
7	workflow-orchestrator	Step ① 本文を requirement-analysis への委譲リンク中心に	−10〜15 行	低。Gate Matrix は残す

P2 — 後回し / 原則触らない

#	対象	理由
8	agentic-workflow-foundation	起動稀・disable 済み。短縮は可だが ROI 低。触るなら Phase 詳細の references 化
9	deep-thinking / agent-kaizen / requirement-analysis / session-*	既に薄い or 適切分割。いじると逆に劣化
10	スキル統合（docs↔gotchas、pr↔issue）	責務境界が明確。統合は誤用・テスト・ゲート契約の破壊リスク大

---

5. 「やってはいけない」削減（性能劣化の定義）

本調査での「性能」はトークン効率だけでなく、手順遵守率・誤投稿防止・判定品質を含む。

禁止施策	理由
Hard Stop / 不変条件の削除・refs 一本化のみ	未読時でも守る契約が消える
mode-b-reminder の廃止	Lost in the middle 再発
judgment / approval / completion の「暗記必須」省略	レビュー品質ゲートの骨組み
maintenance 2 スキルの統合	入力・対象レイヤ・昇華処理が異なる
description から Do NOT use を削る	誤スキル起動が増え、結果としてコンテキスト浪費

---

6. 推奨ロードマップ

推奨案: P0（#1〜#4）を先に実施し、効果計測後に P1（#5→#6→#7）へ。

フェーズ	内容	トレードオフ
Phase A	maintenance twins の references 化 + Context Budget ポインタ化	効果中・リスク低。テンプレ共通化の設計コストあり
Phase B	github-pr / issue のコマンド本文移設	効果中・リスク低。既存 refs と重複整理が必要
Phase C	agent-code-review のレポート節・Step 叙述の圧縮（不変条件は温存）	効果高・リスク中。圧縮後は Mode A/B の回帰チェック必須

変更経路は必ず templates → bin/foundation-gate generate → audit。生成物直編集は Boundaries 違反。

検証（Thorough）:

1. bin/foundation-gate self（または相当 audit）
2. agent-code-review は Mode A/B の手順チェック（Hard Stop 発火確認）
3. maintenance 系は Phase 再開表が欠落していないこと
4. トークン指標: 起動時 Read する SKILL.md 行数の前後比較

---

7. 定量サマリ

指標	値
SKILL.md 合計（14）	約 2,490 行
うち「厚い」上位 5	ACR + foundation + mdocs + issue + pr ≈ 1,361 行（約 55%）
Progressive Disclosure 優良	kaizen / deep-thinking / requirement-analysis
Progressive Disclosure 欠落	maintenance-docs / maintenance-gotchas
安全な削減余地（P0）	おおよそ 200〜250 行（invoke 時）
条件付き削減（P1、品質ゲート維持前提）	さらに 100〜150 行
削減禁止（意図的冗長）	ACR 不変条件・Hard Stop・Mode B reminder

---

8. 次アクション（実装は未着手）

調査のみ完了。実装に進む場合の推奨順:

1. maintenance twins のテンプレート共通化設計（共有 references の置き場を決定）
2. agent-github-pr / issue の SKILL テンプレから bash を refs へ移動
3. agent-code-review は「レポート節 → Step 叙述」の順で段階圧縮（不変条件は触らない）

実装着手の指示があれば、上記 Phase A からテンプレート側で進められます。