前言¶
自建 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
