Skill の主体をスクリプトへ移し、LLM は呼び出し・結果の解釈・判断だけを持つ（全 Skill の改善の親）

[takemi-ohama]

何を変えるか

Skill の主体を、スクリプトと決定論的なツールにする。 LLM（CLI / エージェント）は、スクリプトを呼び、結果を読み、スクリプトでは決められない判断だけをする。

例: /ndf:merged 812 を打つと、今は LLM が merged/SKILL.md（25,026B）を読み、起点の決定・ブランチとworktreeの削除・無視されたファイルの退避・完了報告の表を 1 手ずつ実行する。変更後は次のようになる。

1. LLM が merged-steps.py cleanup 812 を打つ
2. スクリプトが後片付けを進め、{"status":"gate","stopped":[{"name":"feature/x","reason":"未マージのコミット 2 件"}],"presentation_path":"..."} を返す
3. LLM は止まった 1 件だけを利用者に示して同意を取る

SKILL.md は約 7KB になる。LLM が読むのはこの本文と結果の JSON だけである。

なぜ

#827 の実測（2026-09-20 以降、5 リポジトリ、サブエージェント 156 件）で、次のことが分かっている。

• Skill の本文がサブエージェントの持ち越し量の 16% を占める。 156 件のうち 102 件が Skill を読み、合計 371 回・約 230 万トークンだった（progress-tracking 1 回約 7.6k、fix 約 7.2k、cross-review 約 9.8k）
• 待ちのポーリングが全体の費用の 16% を占める（30 日間では 19%）
• 本文の大半は「決まった手順」である。今回の調査では、17 の主要 Skill で本文の 4〜7 割が、gh / git の呼び出し列・雛形の穴埋め・書式の検査・状態の判定・集計だった

決まった手順を LLM が本文を読みながら実行すると、手順が長いほど本文の読み込みと往復が増える。スクリプトにすれば、本文は呼び出し 1 行と判断の基準だけになり、往復もスクリプトの中で済む。

参考: Jev 時代の AI エージェント・ハーネス設計。「確実に決められる処理はコード、小さな判断は高速な判断モデル、複雑な推論は大規模 LLM」に分け、判断を is_complete() / needs_human() のような小さな部品にし、確信度・しきい値・ポリシーで実行可否を決める。

判断の 3 段

#841 の分け方を全 Skill に当てはめる。

段	担当	任せるもの	例
1	スクリプト	取得・生成・検査・状態の判定・待ち・集計・雛形の穴埋め	起点ブランチの解決、未解決スレッドの取得、証跡の記録、文書の lint
2	分類の判断（最小構成の claude -p、#841 で Jev）	決まった選択肢から選ぶ	fix の指摘の振り分け、lint のヒットを直すか残すか、テストの失敗が既存のものか
3	LLM	差分やコードを読んで考える	修正、設計、文章、レビュー

各 Skill の issue は、段 2 の判断点を列挙する。その一覧は #841 の「判断点の一覧」へ渡す。

対象と構成

• 対象: plugins/ndf/skills/ の全 Skill（development-workflow を除く）、plugins/ndf/agents/、playwright-kit、mcp-redash
• development-workflow は対象外。 development-workflow: トークン消費の実測と削減（supervisor をスクリプトで駆動し、判断は最小構成の claude -p に任せる） #827 の子 issue と 設計: 待つ間の問い合わせを hook で止め、conductor の会話を工程の切れ目で切る（#829 #830） #843（待つ間の繰り返し問い合わせ（sleep ループ・出力ファイルの読み直し）をやめ、完了通知か Monitor で待つ #829 / conductor の会話を工程の切れ目で切ることを hook で強制する #830 の設計）で進めている。この親の子 issue は、下の「development-workflow との接点」を守る

子 issue

基盤（共通の部品と規約）

issue	内容	優先度	状態
#846	基盤: スクリプトの結果 JSON・終了コード・承認ゲートの提示を共通の契約にする	高	閉じた
#847	基盤: スクリプトの置き場所（$SCRIPTS / SKILL_DIR）の解決を 1 本のコマンドにする	高	閉じた
#848	基盤: 起点ブランチと本番チャネルの解決を呼び出し口 1 本で出す	高	開いている
#849	基盤: PR / issue の取得と本文の節の差し替えを共通の部品にする（pr-info・unresolved-threads・body-section）	高	閉じた
#850	基盤: 配布の記録とリリース後テストのブロックを読み書きする部品（dist-record・record-pr）	中	開いている
#851	基盤: 起票の部品（起票先の解決・重複の検索・骨格の検査つき起票・由来の付与）	中	開いている
#852	基盤: 外部 CLI の起動・上限つきの待ち・回収を 1 本のスクリプトにする（external-ai.sh run）	高	閉じた
#853	基盤: 検証の証跡を積む evidence.py と、テストの実行方法を返す detect-test-runner	高	開いている
#854	基盤: Markdown の文書検査を配布される 1 本のツールにする（doc-check）	高	開いている
#855	基盤: Skill の書き方の規約に「スクリプト主体」を足し、検査と本文の量の計測を入れる	中	開いている

