# Skill Optimizer

> 审计并优化现有 Agent 技能，使其简洁、层次清晰、渐进式披露，且流程描述完备、语言规范、异常处理健全。当 SKILL.md 接近或超过 500 行、引用文件缺少明确指引、大型引用文件（>300行）需要目录、流程描述缺少五要素（触发条件/主流程/分支/异常/输出）、语言含模糊词、异常处理无错误码或降级路径，或用户要求重构、精简、重组或改进技能时使用。

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

---


# 技能优化器

围绕六个核心模式优化 Agent 技能：

**结构质量（模式1–3）**

1. **长度控制** — 保持 `SKILL.md` 在 500 行以内；接近上限时增加层次结构。
2. **清晰引用** — 每个链接文件都有明确的"何时阅读"指引。
3. **大文件目录** — 超过 300 行的引用文件包含目录。

**内容质量（模式4–6）**

4. **流程描述** — 执行流程覆盖五要素：触发条件、主流程、分支决策、异常处理、输出与副作用。
5. **描述语言** — 确定性语言，智能体第一视角，参数标识符化，数值量化，禁止暴露实现细节。
6. **异常处理** — 错误码携带语义，区分可恢复/终结错误，提供降级路径。

## 使用时机

当以下任一条件为真时触发此技能：

**结构质量触发**
- 技能的 `SKILL.md` 超过约 400 行（接近 500 行上限）。
- 引用文件链接未告知智能体*何时*打开它们。
- 引用文件超过 300 行且没有目录。

**内容质量触发**
- 流程描述缺少触发条件、分支决策或异常处理等核心要素。
- 流程描述含模糊词（`可能` `大概` `有时候` `尽量`）。
- 异常场景无错误码，或错误码无语义/无降级建议。
- 步骤描述暴露了内部实现（SQL、内存操作、私有函数名）。

**通用触发**
- 用户要求 `精简`、`重构`、`优化`、`拆分` 或 `改进` 技能。
- 技能感觉冗长、重复或难以导航。

如果以上均不适用，技能 `可能` 不需要优化 — 停止并报告此情况。

## 优化工作流

在每个优化任务开始时复制此清单并跟踪进度：

```
优化进度：
- [ ] 步骤1：审计技能（度量+检查）
- [ ] 步骤2：诊断哪些模式被违反
- [ ] 步骤3：规划重构（大型变更需用户确认）
- [ ] 步骤4：逐模式应用修复
- [ ] 步骤5：重新审计并验证

结构质量（模式1–3）默认始终检查。
内容质量（模式4–6）当技能包含执行流程描述时检查。
```

### 步骤1：审计

在目标技能目录上运行审计脚本：

```bash
python scripts/check_skill.py <技能目录路径>
```

脚本报告：
- `SKILL.md` 行数和 frontmatter 有效性。
- 每个引用文件的行数。
- `SKILL.md` 中的每个 markdown 链接及其是否带有 `何时阅读` 指引。
- 超过 300 行的引用文件是否包含 `## Table of Contents` 或 `## 目录` 段落。

如果脚本不可用，手动审计：读取 `SKILL.md`，统计每个文件的行数，检查链接上下文。

### 步骤2：诊断

将发现映射到六个模式。对每个违规记录严重程度：

| 模式 | 违规 | 严重程度 |
|------|------|----------|
| 长度 | `SKILL.md` > 500 行 | 高 — 必须修复 |
| 长度 | `SKILL.md` 400–500 行 | 中 — 主动增加层次 |
| 引用 | 链接缺少"何时阅读"上下文 | 中 |
| 引用 | 引用文件未被 `SKILL.md` 使用 | 低 — 考虑删除 |
| 目录 | 引用文件 > 300 行，无目录 | 中 |
| 流程 | 缺少触发条件或前置检查 | 高 — 智能体不知何时调用 |
| 流程 | 缺少分支/决策点 | 中 — 智能体遇异常无法处理 |
| 流程 | 缺少异常处理 | 高 — 智能体蒙眼狂奔 |
| 流程 | 缺少输出规格或副作用声明 | 中 — 智能体无法规划后续 |
| 语言 | 含模糊词（`可能`/`大概`/`尽量`） | 中 — 推理歧义 |
| 语言 | 步骤暴露内部实现 | 中 — 噪音干扰推理 |
| 语言 | 数值未量化 | 低 |
| 异常 | 错误码无语义 | 中 |
| 异常 | 未区分可恢复/终结错误 | 中 — `可能` 无效重试 |
| 异常 | 无降级路径建议 | 低 |

