skill-improver

スキル改善ツール

/code-improver:improve を実行して Claude Code のスキルを改善します。レビュー担当と修正担当のサブエージェントが、レビューで重大または主要な指摘がゼロになるまで繰り返し動作し、その後、独自に追加した痕跡を取り除く動的なワークフローです。このエントリーポイントはループを plugin-dev:skill-reviewer エージェントに接続するため、plugin-dev プラグインがインストールされている必要があります（マーケットプレイス：claude-plugins-official）。ループ、記録簿、ガードはワークフロー内にあり、このスキルは対象を特定して結果を伝えます。

ループの開始

ユーザーが指定した値：$ARGUMENTS（空の場合は、会話から対象のスキルを特定します）。

1. スキルのパスを特定する

1. 入力が /SKILL.md で終わり、そのファイルが存在する場合は、そのディレクトリを使用します
2. 入力が SKILL.md を含むディレクトリの場合は、そのパスを使用します
3. それ以外の場合は、Glob(pattern="**/SKILL.md") を実行し、スキル名またはパスの部分文字列で絞り込みます：
   • 一致する項目が複数ある場合： ユーザーに選択を求めます
   • 一致する項目がない場合： 利用可能なスキルを報告します
   • 一致する項目が1つの場合： 次に進みます

2. ループスクリプトを特定する

ループは、このプラグインにある動的ワークフロー workflows/improve.js です。パスを指定して起動します。scriptPath には解決済みの絶対パスが必要です。また、Workflow ツールの name は組み込みワークフローとプロジェクトのワークフローを解決するため、マーケットプレイスからインストールしたものが code-improver:improve で見つからない場合があります。以下の順に試し、最初に見つかったものを使用します。ホームディレクトリを . より先に検索するため、マーケットプレイスからインストールしたコピーが、このマーケットプレイスのチェックアウトより優先されます。

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"（その変数が設定されている場合）
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

出力されたパスをそのまま使用します。/workflows/improve.js を取り除いたパスが、そのプラグインディレクトリの pluginRoot です。3つすべての結果が空の場合は、{name: "code-improver:improve"} を一度だけ試します。それも利用できない場合は、ループが見つからなかったことを伝えて停止します。手作業でパスを組み立てたり、ループを独自に実装したりしないでください。

3. ワークフローを実行する

Workflow ツールで実行します。{scriptPath: "<the path from step 2>", args: {...}}：

{
  "target": "<resolved absolute path>",
  "reviewer": {
    "kind": "agent",
    "name": "plugin-dev:skill-reviewer",
    "notes": "The target is a Claude Code skill directory; review it as a skill (frontmatter, triggering description, progressive disclosure, referenced files)."
  },
  "pluginRoot": "<the plugin directory from step 2>",
  "maxRounds": 5
}

• maxRounds を指定するのは、ユーザーが別の上限（--max-rounds N）を求めた場合のみです。
• pluginRoot を指定すると、実行時にメトリクスコレクターを見つけられます。ステップ 2 でワークフロー名までしか特定できなかった場合に限り、このキーを省略してください。その場合、ワークフローが自身を検索します。
• scope（リポジトリ相対の glob）を指定するのは、ループが変更できる範囲をユーザーが制限または拡大した場合のみです。デフォルトでは、ワークフローはスキルのプラグインディレクトリを対象範囲とします。
• decision を指定するのは、以下の継続時のみです。

ワークフローはバックグラウンドで実行され、付き添う必要はありません。レビュー、修正、再レビューを行い、修正ラウンドごとに対象範囲を確認し、問題のないレビューが完了するまで終了しません。コミットは行いません。すべての変更は作業ツリーに残ります。

Workflow ツールを利用できない、または使用を拒否された場合は、そこで停止してその旨を伝えてください。 ループをインラインの直接編集で代用しないでください。台帳、対象範囲ガード、エスカレーションの保証はワークフローに組み込まれており、インラインで模倣してもその保証はありません（確認された失敗例：インラインの代替手段が、記載された保証を弱めることで指摘を「修正」しました。まさにそれを防ぐためにこのループがあります）。

