Skill 优化器

对已有 Skill 进行系统性审查、诊断与优化，确保其符合 Agent Skills v0.1 规范及业界最佳实践。

审查流程

按以下顺序执行，每个阶段发现问题后立即记录，全部完成后统一输出优化报告。

阶段一：结构合规检查

读取目标 SKILL.md，逐项检查以下硬性规范：

| 检查项 | 标准 | 来源 | |---|---|---| | YAML frontmatter 存在且格式正确 | 以 --- 开头和结尾，中间为合法 YAML | Agent Skills v0.1 | | name 字段存在且合法 | 仅小写字母、数字、连字符，最长 64 字符，不以连字符开头/结尾 | Agent Skills v0.1 | | description 字段存在且合法 | 最长 1024 字符，不含 <> | Agent Skills v0.1 | | 目录名与 name 一致 | skill-name/ 目录名必须等于 name 值 | Agent Skills v0.1 | | 无多余文件 | 不存在 README.md、CHANGELOG.md 等非必要文件 | skill-creator 规范 | | 资源目录规范 | 仅含 scripts/、references/、assets/，命名正确 | skill-creator 规范 |

也可运行 scripts/quick_validate.py <skill-path> 做基础结构校验。

阶段二：触发质量评估

重点评估 description 的质量——这是 Skill 被触发的唯一入口。

评估维度：

是否说明了"做什么" — 清晰描述 Skill 的核心能力
是否说明了"什么时候用" — 列出具体触发关键词和场景上下文
关键词覆盖率 — 是否穷举了用户可能的表达方式（中英文、口语化、同义词）
是否有负面排除 — 对"不要触发"的场景给出明确边界
是否积极触发 — Agent 倾向"少触发"而非"多触发"，description 应写得稍积极

常见问题与修复建议：

| 问题 | 示例 | 修复方向 | |---|---|---| | 太笼统 | "处理文档的技能" | 补充具体能力 + 触发关键词 | | 缺少触发词 | 只描述功能，没说什么时候用 | 补充"当用户提到 X/Y/Z 时触发" | | 太消极 | "仅在...时使用" | 改为"当用户提到 X、Y、Z 时触发" | | 硬编码示例 | "帮我把 input.md 翻译成英文" | 提升为通用场景描述 | | 无排除边界 | — | 补充"不要用于..."避免误触发 |

阶段三：内容质量评估

读取 SKILL.md 正文，评估以下维度：

写作规范：

| 检查项 | 标准 | |---|---| | 祈使句风格 | 用"提取参数"而非"Agent 应该提取参数" | | 解释"为什么" | 与其堆 MUST/SHOULD，不如解释原因让 Agent 理解意图 | | 篇幅控制 | 正文不超过 500 行，超出应拆到 references/ | | 通用性 | 不过度绑定特定示例，用理论指导代替硬编码特例 | | 避免冗余 | 同一信息不重复出现在 SKILL.md 和 references 中 |

内容完整性：

| 检查项 | 是否必要 | |---|---| | 快速开始 / 使用示例 | 推荐 | | 参数列表（如有参数） | 推荐 | | 工作流 / 执行步骤 | 核心 — 必须有 | | 错误处理 | 推荐 | | 资源引用说明 | 如有 scripts/references/assets 则必须 |

四级创作思维检查：

触发时机 — description 是否覆盖到位
输入与输出 — 是否明确参数和交付物
核心流程 — 步骤是否 3-7 步，先骨架后细节
边界与约束 — 错误处理、限制条件是否完备

阶段四：跨平台兼容性检查

检查是否存在平台污染（影响可移植性）：

| 污染类型 | 检测方法 | 修复方式 | |---|---|---| | 平台语法污染 | 正文含 @、/、! 等平台触发符（非引用） | 改为能力描述或用  注释隔离 | | 工具命名污染 | 写死 Bash、WebFetch、Read 等具体工具名 | 改为"调用 shell 命令执行 xxx"等能力描述 | | 路径环境污染 | 硬编码特定平台路径 | 改为相对路径或占位符 | | description 中性化 | description 中出现具体平台名（除非 Skill 本就只服务某一平台） | 移除平台名，改为通用描述 |

阶段五：资源目录审查

如技能包含打包资源，检查其组织是否合理：

| 资源类型 | 检查项 | |---|---| | scripts/ | 是否零依赖优先？是否有结构化输出（JSON）？是否有明确退出码？ | | references/ | 是否超过 100 行的文件有目录？SKILL.md 是否有明确的按需加载指引？ | | assets/ | 是否只存放输出用的静态资源（模板、图片、字体）？ | | 引用完整性 | SKILL.md 中提到的所有资源文件是否都存在？ |

阶段六：渐进式披露检查

验证三级加载机制是否正确实施：

元数据层 — name + description 是否在 100 词以内，触发信息充分
SKILL.md 层 — 是否控制在 500 行以内，是否只保留核心流程和选择指导
资源层 — 详细参考材料、模式、示例是否已拆到 references/ 中

反模式检测：

SKILL.md 超过 500 行且未拆分
references/ 中有文件但 SKILL.md 未提及何时读取
同一信息同时存在于 SKILL.md 和 references/ 中
references/ 文件层层嵌套引用（超过一层）

输出格式

审查完成后，输出结构化的 优化报告，包含：

报告模板

# Skill 优化报告：{skill-name}

## 总评
- **综合评级**：A / B / C / D（A=优秀 B=良好 C=需改进 D=不合格）
- **主要问题数**：{n}
- **建议优化数**：{n}

## 一、结构合规（{通过/不通过}）
| 检查项 | 结果 | 说明 |
|---|---|---|
| ... | ✅/❌ | ... |

## 二、触发质量（{评级}）
- 当前 description 评价：...
- 关键词覆盖：...
- 触发积极性：...
- 排除边界：...
- **优化建议**：...

## 三、内容质量（{评级}）
- 篇幅：{n} 行 {'✅ 合理' / '❌ 超出 500 行建议拆分'}
- 写作风格：...
- 完整性：...
- **优化建议**：...

## 四、跨平台兼容性（{评级}）
- 发现 {n} 处平台污染
- **问题清单**：...
- **修复建议**：...

## 五、资源目录（{评级}）
- ...

## 六、渐进式披露（{评级}）
- ...

## 优化行动清单（按优先级排序）
1. [P0] ...
2. [P1] ...
3. [P2] ...

评级标准

| 等级 | 标准 | |---|---| | A | 结构完全合规，触发精准，内容精简高效，跨平台兼容，资源组织合理 | | B | 结构合规，触发和内容有小幅改进空间 | | C | 存在 2-3 个明显问题（触发不准、内容冗余、篇幅超标等） | | D | 结构不合规或存在严重问题（缺少 frontmatter、description 无法触发、严重平台污染等） |

执行优化

报告输出后，等待用户确认。用户同意后，按行动清单逐一执行优化：

修改 SKILL.md 中的问题
调整目录结构（如需拆分内容到 references/）
对修改后的 SKILL.md 重新运行 scripts/quick_validate.py 验证
输出修改摘要

注意：执行优化前必须向用户说明将修改的内容，获得确认后再操作。不要擅自修改 Skill 内容。