用途
skill-optimization 用于评估和优化技能（skill）文件的质量。它通过 8 个内容模式（Content Optimization Patterns）和 9 条编辑原则（Skill Editing Principles）对技能内容进行审查与改写。适用时机包括：创建技能时、精炼技能内容时、审计已有技能时。
核心哲学
- 以证据为基础（Evidence-Based）：扎根于提示工程研究，应用于技能撰写。
- 具体（Concrete）：每个模式提供检测标准与转换方法。
- 聚焦结构（Structure-Focused）：优化表达与组织方式，领域知识保持不变。
内容优化模式
P1：关键（必须修复）
指直接影响 LLM 执行技能准确性的问题。
BP-001：负面指令 → 正向表述
- 检测：技能指令中出现 "don't"、"do not"、"never"、"avoid"。
- 转换：改写为等效约束的正向指令。例外：仅当同时满足全部 4 个条件时才允许使用负面形式：(1) 违反会在单步内破坏状态；(2) 调用方或后续步骤通常无法恢复；(3) 约束是操作/流程性的，而非质量策略或角色边界；(4) 正向改写会扩大或模糊目标范围。任一条件不满足即应改写为正向形式。
- 例外边界示例：允许的如 "Do not modify the command"、"Do not add flags"、"Do not execute destructive operations"；应改写为正向的如 "Do not invent issues" → "Base every issue on BP patterns or 9 principles"，"Do not skip P1 issues" → "Evaluate all P1 issues in every review mode"，"Do not give grade A when P1 exists" → "Assign grade A only when P1 count is zero"。
- 质量策略、角色边界、评分标准和一般工作规则始终使用正向形式。调用方会验证、覆盖或丢弃的输出从不是不可逆的。
- 技能示例：Before: "Don't use generic variable names"；After: "Use descriptive variable names that reflect purpose (e.g., userId not x)"。
- 对技能为何关键：LLM 注意力机制会聚焦被否定的内容，含 "don't" 的技能指令会提高被禁止行为出现的概率。
BP-002：模糊指令 → 具体标准
- 检测：出现 "appropriate"、"good"、"proper"、"best"、"should be clear"；缺少输出格式、范围或成功标准。
- 转换：替换为可度量的 if-then 标准或具体阈值；补充显式约束。技能例外：LLM 能从输入上下文无歧义解析的表达（例如用户提示可用于比对时的 "where the user left gaps"）不算模糊——它们描述的是确定性操作，而非主观判断。
- 技能示例：Before: "Handle errors appropriately"；After: "Error handling criteria: 1. try-catch for external API calls, file I/O, JSON.parse 2. Log: error.name, error.stack, timestamp 3. Re-throw with context if caller needs to handle"。
- 对技能为何关键：约 40% 的执行差异由此产生，每条模糊指令都会迫使 LLM 猜测。
BP-003：缺少输出格式 → 结构化输出
- 检测：技能描述了做什么，但未说明预期的交付格式。
- 转换：添加输出部分，包含结构、字段和示例。
- 技能示例：Before: "Analyze the code for issues"；After: "Output format: ## Issues Found with table: | Severity | Location | Description | Suggested Fix |"。
- 对技能为何关键：结构化输出约束能减少幻觉，使技能结果保持一致。
P2：高影响（应当修复）
指被修复后能提升技能有效性、未处理会降低效果的问题。
BP-004：非结构化内容 → 有组织格式
- 检测：没有标题的大段文字；一个章节混杂多个主题；参考数据缺少表格。
- 转换：套用标准章节顺序；拆分为带标题的独立章节；把标准/模式列表转为表格。
- 标准技能章节顺序：1. 上下文/前提条件；2. 核心概念（定义、模式）；3. 流程/方法（分步）；4. 输出格式/示例；5. 质量清单；6. 参考。
- 条件：若技能不足 30 行且只覆盖单一主题，则跳过重构。
BP-005：缺少上下文 → 显式前提条件
- 检测：技能假设了未说明的知识；使用领域术语而未定义；缺少 "when to use" 指引。
- 转换：添加前提条件章节列出所需上下文；以内联或术语表定义术语；添加含具体场景的触发条件。技能例外：属于 LLM 基线知识的术语（广泛使用的技术术语、标准领域词汇）无需定义，仅项目专有术语、内部命名约定或 LLM 训练数据之外的领域行话需要显式定义。
- 技能示例：Before: "Apply the strangler pattern for migration"；After: "Prerequisite: Existing monolith with identifiable module boundaries. When to use: Replacing legacy module while maintaining production traffic."。
BP-006：复杂内容 → 分解步骤
- 检测：一条指令包含 3 个以上目标；顺序依赖不明确；缺少中间验证。
- 转换：拆分为带检查点的编号步骤；在步骤间添加依赖标记；每步之后插入检查点。
- 条件：简单参考表或单一标准规则跳过分解。
- 关键洞见：目标是可评估的粒度与质量检查点，而非为分解而分解。
P3：增强（可以修复）
针对特定上下文的增量改进。
BP-007：有偏示例 → 多样覆盖
- 检测：所有示例结构相同；只有顺利路径示例；示例复杂度一致。
- 转换：添加边缘情况与例外；添加错误情形、边界条件；包含简单、中等和复杂示例。
BP-008：没有不确定性许可 → 显式升级
- 检测：技能要求始终给出确定答案；没有 "when to stop" 指引。
- 转换：为含糊情形添加升级标准；添加显式停止条件。
- 技能示例：Before: "Determine the root cause"；After: "Determine the root cause. If root cause is uncertain after 3 investigation cycles, report top 3 hypotheses with confidence levels and evidence for each."。
9 条技能编辑原则
针对技能内容的可度量质量标准，每条原则含通过/失败测试。
- 上下文效率：每句话都对 LLM 决策有贡献，无填充。失败示例："This is an important skill that helps with..."。
- 去重：技能内部或技能之间同一抽象层级的概念不重复解释。不同结构角色的提及（如分类框架 vs 执行细节）不算重复，前提是再次提及增加了新约束或标准。失败示例：同一错误处理规则在多个相关技能中以相同抽象层级重复陈述。
- 分组：相关标准放在同一章节（最小化读取操作）。失败示例：错误处理规则散落在 4 个章节。
- 可度量性：所有标准使用 if-then 格式或具体阈值。失败示例："Write clean code" 而无 clean 的定义。
- 正向表述：指令说明要做什么（应用 BP-001）。失败示例：用 "Don't use any" 而非 "Use only X"。
- 记号一致：标题层级、列表样式、表格格式统一。失败示例：同一上下文中混用 -、*、1.。
- 显式前提条件：所有假设知识均已说明。失败示例：使用 "DI" 而未定义 Dependency Injection。
- 优先级排序：最重要项在前，例外在后。失败示例：边缘情况排在常见模式之前。
- 范围边界：显式说明覆盖范围——本技能处理什么，何时引用其他技能。失败示例：指导内容重叠且无交叉引用。
参考文件
- 创建技能：参见 references/creation-guide.md 了解生成流程与描述指引。
- 审查技能：参见 references/review-criteria.md 了解评估流程与评分。