Back to Details

skill-improver

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Improvement Methodology

技能优化方法论

Iteratively improve a Claude Code skill using the skill-reviewer agent until it meets quality standards.
使用skill-reviewer Agent迭代优化Claude Code技能，直到符合质量标准。

Prerequisites

前置要求

Requires the 
plugin-dev
plugin which provides the 
skill-reviewer
agent.
Verify it's enabled: run 
/plugins
— 
plugin-dev
should appear in the list. If missing, install from the Trail of Bits plugin repository.
需要安装提供
skill-reviewer
Agent的
plugin-dev
插件。
验证是否启用：运行
/plugins
—— 列表中应出现
plugin-dev
。如果缺失，请从Trail of Bits插件仓库安装。

Core Loop

核心循环

  1. Review - Call skill-reviewer on the target skill
  2. Categorize - Parse issues by severity
  3. Fix - Address critical and major issues
  4. Evaluate - Check minor issues for validity before fixing
  5. Repeat - Continue until quality bar is met
  1. 审查 - 对目标技能调用skill-reviewer
  2. 分类 - 按严重程度划分问题
  3. 修复 - 处理严重和主要问题
  4. 评估 - 修复次要问题前先验证其合理性
  5. 重复 - 持续循环直到达到质量标准

When to Use

适用场景

  • Improving a skill with multiple quality issues
  • Iterating on a new skill until it meets standards
  • Automated fix-review cycles instead of manual editing
  • Consistent quality enforcement across skills
  • 优化存在多个质量问题的技能
  • 迭代打磨新技能直至符合标准
  • 用自动修复-审查循环替代手动编辑
  • 对所有技能执行统一的质量管控

When NOT to Use

不适用场景

  • One-time review: Use 
    /skill-reviewer
    directly instead
  • Quick single fixes: Edit the file directly
  • Non-skill files: Only works on SKILL.md files
  • Experimental skills: Manual iteration gives more control during exploration
  • 单次审查：请直接使用
    /skill-reviewer
  • 快速单次修复：直接编辑文件即可
  • 非技能文件：仅适用于SKILL.md文件
  • 实验性技能：探索阶段手动迭代可控性更高

Issue Categorization

问题分类

Critical Issues (MUST fix immediately)

严重问题（必须立即修复）

These block skill loading or cause runtime failures:
  • Missing required frontmatter fields (name, description) — Claude cannot index or trigger the skill
  • Invalid YAML frontmatter syntax — Parsing fails, skill won't load
  • Referenced files that don't exist — Runtime errors when Claude follows links
  • Broken file paths — Same as above, leads to tool failures
这类问题会阻塞技能加载或引发运行时故障：
  • 缺失必填的头信息字段（name、description）—— Claude无法索引或触发该技能
  • YAML头信息语法无效——解析失败，技能无法加载
  • 引用的文件不存在——Claude访问链接时会出现运行时错误
  • 文件路径损坏——和上述问题一致，会导致工具调用失败

Major Issues (MUST fix)

主要问题（必须修复）

These significantly degrade skill effectiveness:
  • Weak or vague trigger descriptions — Claude may not recognize when to use the skill
  • Wrong writing voice (second person "you" instead of imperative) — Inconsistent with Claude's execution model
  • SKILL.md exceeds 500 lines without using references/ — Overloads context, reduces comprehension
  • Missing "When to Use" or "When NOT to Use" sections — Required by project quality standards
  • Description doesn't specify when to trigger — Skill may never be selected
这类问题会大幅降低技能的可用性：
  • 触发描述模糊或薄弱——Claude可能无法识别该技能的适用场景
  • 写作语态错误（使用第二人称「you」而非祈使语气）——不符合Claude的执行模型规范
  • SKILL.md超过500行且未使用引用——会占用过多上下文，降低理解效率
  • 缺失「适用场景」或「不适用场景」章节——不符合项目质量标准要求
  • 描述未说明触发时机——技能可能永远不会被调用

Minor Issues (Evaluate before fixing)

次要问题（修复前先评估）

These are polish items that may or may not improve the skill:
  • Subjective style preferences — Reviewer may have different taste than author
  • Optional enhancements — May add complexity without proportional value
  • "Nice to have" improvements — Consider cost-benefit before implementing
  • Formatting suggestions — Often valid but low impact
这类属于优化项，不一定能提升技能效果：
  • 主观风格偏好——审查者的审美可能和作者不同
  • 可选增强功能——可能增加复杂度但带来的价值不成正比
  • 「锦上添花」类优化——实现前先考虑投入产出比
  • 格式建议——通常合理但影响极低

Minor Issue Evaluation

次要问题评估标准

Before implementing any minor issue fix, evaluate:
  1. Is this a genuine improvement? - Does it add real value or just satisfy a preference?
  2. Could this be a false positive? - Is the reviewer misunderstanding context?
  3. Would this actually help Claude use the skill? - Focus on functional improvements
