By name: improve-skill description: スキルファイルを静的解析・実行シミュレーションで改善する。実プロジェクトを動かさずにトークン効率・明瞭性・完全性を評価し、具体的な改善案を提示する。スキルを新規作成・修正したとき、または品質改善を求められたときに使う。
/improve-skill
対象スキルを「コールドスタートのサブエージェントが実行する」視点でレビューし、改善案を提示する。 実プロジェクトを動かさないため、低トークンで反復改善が可能。
使い方
/improve-skill <ファイルパス>— 指定スキルを改善する/improve-skill— 引数なしの場合はファイルパスをユーザーに確認する/improve-skill <ファイルパス> --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/skills/ 全件）
WAIT_FOR: ユーザーの回答
FILE_ARGS = ユーザーの回答
IF "--cross" が元の引数に含まれる かつ FILE_ARGS が単一ファイルパス（"all" および複数パスは除く）:
CROSS_MODE = true
ENDIF
ENDIF
IF FILE_ARGS が "all":
LIST: .claude/skills/ 内の全 .md ファイルを対象にする
→ 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 に加え、子スキルのパスを抽出する
- Skill ツール呼び出しに含まれるスキル名（例: `skill: "craft"` → `.claude/skills/craft/SKILL.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で参照する）:
- スキルの目的（frontmatter の description）
- ステップの数・構造・順序
- ゲート（GATE / WAIT_FOR / PROHIBITED）の位置
- サブエージェント呼び出し（Agent ツール）の有無と渡すプロンプト
- ファイル操作（Read / Write / Edit / Glob）
- 変数（<cwd> など）の定義と使用箇所
DETECT スキルの種別（[E] の評価方法が変わる）:
プログラム型: Agent ツール（サブエージェント）呼び出しを含む → [E] はプログラム型チェックを適用
※ WAIT_FOR はユーザーインタラクションであり [E] の評価対象とは無関係
指示文型: Claude への自然言語指示のみ（サブエージェント呼び出しなし） → [E] は指示文型チェックを適用
判断に迷う場合（Agent 呼び出しが 1 箇所のみなど）: プログラム型として扱う
DETECT 書き込み・不可逆操作の有無（[D] の評価方法が変わる）:
あり: Write / Edit / Bash（副作用あり）/ 外部API書き込みを含む → [D] はゲート設計チェックを適用
なし: Read / Glob / Grep / WebSearch のみ → [D] はスコープ純粋性チェックを適用
ステップ 2: 6次元の静的評価
各次元を 1〜5 で採点し、問題箇所を行番号付きで列挙する。
EVALUATE:
SCORING INTEGRITY（全採点に適用）:
PROHIBITED: ループを終わらせるためにスコアを意図的に高くすること
PROHIBITED: ループを継続させるためにスコアを意図的に低くすること
PROHIBITED: 前回スコアとの連続性を保とうとすること（毎回独立して採点する）
PROHIBITED: 改善の件数・努力量をスコアに反映させること
RULE: スコアを確定する前に、各次元で「通過したCHECK / 失敗したCHECK」を列挙する
RULE: スコアの根拠はチェックリストの充足状況のみとする
NOTE: EXTRACT 結果（ステップ1）を各次元の採点根拠として使うこと。ファイルの再読みは最小限にする。
[A] → 「ステップの数・構造」「ファイル操作」（重複・冗長・肥大化の確認）
[B] → 「description」「GATE 位置」「変数の定義と使用箇所」
[C] → 「ファイル操作」「条件分岐パス」「GATE / WAIT_FOR の位置」
[D] → 「ファイル操作（Write / Edit の有無）」「GATE / WAIT_FOR の位置」「PROHIBITED」
[E] → 「Agent ツール呼び出しの有無と渡すプロンプト」「WAIT_FOR の数と位置」
[F] → 「description」「ファイル操作の READ タイミング」
[A] トークン効率
CHECK: 同じ情報が複数箇所に重複していないか
CHECK: 削除しても意味が変わらない説明・前置き・まとめがないか
CHECK: テーブルや疑似コードに冗長な列・行がないか
CHECK: 同じ構造の繰り返しをループで書けるのに展開されていないか
CHECK: SKILL.md が肥大化していて、相互排他的なコンテキストを
別ファイルに分離してトークン使用量を削減できないか
（大きな SKILL.md は必要なときだけ参照するサブファイルに分割できる）
CHECK: 参照ファイルが実行開始時に一括ロードされる設計になっていないか
（just-in-time 読み込みを優先する。必要になった段階で READ すること）
[B] 明瞭性
CHECK: 命令が1通りにしか解釈できないか（2通り以上ある = 問題）
CHECK: 変数名・ファイルパス・条件が文脈なしで特定できるか
CHECK: REQUIRE / ASSERT / GATE / PROHIBITED が一貫して使われているか
CHECK: サブエージェントへのプロンプトに「何をするか」が明確に書かれているか
CHECK: frontmatter の description が「Claudeがこのスキルを呼ぶべき状況」を
一文で判断できるほど具体的か
（descriptionの質が自動呼び出し精度を直接決める。曖昧な description は誤呼び出し・未呼び出しの原因）
CHECK: 重要なルールに「IMPORTANT」「YOU MUST」等の強調が付いているか
（スキルが肥大化するほどルールが埋もれる。強調で埋没を防ぐ）
[C] 完全性
CHECK: 各ステップに失敗したときの処理が書かれているか
CHECK: 暗黙の前提（OS・権限・依存ツール）が明示されているか
CHECK: ファイルパスが相対と絶対で混在していないか
CHECK: 条件分岐の全パス（IF/ELSE/ELIF）が網羅されているか
CHECK: スキル実行後にエージェントが成功を自己検証できる手段が記述されているか
（コマンド実行・ファイル存在確認・ビルド成功確認 等）
※ 検証手段がないと「見た目は動いているが実は壊れている」状態を見逃す
CHECK: ステップ間のデータ受け渡し（変数・ファイル・EXTRACT結果等）の依存関係が明示されているか
（暗黙の受け渡しは、ループや分岐があると実行順により未初期化になることがある）
CHECK: ループ・繰り返し処理がある場合、イテレーションごとに行うことと一度だけ行うことが区別されているか
[D] ゲート設計・スコープ純粋性
書き込み・不可逆操作を含む場合（ゲート設計）:
CHECK: ユーザー確認（WAIT_FOR）が不可逆な操作の前にあるか
CHECK: PROHIBITED でゲートをスキップする抜け道が塞がれているか
CHECK: ゲート後の処理がゲート前に漏れていないか
書き込み・不可逆操作を含まない場合（スコープ純粋性）:
CHECK: スキルが description で宣言した目的以外の操作をしていないか
CHECK: 副作用（ファイル作成・外部サービス呼び出し）が予告なく発生しないか
CHECK: ユーザーが期待しない出力・操作が含まれていないか
[E] エージェント・対話効率
プログラム型の場合:
CHECK: サブエージェントのプロンプトに不要なコンテキストが含まれていないか
CHECK: 直列になっているが並列化できるステップがないか
CHECK: サブエージェントの完了待ちが明示されているか
CHECK: 親エージェントとサブエージェントで同じ作業を二重にしていないか
指示文型の場合:
CHECK: WAIT_FOR（ユーザー確認）の回数が最小限か（不要な往復がないか）
CHECK: ユーザーへの複数の質問を 1 メッセージにまとめているか
CHECK: スキップ条件・早期終了条件が定義されていて無駄なステップを踏まないか
CHECK: 確認なしで進めるステップを WAIT_FOR でブロックしていないか
[F] Progressive Disclosure（段階的開示）
※ Anthropic 公式の推奨設計原則
CHECK: description がスキルを呼ぶべき状況をClaude単独で判断できる具体性を持っているか
（第1段階: descriptionだけでトリガー判断 → 曖昧だと呼ばれない・誤呼ばれする）
CHECK: SKILL.md 本体を読めば実行に必要な情報が揃うか、あるいは
参照先ファイルへの READ 指示が明示されているか
（第2段階: SKILL.md全体をコンテキストに読む）
CHECK: 参照ファイルが「必要になった段階で初めて READ する」設計になっているか
（第3段階以降: 参照ファイルは on-demand ロード。事前一括ロードはトークン浪費）
CHECK: 肥大化した SKILL.md を複数サブファイルに分割できる余地がないか
（相互排他的なコンテキストの分離でトークン消費を削減できる）
ステップ 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: コールドスタートのサブエージェント（このスキルを初めて見る）
GOAL: 各ステップを「意図的に誤解しやすい解釈」で読み、混乱・スキップ・誤動作が起きる箇所を探す
TRACE TARGETS:
- 「この命令、2通りに読める」と感じた箇所
- 「これは省略してもいいかな」と思えた箇所
- 「どのディレクトリで実行すればいい？」と迷った箇所
- 「この変数、どこで定義されてたっけ？」と戻りたくなった箇所
- 「エラーが出たらどうすればいい？」と詰まった箇所
- 「ゲートの条件を満たしているか判断できない」箇所
- 「このスキルが今のタスクに関係するか分からない」（description が曖昧）
- 「作業が完了したか自分で確認する方法がない」（検証手段の欠如）
- 「このルール、重要なのか流し読みしていいのか分からない」（強調不足）
- 「参照ファイルをいつ読めばいいか分からない」（just-in-time ロードが不明確）
- 「ステップ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] ゲート設計・スコープ純粋性: X/5
[E] エージェント・対話効率 : X/5
[F] Progressive Disclosure: X/5
────────────────────────────────────────────
── 改善提案 ────────────────────────────────
#1 [B] HIGH — L42: <問題の概要>
Before: ...
After: ...
理由: ...
────────────────────────────────────────────
#2 ...
※ 複数ファイルモード（all / 複数パス）の場合:
── ファイル1: <パス> ───────────────────────
[A] トークン効率 : X/5
[B] 明瞭性 : X/5
[C] 完全性 : X/5
[D] ゲート設計・スコープ純粋性: X/5
[E] エージェント・対話効率 : X/5
[F] Progressive Disclosure: X/5
────────────────────────────────────────────
── ファイル2: <パス> ───────────────────────
...（同形式）
────────────────────────────────────────────
── 全ファイルの改善提案 ─────────────────────
#1-1 [B] HIGH — L42: ...
#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-skill を実行すると次のサイクルを行えます。"
評価の限界（検出できないもの）
このスキルが静的解析で検出できない問題：
- 環境依存の失敗（OSのバージョン・インストール済みツールの差異）
- ライブラリのバージョン変更による破壊的変更
- 実際の出力が期待と異なるケース（Claude の解釈次第で変わる動作）
- 対象プロジェクトの文脈に依存する正しさ（正しいシグナル名・パスなど）
これらは実プロジェクトでの使用後のポストモーテムで補完する。