Skill Optimizer — STOM 自动化引擎
> 定位：对任意 SKILL.md 执行诊断→设计→实施的自动化优化工具。
> 方法论：基于 skill-creation-guide.md 中定义的 STOM v2.0 方法论。
适用场景
| 场景 | 示例 |
|---|---|
| 审计单个 Skill | "审计一下 tushare-data 的 token 效率" |
| 全量批量审计 | "审计所有 Skills，按大小排序" |
| 执行优化改造 | "把 harmonyos-app-dev 瘦身到 350 行以内" |
| 新 Skill 预检 | "我要新建一个 Skill，先帮我规划结构" |
| 健康检查 | "我的 Skills 有没有超标的？" |
不适用：修改 Skill 的业务逻辑（只管 token 效率，不管功能正确性）、创建新 Skill 的业务内容。
核心工作流
工作流 A：单个 Skill 审计（Audit）
输入：skill_name 或 SKILL.md 路径
Step 1: 读取目标 SKILL.md → 统计行数/大小/section分布
✅ checkpoint：行数/大小/section 数已记录到报告「基本信息」
Step 2: 逐 section 分析：
- 标记 L1(保留) / L2应移 / L3应删
- 识别表格压缩机会
- 识别重复内容
- 检测引用链风险
✅ checkpoint：每个 section 有 L1/L2/L3 分类标记
Step 3: 计算：
- 当前 token 估算 (行数 × 25 tokens/行)
- 优化后预估
- 节省比例
- 风险评级（低/中/高）
✅ checkpoint：4 个数值都已填写，风险评级有依据
Step 4: 输出审计报告（见 report template）
✅ checkpoint：报告含评分卡 + 问题清单 + 优化方案三段
工作流 B：全量审计（Batch Audit）
输入：--all 或 skills 目录路径
Step 1: 遍历所有 */SKILL.md → 统计行数+大小
Step 2: 排序（按行数降序）→ 标记超标项（>350行或>15KB）
Step 3: 对每个超标项执行「工作流A」的 Step 1-3（简化版）
Step 4: 汇总为全局报告：
- 总量统计
- TOP 10 最大 Skill
- 超标清单 + 各自优化建议
- 总节省潜力估算
工作流 C：执行优化（Optimize）
输入：skill_name + 审计报告（或 --auto 从头跑）
前置确认：
⚠️ 此操作将修改 SKILL.md 并创建 references/ 文件！
确认后继续：
Step 1: 运行审计（工作流A）→ 得到优化方案
Step 2: 创建 references/ 目录（如不存在）
Step 3: 将标记为 L2 的内容写入 references/ 子文件
Step 4: 在 SKILL.md 中替换为引用指针
Step 5: 插入「复杂任务检测」条件触发区块
Step 6: 更新 YAML frontmatter:
- version minor +1
- 添加 references 列表
Step 7: 验证：
- 新行数 ≤ 350？
- 引用指针指向的文件确实存在？
- 无引用链？
Step 8: 输出前后对比报告
审计维度与评分标准
维度 1：规模合规性（权重 26%）
| 等级 | 行数 | 大小 | 评分 |
|---|---|---|---|
| 🟢 优秀 | ≤ 250 行 | ≤ 10 KB | 10/10 |
| 🟡 合格 | 251-350 行 | 10-15 KB | 7/10 |
| 🟠 轻微超标 | 351-500 行 | 15-22 KB | 4/10 |
| 🔴 严重超标 | > 500 行 | > 22 KB | 1/10 |
维度 2：信息密度（权重 22%）
检测指标：
- 表格占比（表格行数 / 总行数）：>40% → 高密度
- Checklist 使用频率：有 checklist → 加分
- 平均段落长度：<5 行/段 → 密集
- 是否有大段纯文本（>15行连续段落）：有 → 扣分
评分：10（高密）~ 2（低密）
维度 3：分层合理性（权重 22%）
检测指标：
- L2 内容是否已移至 references/？是 → 加分
- 是否存在"参考型"内容留在 L1？有 → 扣分
- 引用指针是否清晰？模糊/缺失 → 扣分
- 是否有条件触发式的复杂任务检测？有 → 加分
评分：10（分层合理）~ 2（混乱）
维度 4：架构健康度（权重 20%）
检测指标：
- YAML frontmatter 是否完整？（name/version/description/references）
- 是否存在引用链风险？
- 踩坑经验区是否干净？
- 版本号是否合理？
评分：10（健康）~ 2（有问题）
维度 5：模型适配性（权重 10%，v1.2.0 升级）
> 审计 SKILL.md 对弱模型的友好度。详见 references/model-adaptation-audit.md。
检测方式（10/10 类覆盖）：
- 静态规则 7 类（M1-M5/M7/M10）：python scripts/step-ambiguity-detector.py <path>
- LLM 语义评审 3 类（M6/M8/M9）：审计 agent 执行 reference 中的评审 prompt
评分：10（弱模型友好）~ 2（易踩坑），按偏差类型覆盖度扣分（high -3 / medium -1.5 / low -0.5）
LLM 语义评审（M6/M8/M9，v1.2.0 新增）
审计 agent 按 references/model-adaptation-audit.md 的「LLM 语义评审 prompt 模板」执行，
输出 JSON 与静态扫描结果合并计算 D5 评分。完整工作流详见 reference「五、D5 维度审计工作流」。
综合评分
总分 = D1×0.26 + D2×0.22 + D3×0.22 + D4×0.20 + D5×0.10
（v1.0.x: D1×0.30+D2×0.25+D3×0.25+D4×0.20；
v1.1.0: D1×0.25+D2×0.20+D3×0.20+D4×0.20+D5×0.15；
v1.2.0: D5 降到 10%，从 D1/D2/D3 抽 4%/3%/3% 相对 v1.0.x 原始权重）
等级划分：
9.0-10 🏆 Gold → 无需优化
7.0-8.9 ✅ Silver → 小改即可
5.0-6.9 ⚠️ Bronze → 建议优化
<5.0 🔴 Fail → 必须优化
Section 分类指南（审计时用）
对 SKILL.md 中每个 ## 或 ### section 做分类：
| Section 特征 | 推荐分类 | 典型例子 |
|---|---|---|
| 包含接口/参数映射表 | L1 保留 | 意图→接口速查表 |
| 短 checklist（<20 行） | L1 保留 | 环境校验、输入规范 |
| 核心 3-7 条原则 | L1 保留 | 最佳实践 |
| 完整工作流模板（每步展开） | L2 移出 | 9 个任务模板详情 |
| 示例代码/对话（>10 行） | L2 移出 | examples |
| 详细错误处理矩阵 | L2 移出 | detailed-rules |
| FAQ 列表 | L2 移出 或删除 | faq |
| 完整 API 参数说明 | L3 外部/不存 | api-docs |
输出规范
审计报告格式
# Skill 审计报告：{skill_name}
## 基本信息
| 项目 | 值 |
|------|-----|
| 文件路径 | ... |
| 当前版本 | ... |
| 行数 | xxx / 350 (xx%) |
| 大小 | xx.x KB / 15 KB (xx%) |
| Section 数 | x 个 |
## 评分卡
| 维度 | 得分 | 权重 | 加权分 |
|------|------|------|--------|
| 规模合规 | x/10 | 30% | x |
| 信息密度 | x/10 | 25% | x |
| 分层合理 | x/10 | 25% | x |
| 架构健康 | x/10 | 20% | x |
| **综合** | | | **x/10 🏆/✅/⚠️/🔴** |
## 问题清单
| # | 类型 | 位置 | 说明 | 建议 |
|---|------|------|------|------|
| 1 | 超标 | L50-200 | 工作流模板占 150 行 | 移至 references/workflow-templates.md |
| ...
## 优化方案
### 建议移至 references/ 的内容（按优先级）
1. [ ] ...
2. [ ] ...
### 可压缩的内容
1. [ ] ...
### 预估效果
| 指标 | 当前 | 优化后 | 变化 |
|------|------|--------|------|
| 行数 | xxx | ~xxx | -xx% |
| 大小 | xx KB | ~xx KB | -xx% |
| Token(估) | ~xxxx | ~xxxx | -xx% |
## 风险评估
- 风险等级：低/中/高
- 主要风险点：...
- 缓解措施：...
详见 references/audit-report-template.md。
最佳实践
- 审计不修改：工作流 A/B 只读+分析，不动文件；只有工作流 C 才写文件
- 先审计后动手：永远先跑 Audit 再跑 Optimize，让用户看到报告再决定
- 保持业务逻辑不变：只做信息架构调整（移动/压缩/重构），不改业务含义
- 版本号必须更新：每次优化后 version minor +1
- 备份意识：重大改动前提醒用户当前版本信息（方便回溯）
与其他 Skill 的关系
| 关系 | Skill | 说明 |
|---|---|---|
| 依赖 | skill-creation-guide | STOM 方法论的权威来源，审计标准以此为准 |
| 输入 | 任意 SKILL.md | 审计目标 |
| 输出 | 被优化的 SKILL.md + references/ | 优化产物 |
| 协同 | strategic-compact | 优化后的 Skill 更适合 strategic-compact 管理 |
| 记录 | skill-creation-guide 末尾表 | 审计结果记录到「已审计 Skill 记录」 |
📚 踩坑经验
> 由 AI 在实际优化中积累。
> 清理规则：IF 删除记录 → THEN 必须满足（任一）：① 已在 CHANGELOG 沉淀为方法论变更；② version major +1 且 CHANGELOG 标注 deprecated。否则 → 保留原条目。
（暂无记录——等待首次实际使用）
CHANGELOG
- v1.2.0（2026-07-06）：D5 模型适配性能力升级。①检测覆盖度 7/10 → 10/10：新增 LLM 语义评审 prompt 模板（M6 指令干扰 / M8 思考泄漏 / M9 约定 vs 新奇），审计 agent 自身执行无需外部 API。②D5 权重 15% → 10%：综合评分公式调整为
D1×0.26+D2×0.22+D3×0.22+D4×0.20+D5×0.10（从 D1/D2/D3 抽 4%/3%/3% 相对 v1.0.x 原始权重）。③SKILL.md 瘦身：D5 详细检测指标 + Phase 4.5 工作流移至references/model-adaptation-audit.md，主文件 341→~305 行。④step-ambiguity-detector.py新增--merge-llm参数支持合并 LLM 评审结果。决策依据：完整 Binary Eval（per-skill 测试用例 + 实际执行）ROI 不够（开发成本高 + 执行成本高 + 通用性差），LLM 语义评审是更优方案（零依赖 + 零 API 成本 + 通用）。 - v1.1.0（2026-07-06）：新增「维度 5：模型适配性（权重 15%）」审计能力。从舆情监测 skill v1.4.x 实战 + ACL 2025 DIM-Bench + arXiv 2507.20439 + Skill Engineering 七原则 + Karpathy 规则 + anti-drift skill 综合提炼 10 类弱模型偏差模式（M1-M10），其中 7 类静态可检测。配套新增
references/model-adaptation-audit.md（偏差模式库） +scripts/step-ambiguity-detector.py（静态扫描器）。综合评分公式从D1×0.30+D2×0.25+D3×0.25+D4×0.20调整为D1×0.25+D2×0.20+D3×0.20+D4×0.20+D5×0.15（从 D1/D2/D3 各抽 5% 给 D5）。triggers 新增「弱模型适配」「步骤歧义检测」「指令遵循」「模型友好度」。 - v1.0.1（2026-07-03）：调整 displayName 为「Skill优化(Skill Optimizer)」，更符合中文市场命名习惯。
- v1.0.0（2026-07-02）：首次发布——基于 STOM v2.1 方法论的 Skill Token 优化器，自动审计 + 瘦身。
