improve-agent - SKILL.md Agent Skill

name: improve-agent description: エージェントファイルを静的解析・実行シミュレーションで改善する。実プロジェクトを動かさずにトークン効率・役割純粋性・命令明瞭性を評価し、具体的な改善案を提示する。エージェントを新規作成・修正したとき、または品質改善を求められたときに使う。

/improve-agent

対象エージェントを「コールドスタートの Claude が実行する」視点でレビューし、改善案を提示する。実プロジェクトを動かさないため、低トークンで反復改善が可能。

使い方

/improve-agent <ファイルパス> — 指定エージェントを改善する
/improve-agent — 引数なしの場合はファイルパスをユーザーに確認する
/improve-agent <ファイルパス> --cross — 親エージェントと、そこから呼び出される子エージェントをまとめて改善する

手順

ステップ 1: 対象ファイルの特定と読み込み

SKILL_DIR: このSKILL.mdが存在するディレクトリのパス（ステップ全体で参照する変数として保持）

DETECT AUTO_MODE（ステップ全体で参照する変数として保持）:
  以下のいずれかを満たす場合 AUTO_MODE = true:
  - 会話コンテキストに "/loop" コマンドの実行履歴がある
  - 会話コンテキストに "適用後スコア: 平均" で始まるスコア報告が存在する（2回目以降のループ反復）
  - 引数またはユーザーの直近メッセージにスコア閾値（"点", "score", "以上", "超える" 等）が含まれる
  それ以外: AUTO_MODE = false

REJECT_BUFFER = []
IF AUTO_MODE = true:
  会話コンテキストから以下を抽出し REJECT_BUFFER に追加する:
  - 過去イテレーションでユーザーが選択しなかった提案の「場所: L<行番号>」+「分類: [A〜F]」
ENDIF

FILE_ARGS: 引数からスコア閾値テキスト（"点"・"以上"・"超える"・"score"・"まで"・"目標" 等を含むトークン）および "--cross" を除いた部分
           以降の引数解析（"all" 判定・複数パス判定・単一パス読み込み）はすべて FILE_ARGS を参照する

DETECT CROSS_MODE:
  "--cross" が引数に含まれる かつ FILE_ARGS が単一ファイルパス（"all" および複数パスは除く）の場合: CROSS_MODE = true
  それ以外: CROSS_MODE = false

IF FILE_ARGS が空（引数なし、またはスコア閾値テキストのみ）:
  ASK USER: 対象エージェントのパスを教えてください（"all" で .claude/agents/ 全件）
  WAIT_FOR: ユーザーの回答
  FILE_ARGS = ユーザーの回答
  IF "--cross" が元の引数に含まれる かつ FILE_ARGS が単一ファイルパス（"all" および複数パスは除く）:
    CROSS_MODE = true
  ENDIF
ENDIF

IF FILE_ARGS が "all":
  LIST: .claude/agents/ 内の全 .md ファイルを対象にする
  ファイルが 0 件の場合: "対象ファイルが見つかりません: .claude/agents/" と報告して STOP
  → MULTI_FILE_PROCESS を実行する
ELIF FILE_ARGS が複数パス（スペース区切りで2つ以上のファイルパス）:
  LIST: FILE_ARGS で指定されたパスを対象ファイル一覧とする
  → MULTI_FILE_PROCESS を実行する
ELSE:
  READ: <対象エージェントファイル>  ← FILE_ARGS のパス
  IF ファイルが存在しない:
    REPORT: "ファイルが見つかりません: <パス>"
    STOP
  ENDIF
  IF CROSS_MODE = true:
    EXTRACT（親エージェント）: 通常の EXTRACT に加え、子エージェントのパスを抽出する
      - Agent ツール呼び出しの subagent_type パラメータ（例: `subagent_type: "forager:Scout"` → `.claude/agents/forager-Scout.md`）
      - Agent ツールのプロンプトに含まれるエージェントファイルパス参照
    FOR EACH 子エージェントパス:
      READ: 子エージェントファイル
      IF ファイルが存在しない: WARN "子エージェントが見つかりません: <パス>" → スキップ
    対象ファイル一覧 = [親エージェント] + [存在した子エージェント]
    IF 子エージェントが0件:
      WARN: "子エージェントが見つからないためクロスチェックをスキップします"
      CROSS_MODE = false
      単一ファイルとして処理を続行する → ステップ2へ
    ELSE:
      → MULTI_FILE_PROCESS を実行する（ステップ2.5完了後にステップ4.5も実行）
    ENDIF
  ELSE:
    — CROSS_MODEなし: 通常の単一ファイル処理としてステップ2へ進む
  ENDIF
ENDIF