Skill ごとの改善

issue	内容	優先度	状態
#856	progress-tracking: 「ミッションを閉じる」をスクリプト 1 本（bundle-close）にする	高	閉じた
#857	merged: 後片付けの手順 1〜8 をスクリプトにし、LLM は止まった対象の同意だけを扱う	高	閉じた
#858	pr: ブランチ確認・起点判定・push・PR 作成・完了報告をスクリプトにし、LLM は文面と同意の判断だけを持つ	高	閉じた
#859	fix: PR の文脈の収集と戻り値の集計をスクリプトにし、LLM は指摘の振り分けと修正だけを持つ	高	閉じた
#860	pr-review: 差分の収集・既存コメントの取得・投稿・外部 AI への委譲をスクリプトにする	中	開いている
#861	pr-tests: Test plan の抽出・結果の記録・チェックの反映をスクリプトにする	低	開いている
#862	release / release-verification: 差分の判定・記録のブロック・公開の確認をスクリプトにし、照会の sleep ループをなくす	中	閉じた
#863	retrospective: 記録先の決定・PR の特定・由来の検索・投稿をスクリプトにする	中	開いている
#864	issue-upkeep: 候補の収集と反映（照合・待ち行列つき）をスクリプトにし、LLM は判定だけを持つ	中	閉じた
#865	out-of-scope: 起票の決まった部分を issue-file の呼び出しにする	中	開いている
#866	issue-plan-strategy: multi-PR の足場づくりと実行計画の状態遷移をスクリプトにする	中	開いている
#867	worktree: worktreeの作成と「メインディレクトリに残った変更を移す」をスクリプトのサブコマンドにする	低	開いている
#868	cherry-pick-pr / deploy: 手順をスクリプトにする（deploy はほぼ全部）	低	開いている
#869	external-ai / corder / qa-security-scan: 外部 CLI の起動と待ちを external-ai.sh run の 1 行にする	高	閉じた
#870	cross-review / cross-refactoring: drive の止まる理由（pause）の形を揃え、ライブラリへの残りの移行を終える（#560 の続き）	高	閉じた
#871	quality-gates / tdd-cycle / refactoring: 証跡と検証を evidence.py の呼び出しにする	高	開いている
#872	implementation-plan / plan-to-spec / requirements-design / design: 雛形と構造の検査を doc-check の呼び出しにする	中	閉じた
#873	markdown-writing / document-restructuring / document-sources / notion-writing / document-drafting: セルフチェックと測定を doc-check の呼び出しにする	高	開いている
#874	layout-review / document-systems: 描画と測定、宣言の読み出しとシステムの判別をスクリプトにする	中	開いている
#875	playwright-kit: 計画書の雛形・シナリオの静的検査・出力の JSON 化と、Drive 連携の記述の食い違いを直す	中	閉じた
#876	mcp-redash: add / list / remove / status の 4 Skill を 1 本にまとめ、ディレクトリ解決の前置きを 1 回にする	低	閉じた
#877	知識系 Skill とエージェント定義の整理（重複・古い節・存在しない参照・判定の誤り）	低	開いている

調査で見つけた不具合

issue	内容	優先度	状態
#878	deploy: PR 本文の heredoc が引用付き（<<'EOF'）で、$FEATURE_BRANCH と $ARGUMENTS が展開されずに載る	中	閉じた
#879	google-drive: --upload が常に「リンクを知る全員が閲覧可」を付け、--id が無いと終了コード 0 で終わる	高	閉じた

development-workflow との接点

子 issue はすべて次の 9 項目を守る。