### 步骤3：规划

编辑前，编写简短计划，列出将变更的文件及方式。对于非平凡的重构（拆分文件、重命名段落），需与用户确认。

### 步骤4：应用修复

逐模式应用修复。每个模式有专门的方案：

**结构质量**
- **长度控制** → 当需要拆分 `SKILL.md`、决定保留内联还是提取、或设计新层次结构时，阅读 [`references/length-control.md`](references/length-control.md)。
- **引用链接** → 当重写链接上下文或决定如何表述"何时阅读"指针时，阅读 [`references/reference-linking.md`](references/reference-linking.md)。
- **目录** → 当为超过 300 行的引用文件生成或更新目录时，阅读 [`references/toc-patterns.md`](references/toc-patterns.md)。

**内容质量**
- **流程描述** → 当补全流程五要素、审查分支完备性、或将模糊流程转为结构化描述时，阅读 [`references/flow-description.md`](references/flow-description.md)。
- **描述语言** → 当消除模糊词、修正技术实现泄露、或统一参数标识符格式时，阅读 [`references/flow-description.md`](references/flow-description.md)。
- **异常处理** → 当设计错误码体系、区分可恢复/终结错误、或补充降级路径时，阅读 [`references/flow-description.md`](references/flow-description.md)。

**不要**预先阅读所有引用文件。只阅读当前修复所需的那个。

### 步骤5：验证

重新运行审计脚本。一个优化良好的技能通过所有三项检查：

```
[OK] SKILL.md: 312 行 (< 500)
[OK] 所有 4 个引用链接都有"何时阅读"上下文
[OK] 所有 2 个超过 300 行的引用文件都有目录
```

如果仍有检查未通过，回到步骤4。

## 六大模式 — 快速参考

以下摘要足够应对大多数优化。仅在摘要不够时打开对应的引用文件。

---

**结构质量（模式1–3）**

### 模式1：长度控制

**规则**：`SKILL.md` 正文保持在 500 行以内。约 400 行时，主动增加层次结构。

**拆分信号**：
- 多个深度主题各占 50+ 行。
- 大量示例、边缘情况或 API 细节的列表。
- 仅在特定子工作流中需要的内容。

**拆分目标**：
- 将详细步骤移入 `references/<topic>.md`。
- 在 `SKILL.md` 中保留 3–6 行摘要 + 指向引用文件的指针。

**指针模板**（在 `SKILL.md` 中）：

```markdown
当需要<特定任务>时，阅读 [references/<topic>.md](references/<topic>.md)。
```

更多细节、决策树和前后对比示例：[`references/length-control.md`](references/length-control.md)。

### 模式2：引用链接

**规则**：`SKILL.md` 到支撑文件的每个链接都告诉智能体**何时**打开它。

**反面**：
```markdown
详见 [examples.md](examples.md)。
```

**正面**：
```markdown
当为多文件重构生成提交信息时，参阅
[examples.md](examples.md) 获取前后对比示例。
```

三种可接受的形式：

1. **条件式** — "当 X 时，阅读 Y。"
2. **任务导向式** — "要做 X，阅读 Y。"
3. **后备式** — "如果内联摘要不够，阅读 Y。"

保持引用只深一层 — `SKILL.md` 直接链接到文件，而不是链接到再链接更多文件的文件。

更多形式、反模式和重写方案：[`references/reference-linking.md`](references/reference-linking.md)。

### 模式3：大文件目录

**规则**：超过 300 行的引用文件在 H1 之后紧接目录。

**最简目录模板**：

```markdown
# <文件标题>

## 目录

- [段落一](#段落一)
- [段落二](#段落二)
  - [子段落](#子段落)
- [段落三](#段落三)

---

## 段落一
...
```

**优秀目录的规则**：
- 按顺序反映实际的 `##` 和 `###` 标题。
- 使用 GitHub 风格锚点（小写、连字符、无标点）。
- 到标题深度 3 为止；更深的嵌套会使目录杂乱。
- 将目录放在所有其他内容之上（仅 H1 之后）。

