improve-skill

技能改进器

通过建模用户意图、通过思维模拟和实时文档验证来测试技能是否符合该意图，并提出按优先级排序的改进方案——新功能、用户体验提升、准确性修复、效率提升，从而提高现有技能的有效性。

此技能关注的是该技能是否满足用户需求。结构正确性（格式错误的 frontmatter、字段缺失、违反约定）属于 repair-skill 的职责范围——如果发现明显的结构问题，简要指出并建议使用 repair-skill，然后继续进行有效性分析。

阶段 0：加载技能

将 $ARGUMENTS 作为技能目录或 SKILL.md 文件的路径读取。

• 如果是目录：读取 SKILL.md，然后记录 references/、scripts/、examples/、assets/ 中哪些目录存在
• 如果是文件：直接读取，然后查找同级资源目录

如果路径缺失或有歧义，使用 AskUserQuestion 进行确认。

用一句话指出任何明显的结构问题（“此描述使用了第一人称——建议使用 repair-skill 修复结构问题”），然后继续。不要进行完整的结构审查。

当 SKILL.md 已加载且已记录同级目录清单时，阶段 0 即完成。

阶段 1：了解用户意图

开始分析前，先了解用户想要什么。使用 AskUserQuestion：

• “这项技能具体在哪些方面表现不佳？”
• 提供以下选项：“我注意到一个具体缺陷”、“我不确定——进行完整的有效性审查”、“它能正常工作，但我想增加新能力”、“工作流程不够顺畅”

无论用户如何回答，也要根据技能的描述和正文推断其用途。继续之前，用一句话说明你对它所解决的问题及目标用户的理解。这能为整个分析奠定正确的基础。

如果用户指出了具体问题：围绕该问题开展分析，并检查同一工作流程区域中是否存在相关问题。如果用户不确定：针对所有五项子分析进行完整的阶段 2 审查。

当用户意图已明确且技能用途已说明时，阶段 1 即完成。

阶段 2：有效性分析

开始前，加载 ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-rubric.md。该文件包含严重程度框架、改进类型定义，以及阶段 3 使用的工作量／影响评估标准。

运行全部五项子分析。对于每项发现，记录问题是什么、为何会降低用户体验，以及具体的改进方案。

---

2a — 思维模拟

以 Claude 执行技能的视角，使用一个具体且有代表性的用户请求逐步走查技能。选择能覆盖主要工作流程的输入——应是典型用例，而非边缘情况。

对于技能的每个阶段，评估：

• 信息缺失：此步骤需要哪些尚未提供或收集的信息？如果用户没有说明某事，而技能也没有询问，Claude 就必须猜测什么？
• 分歧点：两个不同的 Claude 实例执行这条指令时，哪些地方会导致结果出现实质差异？这些都是说明不够明确的步骤。
• 终点未达成：技能的工作流程在哪些地方会结束，但用户的实际目标尚未实现？技能完成后，用户还必须手动做什么？
• 阻力：哪些地方让用户在价值较低的决策点停下来（Claude 本可以采用合理的默认方案），或者在价值较高的时机跳过用户输入（用户对此有强烈偏好）？

按类型记录发现：卡点、分歧点、未达成目标的终点、阻力点。

---

2b — 实时文档验证

找出技能中所有涉及外部标准的事实性声明：frontmatter 字段名称、 Claude 工具名称及行为、API 参数、CLI 标志、第三方服务接口。

根据当前文档逐项验证：

For Claude-specific claims (frontmatter options, tool names, model IDs):
  Use Task tool with subagent_type=claude-code-guide — faster and more accurate than WebSearch.

For third-party claims (npm packages, APIs, external CLIs):
  Use WebSearch or WebFetch against official documentation.

标记技能描述与当前实际情况之间的偏差。严重性：如果声明会导致输出无法正常工作，则为高；如果会提供过时的指导，则为中；如果只是名称变更且不影响行为，则为低。

---

2c — 功能邻接扫描

根据技能的用途，找出尚未涵盖但价值很高的功能：

