repair-skill

技能修复

根据黄金标准审核并改进现有技能。与从头生成技能的 create-skill 不同，此技能既会诊断违规之处，也会找出差距——哪些内容有问题、缺少什么，以及如何提升质量。输出是一份涵盖所有维度的结构化改进计划。

阶段 1：加载技能

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

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

如果路径缺失或有歧义，请先使用 AskUserQuestion 澄清，再继续操作。

在进入阶段 2 前加载全部三个参考文件：

1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/skill-anatomy.md — 关于正确结构、 三级加载模型、目录类型定义、自由度、命名规范和正文规范的黄金标准。 第 5、6、7 维必需。
2. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/frontmatter-options.md — 完整的 frontmatter 字段目录、有效值、工具列表和工具选择框架。 第 1、2 维必需。
3. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/audit-calibration.md — 已知的误报模式：这些情况看似违规，实际上并非如此。避免在 D2（未填写 allowed-tools）、D4（Task/Skill 正文）和 D5（导向说明与路由）中过度标记。

满足以下条件后进入阶段 2：已读取 SKILL.md、已整理同级目录，并已加载全部三个参考文件。

阶段 2：审核

独立检查每个维度。对于每项发现，记录：维度代码、问题或缺失内容、违反的原则或未达到的黄金标准，以及所需的具体修改。评估完全部 7 个维度后进入阶段 3。

发现类型：

• 违规 — 存在与规则相矛盾的内容
• 差距 — 缺少有助于达到黄金标准的内容
• 改进 — 内容有效，但仍有显著的优化空间

严重程度：

• 严重 — 导致触发失效，或每次调用都浪费大量上下文
• 主要 — 降低泛化能力、可靠性或工作流正确性
• 次要 — 润色；技能可正常工作，但仍有提升空间

---

维度 1 — Frontmatter 质量

描述是技能中唯一始终处于上下文中的部分。这里的每个词元都会在每次会话中消耗预算。检查是否存在违规和遗漏：

违规项：

• 人称与表述方式： 描述是否采用第三人称（“This skill should be used when...”）？第一人称或祈使句的表述读起来像是要执行的指令，而不是要评估的触发条件。如果不符合，这是严重问题。
• 标量类型： 描述是否使用了 >（折叠标量）？| 字面标量会保留换行符，解析时可能产生意外空白。轻微问题。
• 触发短语是否真实： 引号中的短语是否是用户的原话——即用户实际会输入的确切词语？改述（“hook creation tasks”）的路由匹配率低于自然语言表达（“create a hook”）。如果是改述，则属于主要问题。
• 词元密度： 描述是否重复技能名称、解释技能的作用，或包含元评论？每个此类词元都是预算浪费。单个实例属于轻微问题；若普遍存在，则是主要问题。

遗漏项：

• 触发短语覆盖范围： 是否有 3–5 个或更多不同的短语？只有一个短语会遗漏同义表达。是否涵盖了从未听说过此技能的用户会使用的直白说法？覆盖稀少时属于主要问题。
• 缺少 argument-hint： 技能是否读取 $ARGUMENTS 或 $1/$2，却没有 argument-hint 字段？此提示会显示在自动补全中——缺少它意味着用户不知道该传入什么。轻微问题。
• 名称有效性： 技能名称是否使用小写字母和连字符，且不超过 64 个字符？命令名称是否以动词开头？是否在有助于明确路由时使用命名空间？这些约束可确保文件系统兼容性、命令行易用性和路由明确性。名称不符合要求时属于轻微问题。
• 触发准确性： 在脑海中生成 3 个应该触发此技能的提示词，以及 3 个不应该触发的提示词（来自相邻领域）。描述是否涵盖应该触发的提示词，并排除不应触发的提示词？覆盖稀少或误触发范围过广，都属于路由质量缺陷。覆盖稀少时属于主要问题。
• 词元预算： 描述是否超过 100 个词元？每个会话的成本会随着所有已安装技能的描述长度而增加。超过 150 个词元属于违规（主要问题）；100–150 个词元属于遗漏（轻微问题）——应优先保留触发短语，而不是说明性文字。
• 缺少排除性触发条件： 对于领域拥挤（多个技能关注点重叠）的技能，描述是否明确注明“Not for X”（不用于 X）？排除性触发条件有助于明确路由决策边界。轻微问题。

---

维度 2 — 执行修饰项