锚点生成规则、嵌套目录示例和自动化技巧：[`references/toc-patterns.md`](references/toc-patterns.md)。

---

**内容质量（模式4–6）**

### 模式4：流程描述

**规则**：执行流程描述必须覆盖五个核心要素。

**五要素**：
1. **触发条件与前置检查** — 必填参数、系统状态、权限要求。
2. **主流程（Happy Path）** — 有序步骤，每步以动词开头，说明动作和中间产物。
3. **分支与决策点** — `IF...THEN...ELSE` 结构，标注分支变量来源。
4. **异常与容错** — 失败类型 + 恢复动作（重试条件/次数、降级、用户决策）。
5. **输出规格与副作用** — 成功返回结构、失败错误格式、外部系统影响。

**推荐格式**：编号步骤式（最通用）。每个步骤用 `IF` 标注条件分支，明确成功/失败路径。

当需要撰写或审查流程描述、补全缺失要素时，阅读 [`references/flow-description.md`](references/flow-description.md)。

### 模式5：描述语言

**规则**：流程描述使用确定性语言，以智能体（“你”）为第一视角，禁止模糊词和内部实现细节。

**五条语言规则**：
- 禁止 `可能` `大概` `有时候` `尽量` — 每步结果给出明确断言。
- 参数与变量用 `` `标识符` `` 标注 — 与 JSON Schema 参数名一致。
- 时间与数值严格量化 — `5 秒超时` 而非 `短期超时`。
- 以 `你` 为主语 — `你收到返回码 0 时，表示成功`。
- 禁止暴露内部实现 — 不出现 SQL、内存操作、私有函数名。

当审查语言合规性、消除模糊措辞时，阅读 [`references/flow-description.md`](references/flow-description.md)。

### 模式6：异常处理

**规则**：异常处理描述必须自成体系，错误码携带语义，区分可恢复与终结错误，提供降级路径。

**错误码格式**：`ERROR_CODE | 可读消息 | Agent 下一步建议`

**两类错误**：
- **可恢复** — 参数缺失、权限不足、临时超时 → 引导用户补充或自动重试。
- **终结** — 账号封禁、服务永久不可用 → 终止任务并告知用户。

**必须包含降级路径** — 如有备用方案，在错误描述中直接建议。

当设计错误码体系、区分错误类型、补充降级路径时，阅读 [`references/flow-description.md`](references/flow-description.md)。

---

## 3C 规范

内容质量三个模式共同遵循“3C 规范”：

- **Complete（完整）** — Happy Path、分支、异常全覆盖，不让智能体在意外情况下“蒙眼狂奔”。
- **Clear（清晰）** — 确定性语言和智能体第一视角，避免歧义和实现细节。
- **Consistent（一致）** — 参数名、状态码、返回格式在整个技能库中保持统一。

## 约束

- 未经用户批准绝不删除内容 — 而是移动它。
- 保留 YAML frontmatter 中的 `name` 和 `description`，除非用户明确要求更改。
- 保持与原始技能一致的术语（优化期间不重命名概念）。
- 不要引入 Windows 风格路径（`scripts\foo.py`）；使用正斜杠。
- 拆分后，从头到尾重新阅读新的 `SKILL.md`，确认它仍可独立作为可用指南。
- 内容质量优化时，不替智能体做业务决策 — 只补全流程描述的缺失要素，不改变业务逻辑。
- 错误码一旦在技能库中定义，保持一致不复用同一码值表示不同含义。

## 工具脚本

`scripts/check_skill.py` — 针对三个模式审计技能目录。

```bash
python scripts/check_skill.py <技能目录路径>
```

所有检查通过时退出码为 `0`，否则为 `1`。可在 CI 中安全运行。

## 附加资源

**结构质量**
- [`references/length-control.md`](references/length-control.md) — 拆分策略、层次设计、前后对比示例。
- [`references/reference-linking.md`](references/reference-linking.md) — 指针措辞、反模式、重写方案。
- [`references/toc-patterns.md`](references/toc-patterns.md) — 目录模板、锚点规则、嵌套目录。

**内容质量**
- [`references/flow-description.md`](references/flow-description.md) — 流程五要素、语言规范、异常处理、3C 规范、完整示例。