Only implement minor fixes that are clearly beneficial. Skill-reviewer may produce false positives.
实现任何次要问题的修复前，先评估以下几点：
  1. 这是不是真实的优化？ - 它是真的能带来实际价值，还是只是满足个人偏好？
  2. 会不会是误报？ - 审查者是不是误解了上下文？
  3. 真的能帮助Claude更好地使用该技能吗？ - 优先关注功能性优化
仅实现明确有益的次要修复。skill-reviewer可能会产生误报。

Invoking skill-reviewer

调用skill-reviewer

Use the skill-reviewer agent from the plugin-dev plugin. Request a review by asking Claude to:
Review the skill at [SKILL_PATH] using the plugin-dev:skill-reviewer agent. Provide a detailed quality assessment with issues categorized by severity.
Replace 
[SKILL_PATH]
with the absolute path to the skill directory (e.g., 
/path/to/plugins/my-plugin/skills/my-skill
).
使用plugin-dev插件提供的skill-reviewer Agent。你可以向Claude发起如下请求触发审查：
使用plugin-dev:skill-reviewer Agent审查路径为[SKILL_PATH]的技能，输出按严重程度分类的详细质量评估报告。
将
[SKILL_PATH]
替换为技能目录的绝对路径（例如：
/path/to/plugins/my-plugin/skills/my-skill
）。

Example Fix Cycle

修复循环示例

Iteration 1 — skill-reviewer output:
text
Critical: SKILL.md:1 - Missing required 'name' field in frontmatter
Major: SKILL.md:3 - Description uses second person ("you should use")
Major: Missing "When NOT to Use" section
Minor: Line 45 is verbose
Fixes applied:
  • Added name field to frontmatter
  • Rewrote description in third person
  • Added "When NOT to Use" section
Iteration 2 — run skill-reviewer again to verify fixes:
text
Minor: Line 45 is verbose
Minor issue evaluation: Line 45 communicates effectively as-is. The verbosity provides useful context. Skip.
All critical/major issues resolved. Output the completion marker:
<skill-improvement-complete>
Note: The marker MUST appear in the output. Statements like "quality bar met" or "looks good" will NOT stop the loop.
第1轮迭代 —— skill-reviewer输出：
text
Critical: SKILL.md:1 - Missing required 'name' field in frontmatter
Major: SKILL.md:3 - Description uses second person ("you should use")
Major: Missing "When NOT to Use" section
Minor: Line 45 is verbose
执行的修复：
  • 给头信息添加了name字段
  • 把描述重写为第三人称格式
  • 新增了「不适用场景」章节
第2轮迭代 —— 再次运行skill-reviewer验证修复效果：
text
Minor: Line 45 is verbose
次要问题评估： 第45行的表述已经足够清晰，冗余内容提供了有用的上下文，跳过修复。
所有严重/主要问题已解决，输出完成标记：
<skill-improvement-complete>
注意：输出中必须包含该标记。类似「已达到质量标准」或者「看起来没问题」的表述不会终止循环。

Completion Criteria

完成标准

CRITICAL: The stop hook ONLY checks for the explicit marker below. No other signal will terminate the loop.
Output this marker when done:
<skill-improvement-complete>
When to output the marker:
  1. skill-reviewer reports "Pass" or no issues found → output marker immediately
  2. All critical and major issues are fixed AND you've verified the fixes → output marker
  3. Remaining issues are only minor AND you've evaluated them as false positives or not worth fixing → output marker
When NOT to output the marker:
  • Any critical issue remains unfixed
  • Any major issue remains unfixed
  • You haven't run skill-reviewer to verify your fixes worked
The marker is the ONLY way to complete the loop. Natural language like "looks good" or "quality bar met" will NOT stop the loop.
重要提示：终止钩子只会检测下方的显式标记，其他任何信号都不会结束循环。
完成时输出此标记：
<skill-improvement-complete>
输出标记的触发条件：
  1. skill-reviewer返回「通过」 或 未发现任何问题 → 立即输出标记
  2. 所有严重和主要问题都已修复 且你已验证修复生效 → 输出标记
  3. 剩余问题均为次要问题 且你已评估确认属于误报或不值得修复 → 输出标记
不得输出标记的场景：
  • 仍有未修复的严重问题
  • 仍有未修复的主要问题
  • 你还没有运行skill-reviewer验证修复是否生效
标记是结束循环的唯一方式。「看起来没问题」「已达到质量标准」这类自然语言表述不会终止循环。

Rationalizations to Reject

应当拒绝的合理化借口

  • "I'll just mark it complete and come back later" - Fix issues now
  • "This minor issue seems wrong, I'll skip all of them" - Evaluate each one individually
  • "The reviewer is being too strict" - The quality bar exists for a reason
  • "It's good enough" - If there are major issues, it's not good enough
  • 「我先标记完成，之后再回来改」—— 现在就修复问题
  • 「这个次要问题看起来不对，我全部跳过就好」—— 逐个单独评估
  • 「审查者太严格了」—— 质量标准的存在是有原因的
  • 「已经够用了」—— 如果还有主要问题，就说明还不够好