MULTI_FILE_PROCESS:
  各ファイルについて READ → EXTRACT → ステップ2・3・4 の順に実行する
  全ファイル完了後、ステップ2.5を一度だけ実行する
  CROSS_MODE = true の場合はステップ4.5を実行する
  その後ステップ5に進む
  ステップ5では全提案を "#<ファイルindex>-<提案番号>" 形式で表示し
  "1-1 2-3 / all / skip" 形式で選択させる

EXTRACT（コンテキスト内に保持し、ステップ2〜4で参照する）:
  - 役割の宣言（## Role / ## 役割、または冒頭の "You are..." 文）
  - model と tools の設定（frontmatter の tools: / model: フィールド）
  - プロセスのステップ数・構造
  - 出力フォーマットの定義
  - ルールの内容と数
  - 他エージェントへの言及（intake / planner / designer など）

ステップ 2: 6次元の静的評価

各次元を 1〜5 で採点し、問題箇所を行番号付きで列挙する。

EVALUATE:

SCORING INTEGRITY（全採点に適用）:
  PROHIBITED: ループを終わらせるためにスコアを意図的に高くすること
  PROHIBITED: ループを継続させるためにスコアを意図的に低くすること
  PROHIBITED: 前回スコアとの連続性を保とうとすること（毎回独立して採点する）
  PROHIBITED: 改善の件数・努力量をスコアに反映させること
  RULE: スコアを確定する前に、各次元で「通過したCHECK / 失敗したCHECK」を列挙する
  RULE: スコアの根拠はチェックリストの充足状況のみとする

NOTE: EXTRACT 結果（ステップ1）を各次元の採点根拠として使うこと。ファイルの再読みは最小限にする。
  [A] → 「プロセスのステップ数・構造」「ルールの内容と数」（重複・冗長の確認）
  [B] → 「役割の宣言」「他エージェントへの言及」
  [C] → 「プロセスのステップ数・構造」「出力フォーマットの定義」
  [D] → 「model と tools の設定」
  [E] → 「出力フォーマットの定義」「ルールの内容と数」
  [F] → 「プロセスのステップ数・構造」「完了確認基準の有無」

[A] トークン効率
  CHECK: 同じ内容が複数セクション（役割・プロセス・ルール）に重複していないか
  CHECK: 削除しても意味が変わらない前置き・例示・まとめがないか
  CHECK: テーブル・コードブロックに不要な行・列がないか
  CHECK: ルールがプロセスの言い換えになっていないか（どちらかで十分）

[B] 役割の純粋性
  CHECK: 役割宣言に「何をしないか」が明記されているか
  CHECK: 他エージェントの担当領域（例：planner がすべき計画）をこのエージェントが侵食していないか
         （判断基準: そのステップを削除してもこの役割の目的が達成できるなら侵食）
  CHECK: プロセスのステップが役割の範囲内に収まっているか
  CHECK: 引き継ぎが必要な場合は完了報告で次エージェントへ誘導しているか、かつ不要な誘導（役割と無関係な次ステップの指示）がないか
  CHECK: 「侵食しかけている」グレーゾーン（役割と隣接する処理が同一エージェントに
         混在しているが、まだ逸脱とは言い切れない箇所）がないか

[C] 命令の明瞭性
  CHECK: 各ステップが1通りにしか解釈できないか
  CHECK: 「適切に」「必要に応じて」などの曖昧な副詞が使われていないか
  CHECK: 出力フォーマットに「何を書くか」が具体的に示されているか
  CHECK: 条件分岐（ヒアリング要否・スキップ条件など）の基準が明確か
  CHECK: ステップ間のデータ受け渡し（変数・ファイル・抽出結果等）が明示されているか
    （「ステップAの結果をステップBで使う」という依存が暗黙になっていないか）
  CHECK: ループ処理がある場合、各イテレーションで行うことと一度だけ行うことが区別されているか
    （例: EXTRACT は各ファイルで実行、全書き直し判定は全ファイル処理後に1回のみ）

[D] tools / model の適切性
  CHECK: 使用していない可能性が高いツールが tools に含まれていないか
    （副作用ツール Bash / Write / Edit は特に慎重に）
  CHECK: model の選択が役割に見合っているか
    （計画・複雑推論 → opus / 標準 → sonnet / 軽量・高速 → haiku）
  CHECK: tools が不足していて目的を達成できない可能性がないか
  CHECK（カスタムツール定義が存在する場合のみ）:
    ツールの description/parameters に使用例・エッジケース・入力形式要件・
    他ツールとの境界が書かれているか

[E] 出力設計
  CHECK: 出力フォーマットが定義されているか（フリーテキストになっていないか）
  CHECK: フォーマットの各セクションに過不足がないか
  CHECK: 下流エージェントが読むファイルを生成する場合、ファイルパスが明記されているか
  CHECK: 成功時・失敗時・スキップ時の出力が区別されているか