修饰项保留默认值并不代表错误——适用默认值时，不指定它们是正确的。审查时要查找不匹配（违规）和缺少配置（缺口）。

完整字段目录、模型选择表和工具选择框架，请参阅 frontmatter-options.md。

违规：

• 技能是否拥有不受限制的 Bash 权限，而使用受限模式（Bash(git:*)）也能满足需求？
• allowed-tools 中是否有技能从未使用的工具？无效条目只会增加干扰。

缺口：

• 技能是否会调用其他技能或生成 Agent，却未在 allowed-tools 中包含 Skill 或 Task？

• 技能是否需要在工作流中途让用户做决定，却未在 allowed-tools 中包含 AskUserQuestion？

• 技能是否从 $1 读取文件路径，却使用 Read 工具调用，而不是通过 @$1 内联注入？这浪费了一次工具往返。轻微。

• 是否可以使用动态内容语法（感叹号 + 反引号括起的命令）注入实时数据（git 状态、环境变量、文件树），而不是调用工具？如果技能的工作流一开始就执行不会出错的探测（git 分支、文件树、环境变量），且从不需要错误处理，则属重大问题；对于可能失败或需要根据退出代码分支的命令，则属轻微问题。

  之前（浪费工具往返）：

  1. Run `git log --oneline -5` using Bash
  2. Run `git diff --name-only` using Bash
  3. Analyze the results...
  

  之后（调用时注入，不调用工具）。 将这些 Bash 调用替换为：

  • 最近的提交：!`git log --oneline -5`
  • 已更改的文件：!`git diff --name-only`

  然后接着写类似“分析结果……”的说明。

  **注意：**反斜杠用于转义反引号，以免这段文档被执行——在实际技能中，应写成不带反斜杠的 !`cmd`。

---

维度 3 — 内涵式指令与外延式指令

陈述规则并说明理由，就能将规则推广到每一种输入。暗示规则的示例则要求阅读模型反向推导规则——需要两步推理，而非一步，且只覆盖该示例的形式。

违规：

• 是否展示了好坏对比，却没有明示原则？应先说明原则；对比用于佐证，而不是代替原则。
• “常见错误”或“坏例子/好例子”章节是否在承担本可由一句原则说明更高效完成的工作？重大。
• 删除示例后，规则是否仍然完整且可执行？如果是，示例就是多余的；如果不是，则说明规则尚未明确——请将其说明清楚。

缺口：

• 是否存在只告诉 Claude 做什么、却没有说明为什么的指令块？补充理由可帮助指令推广到当前示例未涵盖的边界情况。每个未涵盖的指令块均属重大问题。

维度 4 — Agentic 与确定性任务的划分

审查此维度前，请先读取 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md。 其中包含 用于识别脚本候选项的五种信号模式、CLI 设计惯例、 常见类型（init、validate、transform、package、query），以及用于 借助 create-cli 设计接口的委派模式。

技能会混合使用 LLM 引导的推理（Agentic）和脚本执行（确定性）。两者的划分 应当经过深思熟虑——请参阅 skill-anatomy.md 中的自由度表。

违规项：

• 在多次调用中重复或完全相同的代码块——这类确定性操作每次都会被重新生成。应将其放入 scripts/。 内联代码块会在每次运行时消耗上下文 token；脚本则无需加载即可执行。
• 描述确定性流程的文案——如果无论输入如何，步骤始终相同，那么使用脚本比要求模型重现这些步骤更可靠。
• 脚本已存在，但未在 SKILL.md 中引用——Claude 不会使用它们。 如果 SKILL.md 中没有说明何时以及如何调用脚本的引用，该脚本就无法参与技能工作流。严重。
• 含糊的脚本引用——“如有需要，运行验证脚本”不具备可操作性。 引用必须说明触发条件、确切的调用方式，以及如何解读 输出。轻微。

缺漏——将 script-patterns.md 中的五种信号模式应用到每个工作流步骤：