結果が halted: "reviewer-unavailable" の場合は、その結果を伝えて停止してください。 このスキルが指定するレビュアーがインストールされていません。ユーザーに claude-plugins-official マーケットプレイスから plugin-dev プラグインをインストールして、再実行するよう伝えてください。スキルを自分でレビューしないでください。

ループの実行中にターンを終了しないでください。 Workflow ツールはタスク ID をすぐに返し、結果は後から届きます。対話型セッションでは、完了通知によってあなたが再度呼び出されます。通知を待ってください。非対話型の実行（スクリプト、CI、評価）では後続のターンがありません。途中で停止するとループはラウンドの途中で放棄されるため、起動後は完了するまでタスクをポーリングしてください（返されたタスク ID を使って TaskOutput を呼び出すか、一定時間待ってから再確認します）。「ループが実行中です。後で報告します」と回答したセッションでは、実行が放棄されています。

結果の伝達

ワークフローは構造化された結果を返します。区別が重要なので、正確に報告してください。

• converged: true — 最後のアクションは、重大または主要な指摘がゼロのレビューでした。使用したラウンド数、残っている軽微な指摘（open_minor_count）、成果物のパス（ledger_path、metrics）を報告してください。
• capped: true — 修正の上限に達し、最終レビューでもブロッキング問題が見つかりました。上限に到達し、収束していないとはっきり伝え、open_blocking を列挙してください。成功として提示しないでください。
• escalation — ループが収束していないこと（指摘の再発、件数が減らない、修正による問題の移動）を検出しました。エスカレーションのメッセージと指摘 ID をユーザーに伝えてください。追加のラウンドではなく、設計上の判断が必要です。
• halted — ガードが作動しました（対象範囲違反、未登録の新規ファイル、レビュアーの停止または利用不能、あるいはその後のチェックで独自の編集が失敗した最終化パス）。violations／new_untracked_files のパス、finalize_regressions の箇所、および注記を伝えてください。
• notes は常に結果とともに伝えてください。「git リポジトリが初期化された」などの重要な警告が含まれます。

エスカレーション後の継続

ループは設計上、エスカレーション時に停止します。ユーザーが（たとえば「ブロックリストを維持し、制約を文書化する」などの）判断を下したら、同じ target に加えて、以下を指定して新しい実行を開始してください。

{ "decision": "<the user's ruling, verbatim>" }

新しい実行ではディスク上の台帳が再読み込みされるため、すべての指摘、却下、判定が引き継がれます。ラウンド数はリセットされますが、再導出は行われません。

実行中のループを停止するには、ワークフロータスクを停止します（TaskStop）。ディスク上の台帳は最後のラウンドまでの状態になっており、再実行するとその状態から再開します。

このループで強制されること（自分で対応する必要はありません）

• 修正の検証 — 次のレビューですべての修正を検証します。実行可能な動作への修正には、修正前のコードでは失敗するピンが付けられます。
• スコープ — 各修正ラウンドの後と最終仕上げの後に機械的な git-diff チェックを行い、スコープ外の変更があれば停止します。Git が追跡していないスコープ外のファイルは、差分に現れないため、コンテンツハッシュで保護します。また、完了にはスコープ内に未登録の新規ファイルがないことも必要です。
• すべて報告 — レビュアーは重要度を付けてすべての指摘を報告します。絞り込みは台帳の判定時に一度だけ行い、新たな証拠がない限り、却下された指摘について再度議論しません。
• 最終仕上げ — 完了前に、このループは説明コメントを削除し、バージョンの変更を正確に 1 回の更新にまとめ（plugin.json と、同じバージョンを記載しているマーケットプレイスのエントリー）、ドキュメントとコードの整合性を確認します。これらの編集は最後のレビュー後に行われるため、チェックでその内容を確認します。説明コメントを削除しすぎたり、ドキュメントに誤った記述があったりした場合、完了扱いにせず、finalize-regression で停止します。

使用しない場合

• 一度きりのレビュー：plugin-dev:skill-reviewer エージェントを直接呼び出します
• 簡単な単発の修正：ファイルを直接編集します
• スキル以外の対象：対象に適したレビュアーとともに code-improver スキルを使用するか、ブランチには pr-improver を使用します
• 試行錯誤しながらの草稿作成：形式が固まっていない間は、手動で反復するほうが柔軟に進められます