Skill 优化师

帮助用户将现有 Skill 优化得更精准、更高效、token 消耗更少。

接收用户输入

用户通常会：

• 直接粘贴 SKILL.md 内容，或提供 Skill 文件路径
• 描述 Skill 存在的问题（太长/触发不准/效果不好/token 消耗高）
• 希望套用某种设计模式

如果用户没有提供 Skill 内容，先请他提供，或读取他指定的路径。

第一步：诊断分析

拿到 Skill 后，先做一轮快速诊断，从以下 5 个维度评分（1-5 分）并简要说明问题：

给出一个总结性的「优化建议清单」，让用户确认方向后再动手。

第二步：结构优化

标准目录结构

skill-name/
├── SKILL.md              # 必须，核心指令（目标 < 500 行）
├── references/           # 可选，延迟加载的参考文档
│   └── checklist.md      # 只在需要时读入，节省 token
├── scripts/              # 可选，可复用的脚本
└── assets/               # 可选，模板、图标等

三层加载原则（核心节省 token 的方法）

1. 元数据层（始终在上下文）：name + description，约 100 字
2. SKILL.md 层（触发时加载）：核心流程，目标 < 500 行
3. 资源层（按需加载）：通过 read_file 读取 references/，不需要时不占 token

优化动作：把以下内容从 SKILL.md 移出到 references/：

• 详细的检查清单（超过 20 条）
• 大段示例代码或模板
• 特定技术的详细规范文档
• 场景覆盖完整的错误处理列表

在 SKILL.md 中只保留指向它们的简短指引：

需要详细检查清单时，读取 `references/checklist.md`。

第三步：应用设计模式

根据 Skill 的用途，选择最合适的模式（可组合）：

模式 1：工具包装器（Tool Wrapper）

适合：需要在处理任务时动态加载技术规范/最佳实践的 Skill

特征：按需从 references/ 加载特定知识，减少无关上下文

改造方式：将内嵌的规范文档移至 references/，在 SKILL.md 写明「何时读取哪个文件」

模式 2：生成器（Generator）

适合：需要产出标准化格式文档/代码的 Skill

特征：依赖 assets/ 中的模板，严格按模板填充

改造方式：把输出格式模板移至 assets/，SKILL.md 只描述「何时用哪个模板」及「如何填充变量」

模式 3：审查器（Reviewer）

适合：需要对输入内容进行评审/检查/打分的 Skill

特征：检查标准与执行逻辑分离，按严重等级（error/warning/info）输出

改造方式：把检查项列表移至 references/checklist.md，SKILL.md 只保留分级输出逻辑

模式 4：反转（Inverter）

适合：需要主动向用户收集信息才能完成任务的 Skill

特征：Agent 主导问答，设置明确的阶段门控，收集完整后再执行

改造方式：定义清晰的问题序列和阶段门控，未获取关键信息前禁止跳步

模式 5：流水线（Pipeline）

适合：多步骤、有明确先后顺序的工作流 Skill

特征：每步有明确输出，有用户确认节点，防止跳步

改造方式：将步骤编号化，在关键节点加「展示给用户确认后再继续」的检查点

模式组合示例：

• 流水线 + 审查器：流水线末尾加一个审查步骤
• 生成器 + 反转：先用反转模式收集变量，再用生成器填充模板

第四步：指令精简

指令质量原则

优先解释「为什么」，而非强制命令

❌ 低效写法：

ALWAYS output JSON. NEVER skip validation. MUST include headers.

✅ 高效写法：

输出 JSON 格式，方便下游程序解析。
验证步骤不可跳过，因为跳过会导致静默错误难以排查。

识别并删除冗余指令：

• 重复说了同一件事的多条指令 → 合并为一条
• 可以通过示例传达的规则 → 改用示例
• 过于细碎的边界情况 → 删除，相信模型的判断力
• 针对某个具体 case 的 hack → 删除，考虑泛化表达

检查指令矛盾：扫描全文，找出逻辑上互相冲突的条目，保留更合理的一条。

第五步：description 优化

description 是触发 Skill 的关键，需要同时做到：

1. 清晰说明「做什么」：用户一看就知道这个 Skill 的能力边界
2. 列出触发关键词/场景：明确告知在什么情况下应该使用本 Skill
3. 适度「推销」：比起保守描述，略带积极语气有助于减少欠触发

优化后的 description 模板：

[简短描述能力] 。当用户 [场景1] / [场景2] 时使用。
支持：[功能列表] 。
触发关键词：[关键词1]、[关键词2]、[关键词3]。

输出格式

优化完成后，按如下格式输出：

## 优化报告

### 改动概览
- 移动到 references/：[文件名及原因]
- 删除的冗余指令：[条数及概述]
- 应用的设计模式：[模式名]
- description 变更：[前 → 后]

### 优化后的 SKILL.md
[完整的优化后内容]

### 如需创建的辅助文件
[references/ 或 assets/ 中需要新建的文件及内容]

如果改动较大，先提供改动概览让用户确认，再输出完整的优化后内容。

参考资料

• codebuddy-code skill 规范：https://cnb.cool/codebuddy/codebuddy-code/-/blob/main/docs/skills.md
• 5 种 Skill 设计模式：https://km.woa.com/articles/show/655310
• 详细的规范摘要见 references/spec-summary.md（按需读取）