• 邻接功能：自然延伸技能现有功能——属于同一领域，再向前推进一步。刚运行完此技能的用户几乎肯定会想接着使用它。
• 互补功能：通常在此技能之前或之后需要。用户目前会手动完成这项工作。
• 端到端缺口：技能启动了一项工作，但用户还得手动完成——工作流停留在“这是一个计划”，而用户想要的是“并将其应用”。

对每个候选项：估算实现工作量（一处指令变更、新增阶段或新脚本）和用户价值（罕见的边缘情况、常见场景，或在关键场景中会阻碍技能使用）。

---

2d — 用户体验流程审查

评估技能的交互设计：

• 技能是否在开始时就提出所有必要问题（重度工作开始之前），还是会在工作流中途打断用户，提出用户未曾预料的问题？
• 是否明确说明“我不知道”时该怎么办？如果用户在没有具体问题的情况下触发技能，技能能否妥善处理，还是会假定用户知道该怎么做？
• 输出格式是否符合用户的使用方式？用户只需阅读一次的报告可以采用紧凑的散文形式；需要反复执行的报告则需要更清晰的结构。
• 是否存在技能在未经用户输入的情况下自行做出重大决定的步骤？

---

2e — 边缘情况压力测试

走完主要流程（2a）后，刻意尝试破坏技能。找出 3–5 个用于测试故障模式的对抗性输入：

• 缺失或格式错误的输入：预期文件不存在、路径错误，或参数为空或乱码时会发生什么？
• 相互矛盾的要求：如果用户的目标与输入冲突，会发生什么？（例如，在一个并非技能的文件上要求“改进这个技能”。）
• 不受支持的配置：如果技能遇到其设计范围之外的结构，会发生什么——不同的框架版本、边缘情况项目布局或意外的文件格式？
• 边界条件：输入非常大（500 行的 SKILL.md）、非常小（空文件），或路径／名称中含有特殊字符时会发生什么？

对每个对抗性输入，评估：技能是否能检测到问题并给出有用的错误提示、是否会悄然生成错误输出，或是否会导致工作流崩溃。将发现的问题对应到改进类型：缺少错误处理 → 新功能；失败提示不佳 → 用户体验改进；未检测到错误状态 → 准确性修正。

完成全部五项子分析并记录发现后，阶段 2 即告完成。

阶段 3：改进提案

在编写报告前，加载 ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-report-template.md，了解输出格式。必要时参考 ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/examples/sample-analysis.md，把握分析的深度与具体程度。

按改进类型归类展示发现——用户考虑的是结果，而不是审计维度。每项必须包含：方括号中的子分析代码、缺口所在、其对用户的重要性，以及具体修复方案。根据 references/effectiveness-rubric.md 中的标准校准严重性。

询问：“要应用所有改进吗？还是选择特定的改进？”

交付报告并确认用户的选择后，阶段 3 即告完成。

Phase 4：应用改进

按顺序应用已确认的项目：新功能 → 准确性修复 → UX 改进 → 效率提升。

对于每个项目：

• 说明将进行哪些更改以及原因——引用有效性原则，而不是说“你要求的”
• 进行编辑或创建文件
• 确认更改与周边内容顺利整合

应用后，简要说明：

• 更改了什么以及原因
• 添加了什么以及原因
• 哪些内容未纳入以及原因（投入大于收益，或需要用户提供领域知识）
• 哪些内容未被选中——注明之后仍可应用

验证： 提交说明后，通读修改后的 SKILL.md，并确认：所有选中的改进均已落实，周边内容未被意外更改，各阶段仍有编号和退出条件，且所有引用均指向现存文件。

当所有已确认的项目均已应用、说明已提交，且验证未发现整合问题时，Phase 4 即告完成。

Phase 5：结构 lint

应用有效性改进后，调用 skill-lint Agent 进行结构质量检查：

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

等待 Agent 完成。如果它自动应用了结构修复，请将这些修复与 Phase 4 的有效性改进一并说明。如果它报告了轻微问题，请告知用户。

当 lint Agent 返回，且用户选中的任何轻微修复均已应用后，Phase 5 即告完成。