Skills Optimization Pro
> 评估驱动 · 模式指导 · 棘轮保障 · 渐进路由
核心循环：诊断→路由→优化→验证→记录
🚀 快速导航
| 场景 | 入口 | 流程 |
|---|---|---|
| 格式修复 | L1 Quick Fix | 检测→修复→结束 |
| 单技能优化 | L2 | Phase 1→2→3 |
| 全量评估 | L3 Phase 1 | 诊断→评分→报告 |
| 批量优化 | L3 | Phase 0→1→2→3→4 |
| 查看历史 | 读 results.tsv + CHANGELOG | 直接输出 |
路由决策矩阵
| 输入信号 | 路由级别 | 量化阈值 | 执行路径 | 预算 |
|---|---|---|---|---|
| frontmatter/格式问题 | L1 Quick Fix | YAML错误 / 缺name / 缺version / 触发词<3 / tags<2 / 缺序号 | 检测→修复→确认→结束 | 5K |
| 指定单个skill优化 | L2 单技能 | 1个skill名 + 评分<60→强制重组 / ≥60→精练优化 | Phase 1→2→3 | 20K |
| 批量/全量优化、评估 | L3 全量 | 2+个skill 或 "所有"/"批量"关键词 | Phase 0→1→2→3→4 | 50K |
路由规则：从L1开始检测，命中即执行并终止；未命中则降级到下一级。L2内部由Phase 1评分决定子路径。全局约束：max_skills=10, max_rounds=3, max_tokens=100K。
→ 输出: 路由级别 + 执行计划
评估速查（8维度，100分）
| 维度 | 权重 | 一句话标准 |
|---|---|---|
| Frontmatter | 8 | name规范、description含功能+触发词、≤1024字符 |
| 工作流清晰度 | 15 | 有序号、每步有输入/输出、Phase/Step结构 |
| 边界条件 | 10 | 有异常处理、fallback路径、错误恢复 |
| 检查点 | 7 | 关键决策前用户确认 |
| 指令具体性 | 15 | 有参数/格式/示例、可直接执行 |
| 资源整合度 | 5 | 引用路径正确可达 |
| 整体架构 | 15 | 层次清晰、无冗余遗漏、设计模式合理 |
| 实测表现 | 25 | 测试prompt输出符合skill宣称能力 |
评分：维度1-7各1-10分×权重；维度8跑2-3测试prompt打分×权重。详见 references/evaluation-rubric.md
反模式速查
| ID | 反模式 | 检测规则 | 严重度 |
|---|---|---|---|
| AP-1 | God Skill | >500行 或 3+不相关功能 | critical |
| AP-2 | Vague Instruction | 步骤含模糊动词无细化 | high |
| AP-3 | Missing Fallback | 无异常处理路径 | high |
| AP-4 | Trigger Blind | triggers<3 | medium |
| AP-5 | Checkpoint Absent | 无用户确认点 | high |
| AP-6 | Copy-Paste Drift | description与工作流不匹配 | medium |
| AP-7 | Over-Constrained | DO NOT>10条 | low |
| AP-8 | Zombie Reference | 引用路径不存在 | medium |
| AP-9 | Version Stale | version与CHANGELOG不一致 | low |
| AP-10 | Monologue Skill | 无交互点 | medium |
| AP-11 | Silent Failure | 有异常处理但无日志/通知/恢复动作 | high |
| AP-12 | Ghost Dependency | 引用未声明的工具或文件 | medium |
| AP-13 | Magic Number | 硬编码阈值无注释解释 | low |
critical/high→Phase 2优先修复；结果记录到anti_patterns列。关键词自动检测规则见 references/evaluation-rubric.md
设计模式速查
| 技能类型 | 推荐模式 | 优化点 |
|---|---|---|
| tool_calling | Tool Wrapper | 统一接口、错误重试、IO契约 |
| content_gen | Generator | 模板加载、变量收集、输出规范 |
| review | Reviewer | severity分级、checklist、结构化报告 |
| interaction | Inversion | 门控问题、偏好收集、交互决策点 |
| pipeline | Pipeline | 阶段checkpoint、进度可视化 |
| hybrid | 主+辅模式 | 主功能选主模式，次功能选辅模式 |
详见 references/design-patterns.md
版本规则
| 类型 | 变更 | 判定条件 |
|---|---|---|
| Patch | +0.0.1 | Quick Fix/格式修正；改动≤10行且无流程变更 |
| Minor | +0.1.0 | 应用模式/新增检查点/补充边界；改动≤50行或+1模式 |
| Major | +1.0.0 | 探索性重写/流程重组；改动>50行或涉及流程重组 |
执行流程
Phase 0: 初始化（L3专用）
| 步骤 | 动作 | → 输出 |
|---|---|---|
| 0.1 | 确认范围（全量扫描/用户列表） | 技能清单 |
| 0.2 | 全量备份每个目标技能 → zip（除了_BAK或backup类似目录的其他含目标技能的 SKILL.md + references + changelogs + _meta.json），命名 {skill-name}-backup-YYYYMMDD.zip，存储到目标技能根目录_BAK下 |
备份路径列表 |
| 0.3 | 创建分支 skills-optimization-pro/YYYYMMDD-HHMM |
分支名 |
| 0.4 | 初始化 results.tsv | 历史记录 |
强制规则：每次优化其他技能前必须先备份目标技能目录。无备份不启动优化流程。备份文件作为回滚基准点。
Phase 1: 诊断评估
| 步骤 | 动作 | → 输出 |
|---|---|---|
| 1.0 | 分类→推荐模式 | skill_type |
| 1.1 | 生成测试prompt（Happy/Ambiguous/Edge） | test-prompts.json |
| 1.2 | 基线评估（维度1-7打分+理由；维度8子agent或dry_run） | 评分卡 |
| 1.3 | 反模式扫描 AP-1~AP-13（含关键词自动检测） | anti_patterns |
| 1.4 | 优秀点+待优化清单+收益预估 | 对比分析 |
| 1.5 | 快速诊断扫描（评分<60时触发21项检查） | 诊断报告 |
| 汇总 | 展示评分卡+对比分析→用户确认→评分子路由→进入Phase2 | 确认 |
快速诊断扫描（评分<60触发）：执行21项诊断检查（详见 references/diagnostic-checklist.md）
| 类别 | 检查项 | 严重度 |
|---|---|---|
| Metadata (M1-M6) | name格式、description格式（"Use when"）、关键词覆盖、第三人称 | HIGH |
| Architecture (A1-A5) | 文件≤500行、渐进披露、引用深度≤1级、工作流清晰 | MEDIUM |
| Text (T1-T5) | Token合理化、假设Claude已掌握基础、术语一致、具体示例 | MEDIUM |
| Code (C1-C5) | 错误处理、魔术数需注释、依赖声明、Unix路径、验证步骤 | HIGH |
输出：按优先级分组的问题清单（HIGH→MEDIUM→LOW），每项含当前状态+修复建议+影响说明
评分子路由（L2内部）：评分<60→强制结构重组路径（优先修复critical/high AP）；评分≥60→精练优化路径（按最低维度迭代）。
收益对比规则：量化收益（分数提升）+ 质化收益（反模式消除/体验改善）+ 风险评估。
Phase 2: 优化执行
按基线分数从低到高，每个skill最多3轮：
| 步骤 | 动作 | → 输出 |
|---|---|---|
| 2.1 | 找最低维度 | 目标维度 |
| 2.2 | 选设计模式 | 模式选择 |
| 2.3 | 头脑风暴策略（见下方）→生成3方案→用户选择 | 改进方案 |
| 2.4 | 编辑SKILL.md + git commit | commit hash |
| 2.5 | 重新评估 | 新评分 |
| 2.6 | 棘轮决策（差值>+2或P0/P1改善→keep，否则→revert） | decision_reason |
| 2.7 | 记录 results.tsv | 日志行 |
头脑风暴优先策略：
| 优先级 | 策略 | 执行方式 |
|---|---|---|
| P0 | 调用 01_ProductManager_Brainstorming |
Skill工具→互动探索→用户选择 |
| P1 | 联网搜索 + 推理 | WebSearch + 评估 + 反模式 → 3方案 |
| P2 | 纯推理 | 设计模式库 + evaluation-rubric → 3方案 |
方案输出（P1/P2）：3方案各含[改什么/为什么/收益/风险]，推荐方案附理由。用户选择后进入 Step 2.4。
Phase 2.5 探索性重写（可选）：连续2个skill break→提议重写→用户同意→stash→重写→评估→对比→采用或恢复。
Phase 3: 验证确认
| 步骤 | 动作 | → 输出 |
|---|---|---|
| 3.1 | 子agent最终评分（含四类验证测试） | 最终评分 |
| 3.2 | 用户确认 | 确认 |
| 3.3 | 更新版本号 + changelog | 版本记录 |
| 3.4 | 输出物校验（见下方） | 校验结果 |
四类验证测试（详见 references/verification-guide.md）
| 测试类型 | 目标 | Pass Criteria | Fail Criteria |
|---|---|---|---|
| Trigger Test | 技能能否被正确发现和加载 | ✅ Skill discovered from description | ❌ Skill not found / Wrong skill loaded |
| Understanding Test | 工作流能否被正确理解和执行 | ✅ Workflow correctly identified | ❌ Steps out of order / Tools misunderstood |
| Execution Test | 能否完成实际任务（真实场景） | ✅ Expected output produced | ❌ Script errors / Unexpected output |
| Regression Test | 优化是否破坏已有功能 | ✅ All scenarios work as before | ❌ New errors / Different output |
测试prompt模板：每种测试类型都有标准prompt模板（见 references/verification-guide.md），包含：
- Trigger Test：模拟用户自然语言请求，验证技能发现
- Understanding Test：问答式验证工作流理解
- Execution Test：真实任务执行验证
- Regression Test：对比优化前后行为一致性
输出物校验清单：
| 输出物 | 必须/可选 | 校验方式 |
|---|---|---|
| 优化后SKILL.md | 必须 | 评分对比（新>旧） |
| 评分卡（前后对比） | 必须 | 8维度明细完整 |
| CHANGELOG条目 | 必须 | 版本号递增 |
| results.tsv记录 | 必须 | 字段完整 |
| 诊断报告 | L3必须/L2可选 | 含评分+AP+建议 |
| 新增/修改references | 可选 | 路径可达 |
Phase 4: 汇总报告
| 步骤 | 动作 | → 输出 |
|---|---|---|
| 4.1 | 展示优化数/实验次数/保留回滚比/分数变化/模式应用/版本变更 | 报告 |
| 4.2 | 跨技能挖掘（低分维度/常用模式/常见反模式/高成功率策略） | 全局建议 |
| 4.3 | 更新知识库 | 知识库更新 |
results.tsv
字段：timestamp | commit | skill | skill_type | old_score | new_score | status | dimension | note | eval_mode | design_pattern | decision_reason | anti_patterns
位置：.claude/skills/skills-optimization-pro-results.tsv
约束
| ID | 规则 |
|---|---|
| 1 | 不改变核心功能，只优化"怎么写"和"怎么执行" |
| 2 | 不引入新依赖 |
| 3 | 每轮只改一个维度（归因清晰） |
| 4 | SKILL.md ≤ 原始150% |
| 5 | git revert 回滚，禁止 reset --hard |
| 6 | 效果维度子agent或干跑验证（评分独立） |
| 7 | 每次优化记录 changelog |
禁止：改变核心功能 | 添加未授权依赖 | 跳过用户确认 | 自己评自己 | 无测试保留改进 | 忽略 changelog
使用方式
| 模式 | 触发语示例 |
|---|---|
| L1 Quick Fix | "修复格式问题" |
| L2 单技能 | "优化 example-skill" |
| L2 应用模式 | "应用 Reviewer 模式" |
| L3 仅评估 | "评估所有skills质量" |
| L3 全量优化 | "优化所有skills" |
| L3 批量 | "批量优化5个技能" |
| 查看历史 | "看看优化历史" |
关联资源
- references/evaluation-rubric.md — 评估标准 checklist + 反模式关键词检测
- references/design-patterns.md — 设计模式决策树 + 应用案例
- references/optimization-strategies.md — 优化策略 P0-P3
- references/best-practices.md — 最佳实践规则清单
- references/validation-cases.md — 验证案例量化数据
- references/diagnostic-checklist.md — 21项诊断检查点（Metadata/Architecture/Text/Code）+ 示例 + 严重度定义
- references/verification-guide.md — 四类验证测试（Trigger/Understanding/Execution/Regression）+ prompt模板
- references/quality-standards.md — 质量标准定义 + A-F评分体系
- references/report-templates.md — 诊断报告模板 + 结构化输出格式
