前言¶
自建 Agent Skill 时，常见问题不是「不会写步骤」，而是 frontmatter 缺字段、触发描述含糊、章节结构不符合项目规范。人工对照 checklist 改一轮，再让同事或自己复读一遍，往往还要来回几轮。
下面介绍的 skill-improver 把这件事做成自动化：对目标 Skill 反复执行「审查 → 按严重级别修复 → 再审查」，直到达到 Trail of Bits 对 Claude Code Skill 的质量要求，或达到迭代上限。它依赖 plugin-dev 里的 skill-reviewer 做评审，属于「用 Skill 改进 Skill」的元能力；若你只需要单次评审，应直接使用 skill-reviewer，而不是开循环。
这是什么¶
skill-improver 是 Trail of Bits skills 市场中的一个插件 Skill，作者为 Paweł Płatek。定位是：针对 Claude Code 的 SKILL.md（及同目录引用文件），运行自动化的 fix-review 循环，直到关键质量问题被消掉。
官方说明与命令见 Skill Improver 文档。技能定义在仓库路径 plugins/skill-improver/skills/skill-improver/（与 GitHub 上的 skill-improver 目录 对应）。
核心功能¶
自动化 fix-review 循环¶
经过上面的定位，核心流程可以概括为五步：
- 解析你给出的 Skill 目录或
SKILL.md路径，在.claude/下创建会话状态。 - 调用 plugin-dev 的 skill-reviewer，按严重级别列出问题。
- Critical / Major 必须修；Minor 先判断是否真有价值再决定是否改（文档明确提示 reviewer 可能对 minor 误报）。
- 再次运行 skill-reviewer，确认修复有效并发现新问题。
- 重复，直到满足完成条件，或达到
--max-iterations（默认 20）。
完成时，Agent 必须输出显式标记 <skill-improvement-complete>；stop hook 只认这一标记，不会凭「差不多了」结束循环。
问题分级（与修复策略）¶
文档将 findings 分为三类，修复策略不同：
| 级别 | 典型项 | 处理方式 |
|---|---|---|
| Critical | 缺少 name/description、YAML 无效、引用文件或路径不存在 |
立即修复 |
| Major | 触发描述弱、叙述人称不当、正文过长未拆 references/、缺 When to Use / When NOT to Use |
必须修复 |
| Minor | 风格偏好、可选增强、格式建议 | 逐条评估后再改 |
多会话与取消¶
可对不同 Skill 并行开多个改进会话，状态文件形如 .claude/skill-improver.*.local.md。需要中止时使用 /cancel-skill-improver；已做的文件修改会保留。
与 code-improver 的关系¶
同一仓库里还有 code-improver 插件，提供带 findings ledger、scope guard 等机制的通用 review-and-fix 工作流，其中也包含面向 Skill 的改进入口。本文聚焦独立的 skill-improver 插件；若你需要对分支 diff 或更重的收敛/范围控制，可另行查阅 code-improver 文档。
安装与启用¶
前置：plugin-dev 与 skill-reviewer¶
skill-improver 依赖 plugin-dev 插件（提供 skill-reviewer agent）。在 Claude Code 中执行 /plugins，确认列表中有 plugin-dev；若没有，需从官方插件源安装（文档示例：/plugin install plugin-dev）。
添加 Trail of Bits 市场¶
Claude Code 先加入市场：
/plugin marketplace add trailofbits/skills
浏览并安装插件：
/plugin menu
也可按文档直接安装 skill-improver 插件路径：
/plugin install trailofbits/skills/plugins/skill-improver
Codex CLI¶
Codex 支持 Claude 插件市场兼容。安装市场并添加插件的典型命令为：
codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add <plugin-name>@trailofbits
具体插件名以 codex plugin list 输出为准；skill-improver 是否单独列出取决于市场元数据，安装后同样依赖 plugin-dev。
Cursor¶
公开文档以 Claude Code 斜杠命令（/skill-improver）为主。Cursor 侧若通过兼容的 Skills / 插件机制加载同一套 Trail of Bits 市场，步骤应与 Claude Code 市场安装一致；未在官方文档中单独说明的差异，此处不展开。
典型用法¶
启动改进循环¶
对 Skill 目录或 SKILL.md 发起循环：
/skill-improver ./plugins/my-plugin/skills/my-skill
/skill-improver ./skills/my-skill/SKILL.md --max-iterations 15
参数含义：
<SKILL_PATH>：Skill 目录，或指向SKILL.md的路径。--max-iterations N：最大轮数，默认 20。
命令实现会先解析路径（目录含 SKILL.md、或直接给出 SKILL.md；否则在仓库内 Glob 匹配），再调用插件内的 setup-skill-improver.sh 初始化循环。
文档中的迭代示例（摘要）¶
第一轮 review 可能报告：frontmatter 缺 name、description 使用第二人称、缺少 When NOT to Use，以及一条 minor 的「某行冗长」。修复阶段会补上 name、改写 description、补章节，并对 minor 判断「保留上下文更有用」而不改。
第二轮若仅剩同类 minor 且仍判为误报，在 critical/major 已清空且经 skill-reviewer 验证后，输出 <skill-improvement-complete> 结束。
查看或清理状态¶
查看活动会话状态文件：
ls .claude/skill-improver.*.local.md
cat .claude/skill-improver.*.local.md
取消循环：
/cancel-skill-improver
若达到默认 20 轮仍未完成，可人工处理剩余项后提高上限重启，例如 --max-iterations 30。
适用场景与注意¶
适合：
- 新建 Skill 已能跑通，但要对齐 Trail of Bits / Claude Code Skill 质量条。
- 多个 Skill 需要统一 frontmatter、触发语、When to Use / When NOT to Use 结构。
- 希望用自动化循环替代「手改 + 再问一遍 reviewer」的重复劳动。
不适合：
- 只要一次性评审：用 plugin-dev 的 skill-reviewer（或
/skill-reviewer），不要开 skill-improver 循环。 - 单处小改动：直接编辑
SKILL.md更快。 - 非 Skill 文件：本工具只针对 Skill 目录结构。
注意：
- 未安装 plugin-dev 时会出现 subagent 找不到；先装 plugin-dev。
- Minor 项不要全盘自动改，否则可能引入无意义 diff。
- 循环结束依赖
<skill-improvement-complete>，漏写会导致 hook 认为仍在进行。 - 官方示例中的安装路径、默认迭代次数以 Mintlify 文档 为准。
结尾¶
skill-improver 把 Skill 质量改进收敛成可重复的 fix-review 循环：评审由 skill-reviewer 执行，修复策略按 Critical / Major / Minor 区分，完成条件由显式标记收口。对经常自建 Skills 的开发者，它减少手工对照规范的时间，把精力留给领域步骤本身。
官方仓库：trailofbits/skills
插件文档：Skill Improver
技能路径：plugins/skill-improver/skills/skill-improver
