skill-improver

Skill Improver

概述

改进现有技能。目标是提供有帮助的改进，而非打分——给出作者可以采纳的具体、按优先级排序的修改建议，而不是评分。你需要审查五个维度：机械性事实依据随附的 lint 工具，其余部分则依靠判断。

**核心原则：**每条意见都要附上建议的修正方案。

输入

• **必需：**技能目录路径（其中包含 SKILL.md），或 SKILL.md 文件路径。
• **可选：**技能的预期用途（若有说明）——用于判断名称和范围是否符合预期。

步骤

1. 以确定性方式收集机械性事实（脚本路径相对于此技能自身的目录。请从该基准目录运行脚本）：

   bash scripts/skill-lint.sh <skill-dir-or-SKILL.md>
   

   报告 frontmatter 有效性、名称格式、描述结构、SKILL.md 大小、推荐章节，以及被引用和孤立文件。将 [FLAG] 视为线索，而非结论。
2. 自行阅读 SKILL.md 和随附文件——lint 工具无法判断清晰度、范围或正确性。
3. 审查五个维度（指南），并将每项发现转化为具体修正方案。
4. **按影响从高到低排序。**优先指出会妨碍发现技能的问题（描述薄弱）或正确性问题。
5. 撰写报告（输出）。主动提出代为应用修改；如用户提出要求，则交由 superpowers:writing-skills 负责编写。

指南

维度	优秀标准
名称与范围	以动词开头、使用主动语态、目标明确单一。指出含糊或多用途的技能（建议拆分）。
描述	说明何时调用（触发条件／症状／情境），而非只说明功能——应写成 "Use when the user asks about slow queries or indexes"，而不是 "Analyze and optimize queries"。使用第三人称；以 "Use when" 开头。概述步骤会让 Agent 跳过正文——应指出这一点。
结构	优先采用概述、输入、步骤、指南、输出格式。指出缺失的章节，并建议内容应移至何处。
保持 SKILL.md 精简	正文保留工作流和判断依据；大量细节（API、长表格、大型示例）应放入 references/。指出臃肿之处，并说明应提取哪些内容。
参考资料／脚本／资源	机械性操作应使用确定性的脚本。可复用的上下文应作为参考资料。模板应作为资源。指出孤立文件和非确定性脚本。

请明确寻找最具价值的两个改进机会：提取（将适合放入 references/ 文件的内联内容移出常驻加载的正文，使其更精简）和确定性（将 Agent 执行不一致的文字步骤改为小型脚本，以便复现）。

输出格式

## Skill review: <name>

Strengths: <1-2 lines>

### Suggested improvements (highest impact first)
1. [<dimension>] <observation> -> <concrete fix>
2. ...

### Extraction & determinism opportunities
- <inline content -> references/file.md>, <prose step -> scripts/x.sh>

Overall: <1-2 sentences, specific and encouraging. No score.>

常见错误

• 只打分，不提供帮助——不要评分；每条意见都必须包含可执行的修正方案。
• 照抄 lint 结果——其标记只是输入；还要补充它无法提供的判断。
• 提取内容却没有目标位置——明确指出目标文件，以及要移入其中的内容。

脚本

• scripts/skill-lint.sh — 用于确定性机械检查（frontmatter、名称、描述、大小、章节、孤立／非确定性文件）。只读；传入技能目录或 SKILL.md 文件路径即可。

如果此处无法运行脚本（缺少 bash／某个工具，或使用其他操作系统）：不要放弃任务——这些脚本只会自动执行常见的 git／文本命令，因此可使用当前环境中的其他工具直接复现相同步骤。