skill-cleaner

技能清理器

对单个技能进行有针对性的编辑。目标是让版本读起来轻松流畅——无论是人类还是执行该技能的 Agent 都如此——不含相互矛盾的指令，同时保留充分细节并保护每项行为。 这通常意味着减少文字，但并非总是如此：如果一个技能篇幅较长是因为包含了真正重要的信息，就应该保持原样。篇幅不是问题，混乱才是。精简冗长段落、修正不合逻辑的结构，以及协调各章节之间互相冲突的指令，都有助于实现这个目标。减少行数只是副作用，绝不是目的。

技能会随着时间不断累积。每次事故都会添上一句话，每次修正都会多一个保留条件，每个新边缘案例都会增加一段。经过足够多轮之后，技能就会膨胀到模型无法在工作记忆中完整掌握的程度，结果反而比原始草稿更难遵循。这个技能正是对此的制衡：认真审视每一行，问问它“现在是否仍然发挥着作用？”

累积也会滋生矛盾：在后续步骤中补上的修正，可能悄然与早期步骤的规则冲突；而“参见 X 技能／参见步骤 Y”这样的指引，也可能把人引向与原指令相悖的内容。这些是最不该留下的严重缺陷——Agent 无法判断哪条指令优先，于是只能猜，而最终交付的就是猜测的结果。发现并解决这些问题，与删减赘述同样重要。

这个技能不是什么

• 不是改换文风。 不要强加另一种写作风格，不要引入新约定，也不要为了让文字听起来不一样而重写段落——要保留用户的表达风格。结构调整属于本技能的范围，但只能用于解决实际问题：把前提条件从过晚出现的位置移到前面，合并重叠或矛盾的章节，理顺突兀的过渡。原则是：只为解决真正的可读性或一致性缺陷而调整结构，绝不为了个人喜好。
• 不是更改功能。 不要添加新指令，不要扩大或缩小技能的作用范围，也不要修复你发现的工作流错误（指令本身有误）——应在报告中列出这些问题。解决两条现有指令之间的矛盾则不同，且属于本技能的范围：你不是在改变技能的作用，而是在让它只表达一种意思，而不是两种相互对立的意思。如果正确的解决方式确实不明确（双方看起来都像是有意为之），不要猜测——选择符合技能初衷的解读，并在报告中标记出来，让用户确认。
• 不是激进删改。 如有疑虑，就保留原句。过度删改的代价（几个月后出现无人能追溯的回归问题）远高于保留一段略显冗长的文字。

输入

用户（或调用方技能）会指定目标技能，通常通过路径（skills/<name>/SKILL.md）或简称（ship、ticket 等）指定。如果只给出简称，请在仓库根目录的 skills/ 下查找。如果指定了多个技能，请逐一清理，并为每个技能生成一份报告。

如果目标位于 .agents/skills/ 或 .claude/skills/ 中，请停止并告知用户。这些是通过 npx skills update 安装的外部元技能，任何编辑都会在下次更新时被覆盖。不在本任务范围内。

支持并鼓励自我清理。 skills/skill-cleaner/SKILL.md 与其他用户拥有的技能一样，也是有效目标——如果用户要求你清理自己，或者 skill-improver 的清理模式（参见 skill-improver 第 4b 步）将此技能选为候选对象，请对其执行相同的工作流程。只有一点不同：你正在阅读指令，并编辑指令所在的文件。首次编辑前，请将整个文件读入上下文，确保后续编辑不是基于过时内容进行。如果编辑超过两三处，请重新阅读相关部分。除此之外，流程完全相同——仍须执行第 0 步（查阅 skill-creator），适用相同的精简／保留标准，报告也照常交还给用户（或调用方）。自我清理往往最有价值：仓库中的其他技能都要依据这些标准进行评判，因此保持此技能本身精简，会直接影响今后的每次清理。

清理流程

第 0 步 — 依据 skill-creator 更新对“优秀”的理解

评判目标技能前，请阅读 .agents/skills/skill-creator/SKILL.md，具体阅读“Skill Writing Guide”和“Writing Style”部分。这是本仓库技能应遵循的风格：说明指令背后的原因，避免堆叠 MUST／NEVER，保持提示词精简，优先通过重新表述来改善，而不是施加严苛限制；对重复性工作配套提供脚本；大型参考文件采用渐进式披露。这些原则正是你要落实的要求——如果不先重温，就可能精简过度（把看似冗余的原因说明删掉），或精简不足（因为一连串 MUST 看起来“权威”就保留下来）。

如果仓库中没有 .agents/skills/skill-creator/，则遵循用户描述的风格，并在报告中说明你未能使用规范参考。

第 1 步 — 阅读整个技能

