技能内容优化
核心理念
- 基于发现：每次变更都应解决一个已记录的问题，或遵循一个具名的项目专属来源
- 具体化：每种模式都提供检测标准和转换方法
- 聚焦结构：优化表达和组织方式；领域知识本身保持不变
- 保留意图：在改变结构、措辞、约束、上下文或示例之前，记录原始需求
- 可追溯：将每一处应用的变更关联到一个发现或具名的项目来源
- 自包含：确保每个纯技能在单独加载时都可独立执行；当每份副本都是独立执行所必需时，跨多个独立加载的纯技能之间的重复内容是合理的
内容优化模式
P1：关键问题（必须修复）
会直接降低 LLM 使用该技能时执行准确性的问题。
BP-001：否定式指令 → 正向表达
| 检测 | 转换 |
|---|---|
| 技能指令中出现“不要”、“禁止”、“永远不要”、“避免” | 首先陈述期望的动作或允许的状态。仅当违反行为是不可逆的操作性动作、调用方通常无法恢复、且纯正向改写会模糊边界时，才保留明确的禁止性表述。将禁止性表述与安全替代方案以及允许跨越该边界的条件配对。可评审的质量策略应改写为正向形式。 |
例外边界示例：
- 允许保留：“将过期记录移至可恢复的归档区。除非用户明确授权永久删除，否则不要永久删除它们。”
- 改写为正向形式：“不要臆造问题” → “每个问题都应基于 BP 模式或 10 条原则”、“不要跳过 P1 问题” → “在每次评审中评估所有 P1 问题”、“存在 P1 问题时不要给 A 级” → “仅当 P1 数量为零时才给出 A 级”
质量策略、角色边界、评分标准和一般工作规则始终使用正向表达。调用方会校验、覆盖或丢弃的输出永远不是不可逆的。
技能示例：
- 修改前：“不要使用通用变量名”
- 修改后：“使用能反映用途的描述性变量名（例如
userId而非x）”
为何对技能而言是关键问题：仅有禁止性表述，会使可执行的目标状态无从确定。
BP-002：模糊指令 → 具体标准
| 检测 | 转换 |
|---|---|
| 模糊用词（“恰当”、“良好”、“合适”、“最佳”、“应当清晰”）遗留了一个预期成果所需的决策，且不同的合理解读会实质性改变执行或验证方式 | 按照下面的解决步骤，用限制最少但足够充分的标准来解决 |
| 未指定的格式、长度、范围、语气或成功标准，只要不同的合理解读同样能满足预期结果 | 视为可接受的灵活性；仅当只有一种解读符合要求时才添加约束（如下游使用方需要特定格式，参见 BP-003） |
解决步骤（针对第一行的发现）：
- 选择限制最少但足够充分的标准——即在排除最少有效行为的前提下，提供所需精确度的可衡量的 if-then 规则或阈值。
- 记录其精确度贡献：它为预期结果所改进的可观测输出差异。
- 记录其约束成本：它排除了原始意图中哪些本来有效的解决方案。
- 只有当精确度贡献可识别、且约束成本仍保留原始意图时，才应用该标准。
- 当输入或项目上下文无法确定该决策时，记录所需的来源，而不是凭空猜测。
技能例外：LLM 能从输入上下文中明确解决的表述（例如“用户遗留的空白之处”，当用户的提示词可供比对时）不算模糊——它描述的是确定性操作，而非主观判断。
技能示例：
- 修改前：“适当地处理错误”
- 修改后（标准来自具名来源）：“遵循项目错误处理策略（docs/error-handling.md）：对外部 API 调用、文件 I/O 和 JSON.parse 使用 try-catch 包裹；记录 error.name、error.stack 和时间戳；当调用方必须处理该错误时，携带上下文重新抛出。”
- 修改后（无可用来源）：“将‘错误处理策略’记录为所需来源，而不是臆造 try-catch 目标、日志字段或阈值。”
为何对技能而言是关键问题：模糊指令会迫使模型在没有给定标准的情况下，选择一个影响结果的行为。
BP-003：缺失输出格式 → 结构化输出
| 检测 | 转换 |
|---|---|
| 技能描述了要做什么，但未说明预期的交付物格式 | 添加输出章节，定义输出使用方（解析、路由、比对、验证）所需的结构、字段和顺序，而非按惯例随意选择格式 |
对于技能评审，输出契约包含 BP-001 至 BP-009 的覆盖情况、稳定的发现 ID、严重程度、位置、引用依据、有依据的拒绝项、需保留的要求、未解决的输入，以及最终评级。对于技能创建，输出是完整的 SKILL.md 内容，加上任何所需的同目录引用文件或脚本。
技能示例：
- 修改前：“分析代码中的问题”
- 修改后（评审报告使用方所需的格式）：“输出
## Issues Found作为报告渲染器可解析的表格：| 严重程度 | 位置 | 描述 | 建议修复方案 |”
为何对技能而言是关键问题：结构化输出约束能减少幻觉，并使技能结果保持一致。
BP-009：无边界的工作生成 → 相称的工作量
| 检测 | 转换 |
|---|---|
| 一个发现、可能性或技术上有效的改进，在不改变结果、必需边界、真实使用方或必要证明的情况下变成了强制项 | 将其视为候选项；保留必需的工作，并允许无变更、复用以及有依据支持的拒绝 |
| 研究广度决定了实现或产物的范围 | 一旦预期结果可被观察到即停止；单纯的发现本身不应扩大工作范围 |
为何对技能而言是关键问题：能力强的模型会执行隐含的义务，因此缺乏支撑依据的可能性会凭空制造出并不能改善结果的工作。
P2：高影响（应当修复）
处理后能提升技能有效性的问题。
BP-004：非结构化内容 → 有组织的格式
| 检测 | 转换 |
|---|---|
| 一大段文字没有标题分隔 | 应用标准章节顺序（见下文） |
| 一个章节中混杂了多个主题 | 拆分为各自独立的带标题章节 |
| 参考数据未使用表格呈现 | 将标准/模式列表转换为表格 |
标准技能章节顺序：
- 上下文/前置条件
- 核心概念（定义、模式）
- 流程/方法论（分步说明）
- 输出格式/示例
- 质量检查清单
- 参考资料
条件性：如果技能文件少于 30 行且只涉及单一主题，可跳过重新结构化。
BP-005：缺失或过多的上下文 → 必要且充分的上下文
| 检测 | 转换 |
|---|---|
| 技能假设了未言明的已知知识 | 添加“前置条件”章节，列出所需上下文 |
| 使用了领域术语但未加以定义 | 内联添加定义，或放入术语表。技能例外：属于 LLM 基础知识范围内的术语（广泛使用的技术术语、标准领域词汇）无需定义。只有项目专属术语、内部命名约定或常见 LLM 训练数据之外的领域行话才需要明确定义。 |
| 没有“何时使用”的指引 | 添加带具体场景的触发条件 |
| 对下游没有影响，且内容重复、会分散注意力或不可执行的上下文 | 将重复的事实浓缩为一条可操作的陈述；只有在需要提取出的事实时，才把原始背景信息保留在路径或引用之后；为项目专属事实标注来源 |
技能示例：
- 修改前：“迁移时应用绞杀者（strangler）模式”
- 修改后：“前置条件：存在具备可识别模块边界的现有单体应用。何时使用：在维持生产流量的同时替换遗留模块。”
BP-006：缺失或过多的流程控制 → 依据驱动的检查点
| 检测 | 转换 |
|---|---|
| 若缺少前置依据，后续动作将失效 | 添加检查点，指明所需依据和转换条件 |
| 权限、不可逆动作、机器读取的契约或完成证明是隐含的 | 将该边界明确化 |
| 一个可逆的选择被规定为强制路径 | 陈述目的、依据和选择标准；让模型自行选择路径 |
| 某检查点要求特定标签或产物，尽管存在语义等价的依据 | 除非机器读取方要求确切形式，否则应接受等价的依据 |
关键洞察：控制的是边界和所需依据，而非在两者之间预设的路径。
对于技能创建，依次使用三个检查点：
- 分析检查点：原始需求已记录、BP-001 至 BP-009 均已覆盖、每个问题都有依据、且没有未解决的输入阻碍工作的忠实完成。
- 优化检查点：每个发现都有一个已应用/已跳过的处理方式、每处变更均可追溯、且所有需保留的要求依然得到体现。
- 平衡检查点：意图保留、决策充分性、信息密度、约束必要性、工作量相称性和可追溯性均通过后，结果方为最终版本。
对于评审驱动的修复，以当前评审作为分析依据，并将优化检查点和平衡检查点应用于已接受的修复范围。
P3：增强项（可以修复）
针对特定场景的渐进式改进。
BP-007：不必要或有偏差的示例 → 最小必要示例集
| 检测 | 转换 |
|---|---|
| 示例只是复述了 LLM 已知的行为 | 替换为简洁的规则或使用方所需的输出形态，并移除这些示例 |
| 示例编码了领域、产品或组织专属的映射关系、非显而易见的例外情况，或规则无法表达的边界 | 保留能覆盖这些映射关系的最小集合；将每个示例对应到它所消除的歧义 |
| 多个示例消除了相同的歧义，或所有示例都具有相同的表层模式 | 缩减为能覆盖所有情况的最小集合；仅当能消除不同的歧义时才添加新的示例 |
BP-008：不允许存在不确定性 → 明确的上报机制
| 检测 | 转换 |
|---|---|
| 技能要求始终给出确定性答案 | 将断言分类为已观察、已推断或未知；为模糊情况添加上报标准 |
| 没有“何时停止”的指引 | 当某个未知因素阻碍下一步时，在当前检查点停止，并指明继续所需的确切依据或用户决策 |
技能示例：
- 修改前：“确定根本原因”
- 修改后：“将根本原因分类为已观察、已推断或未知。当缺失的依据阻碍下一步时，在当前检查点停止，并指明继续所需的确切依据或用户决策。”
10 条技能编辑原则
针对技能内容的可衡量质量标准。每条原则都包含一个通过/未通过的测试。
| # | 原则 | 通过标准 | 未通过示例 |
|---|---|---|---|
| 1 | 上下文效率 | 每句话都提供非基础性知识、决策规则、必需边界或执行依据 | 复述基础行为，却没有给出对应的失败案例、评审发现或能体现执行影响的项目需求 |
| 2 | 去重 | 同一技能内，同一抽象层级的概念不应被解释两次。当每份副本都是独立执行所必需时，跨多个独立加载的纯技能之间的重复是合理的；应评估这些副本之间的语义一致性，而非将其替换为对同级技能的引用 | 同一条规则在同一技能中出现两次，却没有增加不同的执行作用 |
| 3 | 归类 | 相关标准集中在单一章节中（减少查阅次数） | 错误处理规则分散在 4 个章节中 |
| 4 | 可衡量性 | 标准指明了可观测的依据、确定性决策规则或有依据支撑的阈值 | “编写整洁的代码”，却没有可观测的判定条件 |
| 5 | 正向表达 | 指令陈述应当做什么（应用了 BP-001） | 将“只使用 X”写成“不要使用 any” |
| 6 | 记法一致 | 标题层级、列表样式、表格格式统一 | 同一上下文中混用 -、*、1. |
| 7 | 前置条件明确 | 项目专属及非基础性的前置条件均已陈述或提供链接；基础技术知识保持简洁 | 使用 "DI" 却未定义 Dependency Injection（依赖注入） |
| 8 | 优先级排序 | 最重要的条目在前，例外情况在后 | 边界情况排在常见模式之前 |
| 9 | 范围边界 | 明确说明该技能覆盖的范围，以及激活条件性内容的条件。一个纯技能应包含独立执行所需的全部上下文。跨技能引用仅保留给承担编排或技能选择角色的技能使用 | 某个纯技能因为另一个独立加载的技能中也包含某条可执行规则，就省略了该规则 |
| 10 | 工作量相称性 | 每一项必需的产物、测试、检查点或决策都应改变结果、边界、使用方结果或必要证明 | 要求实现所有发现或所有技术上有效的改进 |
参考资料
- 创建技能：参见 references/creation-guide.md 了解生成流程和描述撰写指南
- 评审技能：参见 references/review-criteria.md 了解评估流程和评级方式