[F] 検証可能性
  CHECK: エージェントが自分の作業完了を自己判断できる基準が定義されているか
    （テスト実行・ビルド確認・ファイル存在確認・コマンド実行 等）
    ※ 「検証手段を与えることが最高レバレッジ」（Anthropic公式）
  CHECK: 成功/失敗の判定基準が記述されているか（「よさそうなら完了」はNG）
  CHECK: 不可逆・高コストな操作の前に人間確認または自動検証のステップがあるか
  CHECK: 重要なルールに「IMPORTANT」「YOU MUST」等の強調が付いているか
    （ルールが埋もれると無視される。肥大化した指示では特に有効）

ステップ 2.5: 全書き直し判定

単一ファイルモード: ステップ2直後に実行する。 all / 複数パスモード: 全ファイルのステップ2〜4完了後に一度だけ実行する。

IF 対象ファイルのうち「2/5 以下の次元が 3つ以上」のものが1つ以上ある:
  WARN: 該当ファイルを列挙し、差分修正より全書き直しが適切な可能性を伝える
  IF AUTO_MODE = false:
    ASK USER:
      「続行しますか？　続行 → 差分修正を進める　/ 中止 → 書き直しはユーザーが行う」
    WAIT_FOR: ユーザーの選択
    IF 中止: STOP
  ELSE:
    REPORT: "AUTO_MODE のため差分修正を続行します"
  ENDIF
ENDIF

ステップ 3: Adversarial Trace（実行シミュレーション）

PERSONA: コールドスタートの Claude（このエージェントを初めて実行する）

GOAL: 各ステップを「意図的に誤解しやすい解釈」で読み、
      スコープ逸脱・手抜き・誤動作が起きる箇所を探す

TRACE TARGETS:
  - 「役割外のことをやってもよさそう」と感じた箇所
  - 「このステップは省略してもよさそう」と思えた箇所
  - 「どのファイルを読めばいい？」と迷った箇所
  - 「この出力フォーマット、どこまで埋めればいい？」と判断できなかった箇所
  - 「このルールとプロセスが矛盾している」と感じた箇所
  - 「完了の基準が分からない」と詰まった箇所
  - 「作業が完了したか自分で確認する方法がない」と感じた箇所（検証手段の欠如）
  - 「このツール、どう使えばいいか2通りの解釈ができる」と迷った箇所（ツール定義の曖昧さ）
  - 「このルールは重要なのか読み流していいのか分からない」と感じた箇所（強調不足）
  - 「ステップAで作ったデータ、ステップBで本当に使えるのか？」（データ受け渡しの暗黙性）
  - 「このステップはファイルごとに実行？それとも全体で一度だけ？」（ループの粒度の不明確さ）

OUTPUT: 誤解・スコープ逸脱・手抜きが起きやすい箇所のリスト（行番号付き）
  各発見に含める:
    箇所: L<行番号>
    観察: <何が起きるか>
    Root Cause: <なぜ起きるか（設計の欠陥・曖昧な境界・欠落した前提など）>
  ※ Root Cause はステップ4の提案生成の根拠として引き継ぐ

ステップ 4: 改善案の生成

FOR EACH 問題箇所（ステップ2・3の結果を統合）:
  IF REJECT_BUFFER に同一箇所・同一分類の提案が存在する: スキップ
  GENERATE 改善提案:
    分類: [A〜F]
    優先度: HIGH（動作に影響）/ MEDIUM（品質に影響）/ LOW（読みやすさ）
    場所: L<行番号> または セクション名
    改善次元: [改善する次元] / trade-off: [低下しうる次元]（なければ省略）
    Root Cause: <ステップ3の Root Cause、またはステップ2のCHECK失敗が起きる設計上の原因>
    Before: <現在の記述>
    After:  <改善後の記述>
    理由:   <1行>

SORT BY 優先度（HIGH → MEDIUM → LOW）

ステップ 4.5: 親子エージェント一貫性チェック（CROSS_MODE = true のみ）

READ: {SKILL_DIR}/CROSS_CHECK.md
IF ファイルが見つからない:
  WARN: "CROSS_CHECK.md が見つかりません: {SKILL_DIR}/CROSS_CHECK.md"
  CROSS_MODE = false → 単一ファイル処理としてステップ5へ進む

ステップ 5: ユーザー確認 & 適用

SHOW USER:
  スコアサマリー（6次元の採点）
  改善提案リスト（番号付き、優先度順）

