skill-improver

技能改进器

运行 /code-improver:improve 来改进 Claude Code 技能——这是一个动态工作流，会循环调用审查子 Agent 和修复子 Agent，直到审查结果中没有严重或重大问题，然后清理自身残留。此入口会将循环连接到 plugin-dev:skill-reviewer Agent，因此必须安装 plugin-dev 插件（市场：claude-plugins-official）。循环、记录台账和防护措施都在工作流中；此技能负责解析目标并传达结果。

启动循环

用户提供了：$ARGUMENTS（如果为空，则从对话中获取目标技能）。

1. 解析技能路径

1. 如果输入以 /SKILL.md 结尾且文件存在，则使用其所在目录
2. 如果输入是包含 SKILL.md 的目录，则使用该路径
3. 否则，运行 Glob(pattern="**/SKILL.md")，并按技能名称或路径子字符串筛选：
   • 多个匹配项： 请用户选择
   • 没有匹配项： 报告可用技能
   • 单个匹配项： 继续

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。如果三个命令都未返回结果，则尝试一次 {name: "code-improver:improve"}；如果仍不可用，就停止并说明无法找到循环。不要手动拼接路径，也不要自行编造循环。

3. 调用工作流

使用 Workflow 工具运行，{scriptPath: "<第 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
}

• 仅当用户要求使用不同的上限（--max-rounds N）时才设置 maxRounds。
• pluginRoot 用于让运行过程找到其指标收集器；只有当第 2 步回退到工作流名称时才省略此键——此时工作流会自行查找。
• 仅当用户限制或扩大了循环可操作的范围时，才设置 scope（相对于仓库的 glob 模式）；默认情况下，工作流仅作用于技能的插件目录。
• 仅在继续运行时（见下文）设置 decision。

工作流会在后台运行，无需看管：它会审查、修复、再次审查，在每轮修复后检查范围，并且只有审查结果干净时才会完成。 它不会提交更改；所有更改都会保留在工作树中。

如果 Workflow 工具不可用或调用被拒绝，请停止并说明情况。 不要通过直接编辑来内联模拟循环——台账、范围防护和升级保障都由工作流提供，而内联仿效不具备这些保障（已观察到的失败：内联回退通过削弱文档中承诺的保障来“修复”问题，而防止这种情况正是设置该循环的目的）。

如果结果为 halted: "reviewer-unavailable"，请转达结果并停止。 此技能指定的审查器尚未安装；请告知用户从 claude-plugins-official marketplace 安装 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）；磁盘上的台账会更新至最后一轮，重新运行时会从该处恢复。

此循环强制执行的事项（让你无需操心）

• 修复验证 — 下一轮审查会验证每项修复；对可执行行为的修复会附带校验项，若针对修复前的代码运行，则会失败。
• 范围 — 每轮修复后以及 finalize 阶段后，都会进行机械化的 git 差异检查，任何超出范围的更改都会导致流程停止；对于 git 未跟踪的范围外文件，会通过内容哈希进行防护，因为差异中不会显示这些文件；完成流程还要求范围内没有未注册的新文件。
• 报告所有问题 — 审查者会报告所有发现并标注严重程度；筛选只在台账裁定时进行，若无新证据，不会重新争议已驳回的问题。
• Finalize — 完成前，循环会删除叙述性注释，将版本变更压缩为恰好一次递增（在 plugin.json 和重复记录该版本的市场条目中），并执行文档与代码一致性检查。这些编辑会在最后一轮审查后提交，因此检查会读取这些内容：如果过度删除叙述性注释，或文档中存在错误声明，流程会以 finalize-regression 停止，而不会判定为完成。

不适用场景

• 一次性审查：直接调用 plugin-dev:skill-reviewer Agent
• 快速修复单个问题：直接编辑文件
• 非 skill 目标：使用与目标匹配的审查者搭配 code-improver skill，或对分支使用 pr-improver
• 探索性起草：手动迭代能在结构尚未定型时提供更多控制权