从头到尾阅读 SKILL.md，以及其中引用的任何配套 scripts/、references/ 或 assets/。只有了解该技能及其支持文件中的其他内容，才能判断某段文字是否冗余。请特别注意：

• Frontmatter 中的 description——它对触发技能至关重要，几乎不应缩短。
• 指向其他技能、脚本或文件的交叉引用——所有被引用的内容都必须继续可用。
• 如果技能的提交历史值得关注，请查看（git log -p -- skills/<name>/SKILL.md）。近期新增内容通常是对特定事件的防范措施，不要删掉其中的原因。

第 2 步 — 按清理标准标注各个部分

逐段检查技能并作出判断。以下类别是检查重点。请记录判断，但暂不进行修改。 可删减内容（通常可以安全删除或缩短）：

• 纯粹重复。 同一条指示在两处出现。保留最适合阅读的位置上的那一处；删除另一处。
• 重复显而易见的内容。 已经说明下一段内容的句子，或重复描述含义已由标题清楚表达的内容。
• 防御性铺垫。 一连串“必须／绝不／始终”，其实用一句说明原因的话就能达到同样效果。（参见 skill-creator 的写作风格指南——过度强硬地使用 MUST 是一个警示信号。）
• 填充语气。 “值得注意的是……”“请注意……”“如上所述……”“通常来说……”以及没有增加信息的结尾总结段。
• 过时的边缘情况。 某种情况几乎不会发生，且处理不当的影响范围很小，却为此写了整段内容。如果边缘情况虽罕见但后果严重（如数据丢失、强制推送等），则应保留。
• 不值得保留的示例。 示例只是重复上文内容，没有展示上文难以表达的内容。（能说明棘手情况、而这些情况难以通过文字轻松表达的示例很有价值，应予保留。）
• 过时的引用。 指向已不存在或已迁移的文件、脚本或外部系统的引用。

冲突与流程问题（最值得优先发现和处理）：

• 相互矛盾的指示。 一处要求执行某操作，另一处却要求不要执行，或暗示相反做法。Agent 无法判断该听哪一条，只能自行猜测。找出正确规则，并在所有相关位置统一 적용。若两条规则确实适用于不同情境，则应在两处明确说明边界（例如：“提交堆栈前执行 X；提交后绝不要执行 X”）——若不说明适用范围，即使规则本身并不冲突，读者也会觉得它们相互矛盾。
• 误导性引用。 “参见 X 技能”或“参见步骤 Y”之类的引用，其目标内容与引出它的指示相矛盾或不一致。应修正目标内容，或在引用处明确说明以哪条指示为准，避免读者面对相互冲突的答案。
• 同一指示，表述不一致。 这不只是纯粹重复，而是两个版本在细节上确实不同。选定正确版本，并统一两处内容；不一致的重复表述会造成隐性冲突。
• 流程顺序不当。 前置条件在依赖它的步骤之后才出现、提前引用后文定义的内容，或章节之间衔接突兀。应调整顺序，或添加一句过渡语，让内容自上而下顺畅易读。

可考虑重组的内容——你有充分的调整空间。只要能让技能更易读或让 Agent 更容易执行，就完全可以移动章节、合并章节或拆分章节。不要为了保留现有顺序而放任已发现的流程问题。请留意：

• 某章节在实际出现之前就已被引用或需要——将它提前，让读者按实际需要的顺序阅读。
• 设置、前置条件或背景信息位于依赖它的步骤之后。
• 两个内容相关的章节合并后是否更易读，或一个章节是否实际包含两个更适合拆分的主题。
• 一份较长且平铺的列表是否实际可以分成两个自然分组。
• 当前顺序是否迫使读者（或 Agent）在脑中记住某些内容，经过数个章节后才能用到——调整顺序，让每部分内容在需要时出现。

遇到明显能改善阅读或执行顺序的情况，就进行调整。调整时请注意两点：确保所有交叉引用仍然有效（“参见步骤 N”或按名称引用的章节在移动后仍能找到——必要时修正引用两端）；调整顺序必须确实能改善阅读或理解，不能仅仅出于个人偏好。仅仅打乱本来已很合理的章节顺序，只会造成无谓改动。 不要修改：

• frontmatter 中的 name: 字段。
• description: 字段，除非内容确实错误或包含过时引用——触发准确性取决于该字段，缩短它通常只会让触发效果变差，不会变好。
• 解释“为什么”的内容。如果某段文字解释了某条指令为什么重要，请保留——这些内容是关键背景，可帮助模型处理边缘情况，而不是只做模式匹配。
• 任何会限制破坏性或不可逆操作的内容（强制推送、硬重置、删除工作内容、发送外部消息）。
• 任何针对已知历史失败的内容——通常可以从提交消息（“fix: add guard against X”）或正文（“不要做 X——上次因此导致了 Y”）中看出来。
• description 字段中有助于触发的具体示例。