FORMAT:
  ── スコア ──────────────────────────────────
  [A] トークン効率      : X/5
  [B] 役割の純粋性      : X/5
  [C] 命令の明瞭性      : X/5
  [D] tools/model適切性 : X/5
  [E] 出力設計          : X/5
  [F] 検証可能性        : X/5
  ────────────────────────────────────────────

  ── 改善提案 ────────────────────────────────
  #1 [B] HIGH — L12: <問題の概要>
  Before: ...
  After:  ...
  理由: ...
  ────────────────────────────────────────────
  #2 ...

  ※ 複数ファイルモード（all / 複数パス）の場合:
  ── ファイル1: <パス> ───────────────────────
  [A] トークン効率      : X/5
  [B] 役割の純粋性      : X/5
  [C] 命令の明瞭性      : X/5
  [D] tools/model適切性 : X/5
  [E] 出力設計          : X/5
  [F] 検証可能性        : X/5
  ────────────────────────────────────────────
  ── ファイル2: <パス> ───────────────────────
  ...（同形式）
  ────────────────────────────────────────────
  ── 全ファイルの改善提案 ─────────────────────
  #1-1 [B] HIGH — L12: ...
  #2-3 [D] MEDIUM — L8: ...
  ─────────────────────────────────────────────

  ※ CROSS_MODE = true の場合のみ追加表示:
  ── 親子エージェント一貫性 ────────────────────
  #X-1 [X2] MEDIUM — file1 vs file3: ...
  問題: ...
  推奨: ...
  理由: ...
  ─────────────────────────────────────────────

RECOMMEND:
  優先度 HIGH の提案から、以下の順で上位 3 件を選ぶ:
    1. trade-off なし かつ 改善次元が 2 つ以上（Pareto 改善）
    2. trade-off なし かつ 改善次元が 1 つ
    3. trade-off あり（必ず理由を添える）
  例: "#1 #3 #5 を最初に適用することを推奨します（理由: ...）"

IF AUTO_MODE = false:
  ASK USER:
    "適用する改善案を選んでください"
    "通常モード: 1 3 5 / all / skip"
    "all モード:  1-1 2-3 / all / skip（<ファイルindex>-<提案番号> 形式）"
  WAIT_FOR: ユーザーの選択
  IF ユーザーが "skip": REPORT "改善をスキップしました" → STOP
  IMPORTANT — PROHIBITED: ユーザーの選択なしにファイルを書き換えること
ELSE:
  承認された番号 = 全提案番号（"all" として扱う）
  REPORT: "AUTO_MODE のため全提案を適用します"
ENDIF

FOR EACH 承認された番号（all モードでは "<ファイルindex>-<提案番号>" 形式）:
  IDENTIFY: 対象ファイルと行番号を改善提案から特定する
  EDIT: 対象エージェントファイルの該当箇所を改善後の記述（After:）に置き換える

VERIFY:
  変更した箇所を READ して、After: の内容が正しく反映されているか確認する
  差異があれば再 EDIT する（最大2回。それでも残る場合:
    AUTO_MODE = false: ユーザーに報告して手動修正を依頼する
    AUTO_MODE = true: WARN を出力してスキップし次の提案へ進む）

DETECT LOOP_COUNT:
  会話コンテキスト内の "適用後スコア: 平均" の出現回数を数える
  LOOP_COUNT = 出現回数 + 1（今回を含む）

IF LOOP_COUNT >= 5:
  WARN: "5サイクルを超えました。改善が収束しないため強制終了します。"
  STOP
ENDIF

EVALUATE 改善後スコア（改善を1件以上適用した場合のみ）:
  改善後の状態で6次元スコアを再評価し、平均を算出する（今回平均）

IF LOOP_COUNT >= 2:
  前回平均 = 直前の "適用後スコア: 平均 Y.Y/5" の Y.Y を取得
  IF 今回平均 - 前回平均 < 0.2:
    REPORT: "スコア改善幅が 0.2 未満です（{前回平均} → {今回平均}）。改善が頭打ちのためループを終了できます。"
    STOP
  ENDIF
ENDIF

REPORT:
  "X 件の改善を適用しました: <ファイルパス>"
  "適用後スコア: 平均 Y.Y/5 — [A]X [B]X [C]X [D]X [E]X [F]X"
  IF 提案がゼロ件だった、または平均スコアが変化なし:
    "改善の余地がありません。ループを終了できます。"
  ELSE:
    "再度 /improve-agent を実行すると次のサイクルを行えます。"

評価の限界（検出できないもの）

実際のヒアリング品質（ユーザーの回答次第で変わる動作）
他エージェントとの連携時の実際の出力品質
model の応答特性の差異（sonnet と opus で解釈が変わる場合）
エージェント設計の意図に依存する正しさ（役割境界・ツール選択の妥当性は設計思想による）