1. 工程 Skill 13 個の名前を変えない。統合もしない。 設計: 待つ間の問い合わせを hook で止め、conductor の会話を工程の切れ目で切る（#829 #830） #843 の token-guard-stages.txt が名前で判定するためである。13 個は implementation-plan / document-drafting / cross-refactoring / cross-review / pr-review / quality-gates / plan-to-spec / merged / layout-review / release-verification / retrospective / development-workflow / issue-plan-strategy。変える場合は一覧と同じ PR で変える
2. 工程名の一覧をスクリプトに持たせない。 正本は工程表と progress-record.sh である。後片付けまでの進捗記録は「1 実行に 1 件」のまま
3. worker は進行を記録しない（agent-layers.md の規則 2）。記録するスクリプト（mission-close.py / merged-steps.py など）は supervisor か conductor が呼ぶ
4. 結果 JSON の status（ok / gate / stopped）は、## 作業の報告 の「結果: 完了 / 承認ゲート / 止まった」に写せる形にする（基盤: スクリプトの結果 JSON・終了コード・承認関門の提示を共通の契約にする #846）
5. 承認ゲートは approval-request.md の 2 層の形で示す。 読めなかったこと（終了コード 2）を「一致」「0 件」と読ませない
6. fix の戻り値 JSON は cross-review の state.py merge-fix が読む契約である。 形を変えない
7. 待ちはスクリプトの中で、上限つきで行う（development-workflow/references/waiting.md）。フォアグラウンドの sleep ループを本文に残さない。PR 待ちの問い合わせと長い conductor の工程の起動を hook で止める（#829 #830） #844（待つ間の繰り返し問い合わせ（sleep ループ・出力ファイルの読み直し）をやめ、完了通知か Monitor で待つ #829 の実装）が 4 文書に足す「run_in_background で実行する」の案内は、基盤: 外部 CLI の起動・上限つきの待ち・回収を 1 本のスクリプトにする（external-ai.sh run） #852 / external-ai / corder / qa-security-scan: 外部 CLI の起動と待ちを external-ai.sh run の 1 行にする #869 でループごとスクリプトへ移すときに置き換える。agents/corder.md は 待ちの問い合わせと長い conductor の工程の起動を hook で止める（#829 #830） #844 の対象外で hook の拒否を受けてからバックグラウンドへ回るので、external-ai / corder / qa-security-scan: 外部 CLI の起動と待ちを external-ai.sh run の 1 行にする #869 で最初に置き換える
8. $SCRIPTS の解決の正本は development-workflow/references/scripts-lookup.md である（基盤: スクリプトの置き場所（$SCRIPTS / SKILL_DIR）の解決を 1 本のコマンドにする #847）
9. worker の起動器は /goal の worker をサブエージェントから CLI へ変え、ランタイム × モデルを輪番で回し、統計が溜まったら作業に適した組を自動で選ぶ #760 と同じ層（lib/launch-cli.sh / monitor.py）を使う。 サブエージェントに Skill 本文を丸ごと読ませず、持ち場で要る手順だけを渡す #828 の worker 向け抜粋には、スクリプトの呼び出し 1 行と、結果の読み方だけを書く

進め方

子 issue はすべてマイルストーン「17 トークン消費の削減」に置く。 1 回の /goal に渡すのはこのマイルストーンの中の 1 ミッションである。

• 基盤は、最初の読み手の Skill と同じ PR で入れてよい。 読み手の無い部品を先に作らない（ライブラリの条件「2 つ以上の読み手」は、2 つ目の Skill の issue で満たす）
• Skill ごとに本文の量を移行の前後で記録する。 基盤: Skill の書き方の規約に「スクリプト主体」を足し、検査と本文の量の計測を入れる #855 の --report で測る

効果の測り方

• Skill ごとの本文の量（SKILL.md と references のバイト数）の前後。移行前の値は下の表
• development-workflow: トークン消費の実測と削減（supervisor をスクリプトで駆動し、判断は最小構成の claude -p に任せる） #827 の計測スクリプトを、移行後の版で同じ条件で回す。サブエージェント内の Skill の読み込み量と、ポーリングの費用を比べる

移行前の本文の量（SKILL.md、2026-09-23 の develop）

Skill	バイト数	見込み
cross-review	33,428	約 15,000
cross-refactoring	31,833	約 20,000
merged	25,026	約 7,000
progress-tracking	24,270	約 8,000
fix	23,852	約 11,000
issue-plan-strategy	23,851	約 14,000
release	23,105	約 15,000
pr-review	21,622	約 10,000
issue-upkeep	21,090	約 16,000
markdown-writing	19,353	約 14,500
retrospective	19,003	約 9,000
external-ai	17,648	約 9,000
pr	16,323	約 8,000
document-restructuring	11,242	約 8,500
quality-gates	11,242	約 8,000
out-of-scope	9,142	約 6,000

見込みは今回の調査による概算で、測った値ではない。

受け入れ条件

• 子 issue がすべて閉じている（直さないと決めたものは理由を残して閉じる）
• 上の表の 16 Skill の本文の量が、移行後の値で埋まっている
• development-workflow: トークン消費の実測と削減（supervisor をスクリプトで駆動し、判断は最小構成の claude -p に任せる） #827 の計測で、サブエージェント内の Skill の読み込み量が移行前より減っている（数値をこの issue に残す）
• 段 2 の判断点の一覧が supervisor の分類・振り分けの判断を Jev へ移し、最小構成の claude -p より費用を下げる #841 に渡っている

関連

#827（親の方針）、#828、#829、#830、#841、#760、#560、#480

先に進める範囲（2026-09-24 利用者の判断）

development-workflow が毎回通る Skill の子（#857 #858 #862 #856 #872 #846 #847 #859 と、合流した #870 #852 #869）を先に進める。#827 の試作 phase-steps.py（PR #986）を各 Skill のスクリプトへ移す形で、設計・検証のフェーズは飛ばす。根拠は #980 #893 のミッションの実測（Skill を LLM が回した段のうちスクリプトで済むものが費用の約 49%、収束ループが約 38%）。

進行

モード: —

• 要求と受け入れ条件
• 作業場所の用意
• 設計
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画
• 実装
• 構造改善
• 実装レビュー
• 完了判定
• Pull Request
• 確定仕様化
• 後片付け
• 配布 — 2026-09-25 00:53
• 体裁レビュー
• リリース後テスト — 2026-09-25 01:12
• 振り返り