步骤 3 — 进行编辑

直接对 SKILL.md（以及适用时的任何附带文件）进行精简。使用 Edit 工具，而非 Write——保留所有未主动修改的内容。

编辑指南：

• 优先精简，而不是删除。将六行段落改写成两行，比直接删掉更能保留原意。
• 保持相同的语气。如果技能使用祈使句（“运行拉取器。阅读输出。”），不要改写成描述句（“拉取器会运行，然后阅读输出。”）。
• 如果某项精简尚不确定，不要把多项精简合并到一次 Edit 中——小而独立的编辑更容易审阅和还原。
• 每次编辑后重新阅读该部分。很容易删掉一句话，却让下一段留下一个无所指的“这意味着……”。

步骤 4 — 完整性检查

报告前，检查差异并确认：

1. 原技能中的每条指令都仍然保留，或已被有意精简（并在报告中列出）。
2. 内部交叉引用没有失效（按名称引用的章节仍然存在；其他地方引用的步骤编号没有重新编号；移动的内容从所有引用位置仍可正确定位）。
3. frontmatter 完好无损。
4. 技能从头到尾读起来连贯——没有悬空的过渡，也没有“如步骤 4 所述”之类指向已删除章节的内容。

如果有任何问题，请先修正，再撰写报告。

报告

编辑完成后，生成一份报告。内容要简洁具体，让用户能快速浏览并立即发现任何可能有异议、需要还原的内容。使用以下结构：

## Cleaned: skills/<name>/SKILL.md

**Reads better because:** <one-line summary of the net effect on flow, clarity, and consistency — this is the headline>
**Size:** <before> → <after> words/lines (secondary — note it, don't lead with it; "no net reduction, and that's fine" is a valid line)

### Conflicts resolved
- <the contradiction or astray-pointer you found, with the two sections involved> — <how you reconciled it, and which rule won>
(omit this section entirely if none were found)

### What got tightened
- <one-line description of the change> — <one-line why>
- ...

### What got removed
- <what was cut, with a short verbatim snippet or section name> — <why it wasn't pulling its weight>
- ...
(omit this section entirely if nothing was removed)

### What got restructured
- <what moved or merged> — <why it reads better this way>
(omit this section entirely if nothing was restructured)

### Left alone on purpose
- <anything you considered trimming but decided to keep> — <why>
(use this for non-obvious calls — don't list every untouched paragraph; the point is to show the user where you exercised restraint so they trust the calls you did make)

### Notes
- <anything you noticed but didn't act on — e.g. a workflow bug, an outdated reference, a section that might be a candidate for promotion to a separate skill>
(omit if nothing to flag)

“有意保留的内容”部分最有助于建立信任。如果你考虑过删除某段文字，但因为它解释了安全检查背后的原因而保留，请说明这一点——这能让用户知道你经过仔细阅读并有意作出取舍，而不是机械地压缩字数。

由其他技能调用时

如果调用方是 skill-improver（或其他自动化工具），而非直接调用的人类：

• 执行相同的工作流程，并生成相同的报告——将报告返回给调用方，以便纳入其发布内容中（例如 PR 正文）。
• 不要自行提交、创建分支或发起 PR。由调用方负责整体工作流程，并根据自身上下文决定如何将此次清理与其他修改配合。
• 如果认为没有值得清理的内容，请在报告中明确说明（“没有更改——该技能已经足够精简”）。调用方需要一个明确无歧义的信号。

校准

一次好的运行通常会：

• 让技能的内容从头到尾读起来更流畅，并解决各部分之间的矛盾——这是首要衡量标准，而不是行数。
• 在不丢失信息的前提下，精简冗长的段落，同时保留确实信息密集的部分。
• 主要进行小幅、独立的修改，并在有助于让技能更易阅读或执行时，自由移动、合并或拆分各部分。
• 保持技能的意图、语气和触发行为不变。

一次糟糕的运行会：

• 为了减少行数而删掉技能所需的信息——精简长度从来不是目标。
• 因为“为什么”的解释看起来像赘述，就把它们删掉。
• 为了让描述字段显得“更简洁”而删掉其中的具体信息——这会削弱触发效果。
• 为了重组而重组，或调整原本已经合理的章节顺序。
• 因为技能“本来就该知道”而移除安全防护措施。
• 因为解决实际矛盾感觉像是在“添加功能”，就放任矛盾存在——协调冲突指令属于清理工作，也在范围之内。
• 只列出行数，却不说明每项修改的理由。

如果目标技能确实没有问题，这同样算成功。说明这一点，然后结束。