• 信号 1（重复生成）： 是否有步骤会在多次调用中生成结构相同、参数不同的内容？→ 参数化脚本候选项。严重。
• 信号 2（工具选择不明确）： 是否有步骤需要按脆弱的顺序组合多个标准工具，才能完成本可自然表示为单个函数的任务？→ 将此流程编写为脚本。严重。
• 信号 3（契约明确）： 是否有步骤的输入/输出格式明确到现在就能写出 --help 文本？→ CLI 候选项；委托 create-cli 设计。
• 信号 4（双重用途潜力）： 是否有步骤适合脱离技能工作流，在终端中独立运行？→ 从一开始就将其设计为规范的 CLI。
• 信号 5（一致性至关重要）： 是否有步骤需要确保相同输入始终产生完全相同的输出——不是“相似”，而是可复现？→ 使用脚本，而非 LLM 生成。
• 没有评判标准的判断步骤——“分析情况”属于 Agentic 步骤，但缺乏依据。 Agentic 步骤需要明确的考量标准，以及衡量结果是否良好的标准。每个未覆盖的步骤均属严重问题。

维度 5 — 冗长度与上下文效率

技能触发时，SKILL.md 中的每个词元都会加载到上下文中。检查那些消耗预算却无法改善结果的词元，以及 应放在 references/ 中的内容。

参考 skill-anatomy.md 中的大小约束表来评估严重程度。

违规项：

• 复述章节标题的正文 — “## Validation” 后面接着“In this section we will validate...”纯属冗余。每处为轻微问题。
• 模棱两可的措辞 — “you might want to consider”“it could be useful to”“generally speaking”。改为直接的祈使句或删除。每处为轻微问题。
• 用代码块说明一句话就能表达的原则 — 一组好/坏 YAML 对比通常可以归纳为一条意图明确的规则。如果这类模式频繁出现，则为严重问题。
• 将代码块改写成正文后丢失变量绑定 — 为后续步骤使用的工作流变量赋值代码块（BASE=...、BRANCH=...）有双重作用：既说明操作，也建立状态。若改写成正文时未保留这些绑定，后续 $VAR 引用就会失去绑定。改写时添加“推导工作变量”的前言，在正文中明确绑定每个变量。每处丢失绑定均为严重问题。
• 不同章节重复提供指导 — 同一条规则同时出现在“Best Practices”和“Common Mistakes”章节中。整合到一处。轻微问题。
• 正文中的“When to Use This Skill”章节 — 正文仅在触发后加载；此处的路由指导不会被路由决策读取。每次调用都会浪费词元。严重问题。
• 深于 H3 的标题 — 表明内容应放在 references/ 中。轻微问题。
• SKILL.md 超过约 500 行 — 需要将内容转移到 references/。严重问题。
• 多余的文档文件（README.md、CHANGELOG.md、INSTALLATION.md）位于技能目录中 — 它们永远不会加载到上下文中，只会给程序包增加噪声。每个文件均为轻微问题。

缺口：

• references/ 文件能否缩减 SKILL.md 的大小？ 找出仅特定子任务需要的章节，并标记为可转移内容。如果 SKILL.md 超过 300 行，则为严重问题。
• 是否需要用于存放领域专属数据的 references/ 文件？ 查找表、选项目录、字段定义——这些属于参考数据，而非操作说明。严重问题。

---

维度 6 — 工作流清晰度

技能的流程应当按顺序进行、完整，并在每个阶段设有明确的退出条件。检查工作流是否存在问题，以及 是否缺少有助于完善流程的结构。

违规项：

• 流程是否按编号阶段组织，并且每个阶段都有清晰名称？没有明确阶段，模型就无法跟踪进度，也不知道当前处于哪个步骤。若流程未结构化，则为严重问题。
• 每个阶段是否都有明确的退出条件？如果没有，模型就不知道何时停止当前阶段的迭代，可能会陷入循环或过早跳过步骤。若缺少退出条件，则为严重问题。
• 是否存在思路不完整的步骤——描述了意图，却未说明要做什么或如何评估结果的阶段？每个未覆盖的阶段均为严重问题。
• 技能是否能处理缺失、含糊或格式错误的输入？

缺口：

• 变量连续性： 步骤中引用的每个 $VAR 是否都在前面的步骤或预检/前言部分中明确绑定？扫描技能正文中的所有 $VARNAME，并追溯每个变量的来源。未绑定的变量会导致工作流中断——Agent 可能因命令无效而停止，也可能静默地将其替换为空字符串。每个未绑定变量均为严重问题。
• 是否有交付阶段说明 Claude 应生成什么内容以及采用何种格式？许多技能清晰地描述了流程，却未明确输出格式。若缺少，则为严重问题。
• 在工作流末尾添加验证清单是否有助于发现正文说明可能遗漏的错误？轻微问题。
• 添加 examples/ 目录是否有助于用户了解预期输出的样子？轻微问题。

维度 7 — 结构完整性

