# Skill Optimizer

> 诊断、优化、升级、改善任何 Codex Skill 的性能与能力。当用户要优化 skill、提升 skill、改 skill、skill 不触发/触发打架、skill 输出不稳定不专业、skill 太啰嗦被截断、给 skill 体检、重写 skill 描述、搭 skill 评测、做 skill 审计、检查 skill 安全性/稳定性、根据体检报告系统优化 skill、把方法论做成 skill、按规范打包 skill 时触发。体检必须输出完整 Skill 诊断报告；优化必须先基于体检报告形成系统化待确认执行计划，经用户确认后再修改，不能只给总分或泛泛建议。不适用于：从零写一个全新业务 skill（用 skill-creator）、非 skill 的普通文档撰写、具体业务问题本身（如选品/广告投放）。

- Skill: `juneleetime/skill-optimizer` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add juneleetime/skill-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/juneleetime/skill-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: juneleetime (https://skillmd.com/u/juneleetime)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/juneleetime/skill-optimizer

---


# Skill Optimizer · 优化 Skill 的 Skill

把一套完整的 Skill 优化方法论（6 思维模型 + 21 工程方法 + Codex 5 大机制）固化成可执行流程。
你的职责：**对目标 Skill 做诊断 → 输出完整体检报告 → 按报告生成系统化待确认执行计划 → 等用户确认 → 再修改、复验并沉淀**。

**硬性要求**：只要用户要求「体检 / 审计 / 诊断」Skill，最终回复必须给出完整 Skill 体检报告；禁止只回复总分、评级、几条建议或“已通过”。脚本分数只是输入材料，不是最终交付物。
**优化要求**：只要用户要求「优化 / 升级 / 改善」Skill，必须先用体检报告定位问题，再按「红线 → 高 ROI → 维度深挖 → 回归沉淀」生成待确认执行计划；用户明确确认后，才能进入文件修改。

> 本 Skill 自身就是「方法 #20 用 skill 造/优化 skill」的实例，遵循它自己倡导的全部规范。

---

## 第 0 步：先锁定优化维度（不可跳过）

不先定义指标就优化 = 盲调。先判断用户要解决哪一类问题（可多选）：

| 维度 | 典型症状 | 主攻方法 |
|------|----------|----------|
| **结构与上下文健康** | SKILL.md 过长 / 分层混乱 / 引用缺失 | #1 分层加载、机制① 字符预算 |
| **触发与路由质量** | 不触发 / 触发打架 / 误触发 | #5 描述工程、#6 编排器、机制③ 触发开关 |
| **任务契约清晰度** | 用户给什么不清楚 / 输出边界不清楚 | #8 IPO 契约、#9 中间产物 |
| **执行流程可操作性** | 只能靠经验判断 / 路径不稳定 | 模型4 决策树、#11 错误处理 |
| **输出稳定性** | 每次格式都不一样 / 需大量手改 | #2 Few-shot、#3 模板、#4 反例 |
| **运行稳定性与故障恢复** | 工具失败就中断 / 缺文件缺权限无降级 / 不可重复执行 | #11 错误处理、#14 回归、#16 可回滚 |
| **工具化与确定性** | 字符数、统计、预算等手算不稳 | #10 脚本化、#11 健壮性 |
| **评测与回归能力** | 不知道改完是否更好 | #12 Golden Set、#13 对比、#14 回归 |
| **沉淀与演进** | 踩坑没有复利 / 版本不可追踪 | #15 Patch、#16 Changelog、#17 反馈钩子 |
| **安全与边界** | 真实写操作、敏感数据、账号权限、外部发布边界不清 | #5 反触发、#11 友好报错、#16 可回滚 |
| **可维护性** | 后续维护者接不住 | #18 协作、#19 依赖声明、#20 工厂化 |

➡️ 维度不明时，先问用户一句，或先跑 `scripts/health_check.py` 自动定位。

---

## 本 Skill 的 IPO 契约（喂什么 / 得到什么）

**INPUT（任选其一即可启动）**
- 目标 Skill 的目录路径（最优，可跑脚本）；或
- 目标 Skill 的 `SKILL.md` 全文 / 片段（无目录时）；或
- 一份待 Skill 化的方法论 / 文档（走路径 C）；或
- 一句症状描述（如「这个 skill 不触发」「输出太飘」）

**OUTPUT（标准交付物，对应 `assets/diagnosis_report_template.md`）**
```
1. 优化维度锁定（结构/触发/契约/流程/输出/运行稳定/工具/评测/沉淀/安全/维护）
2. 体检总览（health_check.py 输出总分 + 全部维度分 + 红线项 + 检查项分布）
3. 诊断结论（整体判断 + 优先关注维度 + 风险排序）
4. 触发审计（字符数/超预算/触发冲突，health_check.py --skills-root 或 audit_description.py）
5. 安全与稳定性专项审计（权限/敏感信息/写操作/幂等/降级/外部依赖）
6. 已做到清单（保持项）
7. 待优化清单（按 ROI 🥇🥈🥉 排序，每条带：问题→方法编号→动作→预期收益）
8. 待确认优化计划（改动对象 + 具体动作 + 验收方式 + 风险提示）
9. 确认状态与执行记录（未确认则写“待用户确认”；确认后写 diff 摘要）
10. 验证结果（确认修改后的体检 + JSON 回归 + 触发冲突审计；未运行须说明原因）
11. 沉淀（确认修改后写入目标 SKILL.patch.md 的条目或说明不适用）
```
> 缺目录路径时降级：跳过脚本项，仅做人工清单诊断，并在报告标注「未跑脚本」。

## 完整体检报告硬性结构（不可省略）

当用户要求「给 Skill 体检 / 审计 / 诊断」时，最终回复必须按下列结构输出。没有数据的章节也要保留，并写明「未运行 / 不适用 / 需人工复核」：

1. **结论摘要**：总分、等级、红线项数量、整体判断。
2. **维度得分表**：列出全部维度，不能只展示低分维度。
3. **红线项**：无红线也要写「无」。
4. **触发审计**：description 长度、触发词前置、反触发、跨 Skill 冲突。
5. **安全与稳定性专项审计**：真实写操作、敏感信息、权限确认、备份回滚、幂等、重试/降级、依赖失败。
6. **检查明细证据**：每个 WARN/FAIL/MANUAL/SKIP 至少给证据和建议。
7. **ROI 修复清单**：按优先级排序，写清动作和预期收益。
8. **系统化待确认执行计划**：把每个待优化项拆成改动对象、具体动作、验收方式和顺序。
9. **确认状态与执行结果**：确认前写“待用户确认”；确认后说明改了什么、跑了什么、没跑什么。
10. **沉淀记录**：确认修改后说明是否写入 `SKILL.patch.md`。

## 报告驱动优化闭环（优化时不可跳过）

当用户要求「优化 Skill」时，不能只给体检报告，也不能直接修改。必须把报告转成待确认执行队列，等用户确认后再改：

1. **红线先修**：`FAIL`、`blocker`、真实写操作缺边界、缺 `SKILL.md`、坏 frontmatter、诊断类只给分等必须优先处理。
2. **高 ROI 次之**：按 `topFixes` 和 `optimizationPlan` 的 🥇🥈🥉 顺序处理；同优先级先处理影响触发、输出稳定、安全和回归的项。
3. **逐维深挖**：每个低于 90 分或存在 WARN/MANUAL/SKIP 的维度，都要说明根因、改动对象和验证方式。
4. **等待确认**：输出计划后暂停，明确提示“确认后我再修改”；不得在确认前改 `SKILL.md`、`assets/`、`references/`、`scripts/` 或 `agents/openai.yaml`。
5. **确认后执行**：用户确认后，按确认范围修改；如果用户只确认部分项，只改被确认的项。
6. **复验闭环**：确认修改后至少重跑文本体检；能跑时再跑 JSON 和 `--skills-root` 触发冲突审计。
7. **沉淀回归**：实质性改动经确认后写入 `SKILL.patch.md`；新增规则或防退化点要补 `golden_set.md`。

---

## 核心工作流（7 步 SOP）

```
① 定维度   → 锁定触发/质量/稳定/效率（上表）
② 拆契约   → 画 IPO，确认输入输出 Schema 与上下游对齐         [模型3 + 方法8/9]
③ 显性化   → 把隐性专家判断写成决策树 + 显式阈值              [模型1/4]
④ 加护栏   → 模板化输出、强制推导、合规校验、分层防截断        [模型5 + 方法1/3/10]
⑤ 建评测   → 5-10 真实案例 + 基准答案（golden set）          [方法12]
⑥ 跑对比   → eval + 方差分析 + 回归测试                       [方法12/13/14]
⑦ 沉淀     → 失败案例写 SKILL.patch.md，更新版本号            [模型6 + 方法15/16]
```

> 完整方法论细节在 `references/methodology.md`，**按需加载，不要一次性全读**。

---

## 快速执行路径（按用户诉求选一条）

### 路径 A：给某个 Skill 做体检
1. 读目标 Skill 的 `SKILL.md`（只读 frontmatter + 骨架）。
2. 运行 `python scripts/health_check.py <skill目录>` → 输出总分、11 维度分、红线项、Top ROI 修复建议。
3. 需要结构化数据时运行 `python scripts/health_check.py <skill目录> --format json`。
4. 需要触发冲突审计时运行 `python scripts/health_check.py <skill目录> --skills-root <skills根目录>`。
5. 对照 `references/checklist.md` 补充人工判断。
6. 用 `assets/diagnosis_report_template.md` 输出完整诊断报告（维度分/红线项/触发审计/安全与稳定性专项/待优化清单按 ROI 排序）。禁止把脚本输出的总分当作最终答案。
7. 如果用户说的是「优化」而不只是「体检」，先输出报告和 `optimizationPlan` 待用户确认；确认后再按计划修改、复验和沉淀。

### 路径 B：解决「触发打架 / 不触发」
1. 运行 `python scripts/audit_description.py <skills根目录>` → 算每个 description 字符数、标出超 8000 预算、检测触发词重叠。
2. 读 `references/codex-mechanics.md` 机制①③。
3. 把 description 重写成**倒金字塔**（触发词前置）；易冲突的次要 Skill 配 `allow_implicit_invocation: false`（用 `assets/openai.yaml.template`）。

### 路径 C：把一份方法论/文档做成合规 Skill
1. 读 `references/codex-mechanics.md` 确认 Codex 规范。
2. 按本 Skill 自身的目录结构搭骨架：`SKILL.md`（骨架+描述）+ `references/`（细节）+ `scripts/`（计算）+ `assets/`（模板）+ `agents/openai.yaml`。
3. description 用倒金字塔写法；数学/统计逻辑放 `scripts/`。
4. 用 `scripts/health_check.py` 自测，再按路径 A 体检。

### 路径 D：搭评测闭环
1. 读 `references/methodology.md` 的方法 #12-14。
2. 准备 5-10 真实案例 + 专家基准答案（golden set）。
3. 参考 Codex 官方 [Agent Improvement Loop Cookbook](https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop)。
4. 改前改后跑同批输入对比，量化提升，跑回归测试防退化。

---

## 铁律（违反则优化无效）

1. **先量化，后优化** —— 没锁定维度不动手。
2. **触发词前置** —— Codex 初始列表 ≈2% 上下文 / 8000 字符会被截断，description 第一句必须是核心触发场景。
3. **数学不交给 LLM** —— 出价/预算/统计/格式转换一律进 `scripts/`。
4. **改完必回归** —— 跑历史案例，确保没把旧能力搞坏。
5. **踩坑必沉淀** —— 写进目标 Skill 的 `SKILL.patch.md`，复利最值钱。
6. **改前先备份/记版本** —— 更新版本号 + changelog，可回滚。
7. **体检必交完整报告** —— 分数、等级、Top ROI 只是报告的一部分；安全、稳定、触发、证据、未运行项和验证结果都必须交代。
8. **优化必须跟报告走并等待确认** —— 不得跳过报告直接凭感觉改，也不得在用户确认前修改文件；每个实质性改动都要能追溯到报告中的维度、检查项或人工复核项。

---

## 禁止事项（反例 · 这样做 = 优化失败）

- ❌ **不锁定维度就开改** —— 凭感觉调，无法验证是否变好。
- ❌ **靠 LLM 手数字符 / 手算重叠** —— 必须跑 `audit_description.py`，人眼会错。
- ❌ **把方法论全文塞进 SKILL.md** —— 违反分层加载，挤占 8000 预算。正确做法：进 `references/`。
- ❌ **description 写成「这是一个专业的……」开头** —— 触发词埋后半段会被截断。正确：第一句=动作+对象+触发词。
- ❌ **改完不跑回归就交付** —— 可能修了 A 弄坏 B。必须重跑 `health_check.py` + 历史案例。
- ❌ **触发打架只改描述不动开关** —— 描述层治标；根治要给次要 skill 设 `allow_implicit_invocation:false`。
- ❌ **诊断只报问题不给 ROI 排序和具体动作** —— 用户无法执行。每条必须带「方法编号→动作→预期收益」。
- ❌ **体检只报总分/评级** —— 用户无法知道风险来源。必须输出完整报告结构，尤其不能省略安全与稳定性专项审计。
- ❌ **未确认就修改文件** —— 用户要求优化时，先交完整体检报告和待确认执行计划；只有用户确认后才能改文件、复验和沉淀。

---

## 资源索引（渐进式披露 · 按需加载）

| 文件 | 内容 | 何时读 |
|------|------|--------|
| `references/methodology.md` | 6 思维模型 + 8 层 21 方法全文 + ROI | 需要方法细节时 |
| `references/codex-mechanics.md` | Codex 5 大独特机制 + 映射表 + 官方最佳实践 | 涉及 Codex 适配时 |
| `references/checklist.md` | 优化自检清单（10 项打钩） | 体检/收尾时 |
| `references/examples.md` | Few-shot：优化前后对比范例 | 需要范例参照时 |
| `references/golden_set.md` | 评测基准（5 案例 + 期望诊断） | 回归测试 / 路径 D |
| `scripts/audit_description.py` | 扫描 description 字符数/超预算/触发冲突 | 路径 B |
| `scripts/health_check.py` | 输出 11 维度分、红线项、JSON、ROI 修复建议 | 路径 A/C |
| `assets/diagnosis_report_template.md` | 维度评分诊断报告模板 | 输出报告时 |
| `assets/patch_template.md` | SKILL.patch.md 模板 | 沉淀时 |
| `assets/openai.yaml.template` | Codex 元数据/触发开关模板 | 配触发开关时 |

---

## 优先级（资源有限只做这 6 件）
🥇 Golden Set + Eval（#12）→ 🥈 触发描述 + 编排器（#5/#6）→ 🥉 分层 + Few-shot（#1/#2）→ 脚本化（#10）→ Schema 契约（#8）→ patch 沉淀（#15）

---
_v1.5 · 本 Skill 随实践演进，新方法回填到 references 或本目录的 SKILL.patch.md。_