cyrainfall 技能优化器
围绕六个核心模式优化 Agent 技能：
结构质量（模式1–3）
- 长度控制 — 保持
SKILL.md在 500 行以内；接近上限时增加层次结构。 - 清晰引用 — 每个链接文件都有明确的"何时阅读"指引。
- 大文件目录 — 超过 300 行的引用文件包含目录。
内容质量（模式4–6）
- 流程描述 — 执行流程覆盖五要素：触发条件、主流程、分支决策、异常处理、输出与副作用。
- 描述语言 — 确定性语言，智能体第一视角，参数标识符化，数值量化，禁止暴露实现细节。
- 异常处理 — 错误码携带语义，区分可恢复/终结错误，提供降级路径。
使用时机
当以下任一条件为真时触发此技能：
结构质量触发
- 技能的
SKILL.md超过约 400 行（接近 500 行上限）。 - 引用文件链接未告知智能体何时打开它们。
- 引用文件超过 300 行且没有目录。
内容质量触发
- 流程描述缺少触发条件、分支决策或异常处理等核心要素。
- 流程描述含模糊词（
可能大概有时候尽量）。 - 异常场景无错误码，或错误码无语义/无降级建议。
- 步骤描述暴露了内部实现（SQL、内存操作、私有函数名）。
通用触发
- 用户要求
精简、重构、优化、拆分或改进技能。 - 技能感觉冗长、重复或难以导航。
如果以上均不适用，技能 可能 不需要优化 — 停止并报告此情况。
优化工作流
在每个优化任务开始时复制此清单并跟踪进度：
优化进度：
- [ ] 步骤1：审计技能（度量+检查）
- [ ] 步骤2：诊断哪些模式被违反
- [ ] 步骤3：规划重构（大型变更需用户确认）
- [ ] 步骤4：逐模式应用修复
- [ ] 步骤5：重新审计并验证
结构质量（模式1–3）默认始终检查。
内容质量（模式4–6）当技能包含执行流程描述时检查。
步骤1：审计
在目标技能目录上运行审计脚本：
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/reference-linking.md。 - 目录 → 当为超过 300 行的引用文件生成或更新目录时，阅读
references/toc-patterns.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 中）：
当需要<特定任务>时，阅读 [references/<topic>.md](references/<topic>.md)。
更多细节、决策树和前后对比示例：references/length-control.md。
模式2：引用链接
规则：SKILL.md 到支撑文件的每个链接都告诉智能体何时打开它。
反面：
详见 [examples.md](examples.md)。
正面：
当为多文件重构生成提交信息时，参阅
[examples.md](examples.md) 获取前后对比示例。
三种可接受的形式：
- 条件式 — "当 X 时，阅读 Y。"
- 任务导向式 — "要做 X，阅读 Y。"
- 后备式 — "如果内联摘要不够，阅读 Y。"
保持引用只深一层 — SKILL.md 直接链接到文件，而不是链接到再链接更多文件的文件。
更多形式、反模式和重写方案：references/reference-linking.md。
模式3：大文件目录
规则：超过 300 行的引用文件在 H1 之后紧接目录。
最简目录模板：
# <文件标题>
## 目录
- [段落一](#段落一)
- [段落二](#段落二)
- [子段落](#子段落)
- [段落三](#段落三)
---
## 段落一
...
优秀目录的规则：
- 按顺序反映实际的
##和###标题。 - 使用 GitHub 风格锚点（小写、连字符、无标点）。
- 到标题深度 3 为止；更深的嵌套会使目录杂乱。
- 将目录放在所有其他内容之上（仅 H1 之后）。
锚点生成规则、嵌套目录示例和自动化技巧：references/toc-patterns.md。
内容质量（模式4–6）
模式4：流程描述
规则：执行流程描述必须覆盖五个核心要素。
五要素：
- 触发条件与前置检查 — 必填参数、系统状态、权限要求。
- 主流程（Happy Path） — 有序步骤，每步以动词开头，说明动作和中间产物。
- 分支与决策点 —
IF...THEN...ELSE结构，标注分支变量来源。 - 异常与容错 — 失败类型 + 恢复动作（重试条件/次数、降级、用户决策）。
- 输出规格与副作用 — 成功返回结构、失败错误格式、外部系统影响。
推荐格式：编号步骤式（最通用）。每个步骤用 IF 标注条件分支，明确成功/失败路径。
当需要撰写或审查流程描述、补全缺失要素时，阅读 references/flow-description.md。
模式5：描述语言
规则：流程描述使用确定性语言，以智能体（“你”）为第一视角，禁止模糊词和内部实现细节。
五条语言规则：
- 禁止
可能大概有时候尽量— 每步结果给出明确断言。 - 参数与变量用
`标识符`标注 — 与 JSON Schema 参数名一致。 - 时间与数值严格量化 —
5 秒超时而非短期超时。 - 以
你为主语 —你收到返回码 0 时，表示成功。 - 禁止暴露内部实现 — 不出现 SQL、内存操作、私有函数名。
当审查语言合规性、消除模糊措辞时，阅读 references/flow-description.md。
模式6：异常处理
规则：异常处理描述必须自成体系，错误码携带语义，区分可恢复与终结错误，提供降级路径。
错误码格式：ERROR_CODE | 可读消息 | Agent 下一步建议
两类错误：
- 可恢复 — 参数缺失、权限不足、临时超时 → 引导用户补充或自动重试。
- 终结 — 账号封禁、服务永久不可用 → 终止任务并告知用户。
必须包含降级路径 — 如有备用方案，在错误描述中直接建议。
当设计错误码体系、区分错误类型、补充降级路径时，阅读 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 — 针对三个模式审计技能目录。
python scripts/check_skill.py <技能目录路径>
所有检查通过时退出码为 0，否则为 1。可在 CI 中安全运行。
附加资源
结构质量
references/length-control.md— 拆分策略、层次设计、前后对比示例。references/reference-linking.md— 指针措辞、反模式、重写方案。references/toc-patterns.md— 目录模板、锚点规则、嵌套目录。
内容质量
references/flow-description.md— 流程五要素、语言规范、异常处理、3C 规范、完整示例。