请参阅 skill-anatomy.md，了解标准目录结构和差距分析清单。本维度关注：技能的结构是否符合其复杂度层级？还缺少什么才能提升其层级？

直接使用 skill-anatomy.md 中的差距分析清单。 对每个回答“是”的项目，按相应严重程度记录一项差距。

违规项：

• 技能是否包含 scripts/ 目录，且其中的脚本未在 SKILL.md 中提及？ 严重 — 补充引用或删除。
• 技能是否包含 references/ 目录，且其中的文件未在 SKILL.md 中引用？ 严重 — 补充引用或删除。
• 命名是否违反规范（大写字母、下划线、超过 64 个字符）？轻微。

差距 — 对每个缺失的目录进行检查：

• 缺少 scripts/： 是否存在通过脚本执行会更可靠的确定性操作？同一代码块是否已经出现，或会在多次调用中出现？
• 缺少 references/： SKILL.md 是否超过 300 行？是否有仅在特定子任务中需要的章节？是否有特定领域的参考数据？
• 缺少 examples/： 技能是否会生成用户需要调整的输出？是否存在可通过有效示例比通过文字说明更清晰地解释的模糊指令？
• SKILL.md 中缺少资源指引： 是否存在未被引用的目录 — Claude 除非猜测去查找，否则无法看到？

---

阶段 3：改进报告

以结构化报告的形式呈现结果。将违规项与差距分开 — 违规项是现有问题，差距是尚缺少但能改进技能的内容。

SKILL IMPROVEMENT REPORT: <skill-name>
Current tier: [simple / standard / complex] — [lines] lines, [directories present]

VIOLATIONS
──────────
CRITICAL
  [D1] Description uses first-person — routing model reads as instruction, not trigger.
       Fix: rewrite as "This skill should be used when the user asks to..."

MAJOR
  [D3] Body teaches frontmatter quality by bad/good contrast; principle never stated.
       Fix: state the rule ("quoted phrases must be verbatim user speech because routing
       matches on literal tokens") then keep the contrast as confirmation.
  [D5] "When to Use This Skill" section in body — dead tokens every invocation.
       Fix: move routing guidance to frontmatter description, delete body section.

MINOR
  [D1] Description uses | scalar instead of >.
       Fix: change to >.

GAPS (what would improve this skill)
─────────────────────────────────────
MAJOR
  [D7] SKILL.md is 420 lines with no references/ directory. Three sections (option catalog,
       field definitions, examples table) are only needed for specific sub-tasks.
       Improvement: extract to references/; add load pointer in SKILL.md for each.
  [D4] File-path validation logic is inlined but must produce consistent output.
       Improvement: move to scripts/validate-input.py; reference from Phase 2.

MINOR
  [D2] Skill reads $1 as a file path but uses Read tool — @$1 injection would save a
       tool round-trip.
       Improvement: replace Read call with @$1 inline injection.
  [D7] No examples/ directory; skill produces config output users adapt.
       Improvement: add examples/ with one representative output file.

先按严重程度归类违规项，再按严重程度归类差距。对于每一项，说明维度代码、存在的问题或缺失的内容、未达到的原则或标准，以及具体修复方法。

询问：“要应用所有严重和重大项目吗？还是选择特定项目？”

---

阶段 4：应用改进

按以下顺序应用已确认的项目：严重违规项 → 重大违规项 → 重大差距 → 轻微违规项 → 轻微差距。

对于每一项：

• 说明要更改或添加的内容及其原因（引用原则，而不只是说“按你的要求”）
• 编辑内容或创建文件
• 确认更改与周边内容一致

说明你的选择

应用改进后，简要说明：

• 更改了什么以及原因 — 引用原则：“将描述改写为第三人称，因为第一人称表述会被解析为执行指令，而不是需要评估的触发条件”
• 添加了什么以及原因 — “创建了 references/options.md 并将选项目录移出，因为 SKILL.md 有 420 行，而该目录仅在配置子任务中需要”
• 哪些内容保持不变以及原因 — “hooks 保持未设置 — 无需进行生命周期验证”
• 用户还需处理哪些事项 — “examples/ 差距需要领域知识才能填补；已创建占位目录”

所有已确认项目都已应用、已提供说明，并且验证清单已通过后，阶段 4 才算完成。

---

验证

应用所有改进后，加载 ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/quality-checklist.md，先运行质量标准检查，再逐项运行验证清单。交付最终结果前，报告任何未通过的项目。