Skill Guidelines

11 条原则，分四层：通用（1-3）、结构（4-5）、流程（6-8）、编写（9-11）。

元规则：当两条原则冲突时，优先保障输出准确性，其次保障可维护性，最后追求简洁。本条裁决创作时的原则冲突；被审查 skill 内部的指令冲突与循环见 #3。

一、通用（Cross-Cutting）

不限阶段、不限场景的全域纪律，创作与审查中随时生效。

1. 想清楚再动手（Think Before Writing）

想清楚再动手，声明假设，暴露问题，呈现取舍，不明就问。

为什么：在设计或改造技能时，如果带着模糊理解动笔，产出的必然是边界不清、指令矛盾、运行不稳定的 skill。

在写任何指令之前：

• 声明假设。 你假设了什么触发条件、什么执行环境、什么可用工具？写下来。如果不确定，就主动提问。
• 暴露问题。 如果需求可以被理解为多种含义，列出所有含义并问清楚，不要默默选一个。
• 呈现取舍。 如果存在多种方案，列出各自的优劣和你的建议，让用户选，不要默默选一个。
• 不明就问。 如果有什么不清楚的，停下来。说出你的困惑。问。

判定：能用三句话说清"谁在什么场景下触发、做什么、输出什么"，设计才算完成。说不清则继续设计。

2. 最小充分（Minimal Sufficient Context）

Token就是金钱，把Context当作稀缺公共资源，而不是垃圾桶

为什么：每多一个 token 都是在烧钱，而且会占用稀缺的Context窗口，稀释核心指令的注意力权重，并可能产生上下文污染。删除无损内容不是偷懒，是节省金钱，提升信噪比。

• 保持精简、准确，避免冗余、模糊；
• 避免增加不必要的复杂度（有明确收益的除外）。
• 删除无损即为冗余。每条指令都应通过"删除后输出是否变差"的测试——如果答案是否，删掉它。
• 默认模型已经足够聪明，只添加它确实不知道的领域知识和约束。
• 例外：关键安全约束可在执行点就近重申——这是对抗注意力衰减的强调，不是冗余定义。
• 硬指标：description < 100 词，主文件 < 500 行（推荐200行以内）。

3. 避免过度内耗（Avoid Excessive Deliberation）

避免模型过度内耗，消灭没有收益、导致思考链反复空转的权衡，如：冲突裁决不了、分支决策不了、循环停不下来。

注意，适度内耗可能是有益的——规则间的碰撞常能得出更优解，需要结合具体场景权衡利弊，利大于弊就允许。

为什么：skill 是一张决策网，模型在网上的每一次权衡都应有出口——能裁决、能归类、能终止。没有出口，模型就会在同一决策上反复来回，烧掉上下文预算也收敛不了。

模型内耗的四种情形，及对症解法：

• 互斥指令同时适用：两条指令覆盖同一情境、动作冲突、无优先级。消解按优先级选一种：收窄条件使二者天然互斥（首选：模型无需裁决）＞声明显式优先级（"A 优先于 B"）＞定义判不准时的默认动作。
• 并列分支不互斥：场景/步骤各分支的进入条件有重叠或留缺口，输入无法唯一归类。并列分支必须边界清晰、进入条件天然互斥——用枚举值、区间、必填字段做路由，不依赖语义猜测。
• 条件不可判定："必要时""视情况"等无法由输入验真验假的条件。把条件改写成可验证的事实（例如明确"必要"的判定条件）。
• 循环无上限："重复直到正确"没有最大轮次，也没有到顶行为。凡有"重试/校验/迭代/追问"，必须给出最大轮次和到顶后的确定行为（取当前最佳、降级输出并标注、或转向人工审批）。

自检：构造 1–2 个边界案例把流程走一遍——凡是你自己都要反复犹豫"该听哪条"的地方，就是模型过度内耗的地方。

❌ WRONG: 校验失败时重新生成，反复校验直到完全正确为止。（无上限，"完全正确"不可判定，模型只能空转）

✅ CORRECT: 校验失败时重新生成，最多 2 轮；仍失败则输出当前最佳版本并标注未通过项。（有上限、有到顶行为）

二、结构（Structure）

全篇的静态组织：内容放在哪、何时出现——动笔前先定骨架。

4. 模块化复用（DRY）

每个知识点只有一个权威来源。

为什么：同一知识存在于多处时会漂移——更新一处忘更新另一处，模型面对矛盾指令时行为不可预测。

• 知识被多处需要 → 提取到独立文件（references/、scripts/），原处引用。
• 脚本已实现的逻辑 → 指令引用脚本，不再用文字重复描述。
• 不要混放：指令中嵌大段数据、脚本中硬编码应参数化的值、一个文件覆盖多个不相关主题。
• 引用深度 ≤ 1 层：SKILL.md → reference.md。不嵌套。

5. 渐进式披露（Progressive Disclosure）

按场景或步骤加载知识，不在启动时一次性注入。

为什么：把所有知识塞入主文件会耗尽上下文预算，导致模型对后半部分指令的遵从度下降。读取附属文件有额外开销，只在确实需要时才触发。

三种加载模式：

• 按场景：主文件识别场景，读取对应 reference。一个场景只读一个。
• 按步骤：进入工作流某阶段时，才读取该阶段的 reference。
• 按深度：基础路径在主文件完成，高级/边缘路径才需要 reference。

设计要求：

• 不区分场景/步骤的通用内容 → 留在 SKILL.md，不要下沉到附属文件（常见误区）。
• 每个 reference 覆盖一个连贯主题，能独立被理解。
• 主文件用明确指针："需要 X 时读 Y"，而非"详见 references/"。
• 多个场景共享知识 → 提取为共享 reference，各场景引用（DRY 优先于"每场景一个"）。

✅ CORRECT（按场景加载）: SKILL.md:

• 用户提到 React → 读 references/react.md
• 用户提到 Vue → 读 references/vue.md 通用审查流程：理解职责→审查代码→输出报告（结构见 #6）

references/react.md: React 组件审查规则（自足） references/vue.md: Vue 组件审查规则（自足）

三、流程（Flow Control）

运行时的动态机制：进度如何锚定、故障如何退让、步骤如何推进——动笔前先定骨架。

6. 交付物锚定（Anchor with Artifacts）

先定义结构，把输出写成客观存在的交付物；用交付物核查进度，而不是用模型的自述。

为什么：模型执行流程是流动的——它可能觉得自己做完了，也可能静默跳步。把输出写入客观介质（文件），进度变得无法抵赖：每一步做没做、合不合格，看产物说了算。结构定义是"可校验"的前提，落盘是"客观存在"的前提，两者都服务同一个目的：以事实约束替代注意力约束（靠模型"记得做"不可靠，靠产物"必须存在"可靠）。

锚定三要素，先定义后执行：

• 结构先行：交付 schema/模板（字段、类型、必填项）在执行前定死，不让模型生成时现编格式。
• 写入文件：过程和最终产物写入文件——只写在对话里不算产出。
• 先校验再前进：进入下一步前核查产物存在且通过结构校验；失败→修复重试（轮次上限见 #3），不得跳过。

过程产物是否落盘，不看流程长短，看下游对这份输出的依赖：

• 任一命中（输出被下游步骤/其他会话消费；错误无法当场发现、会静默传播到下游；失败后重做代价高） → 必须落盘。
• 全部不命中（当场消费即弃、错误即时可见、重做便宜）→ 留在上下文即可，不值得为它支付落盘与校验的流程成本。
• 只要产出最终交付物，结构先行就不可豁免。

❌ WRONG（无锚点）: 步骤1 分析需求 → 步骤2 依据需求做数据库设计 → 步骤3 生成迁移脚本 （需求清单没有落盘，步骤2 可以绕开它直接发挥，跳步无从发现）

✅ CORRECT（交付物链条）: 步骤1 输出 requirements.md（模板：编号/描述/优先级/验收标准）→ 步骤2 读取后开始设计，并核查每项均有验收标准 → ……

✅ CORRECT（最终交付物）: 分析 ./sales.csv，产出 report.docx，包含：

• regions: 各地区总收入（表格，列：地区/收入/占比）
• highlight: 最高收入地区的 2-3 句分析
• issues: 数据质量问题清单（无则写"无"）

7. 优雅降级（Exhaust First, Degrade Second）

降级是认真尝试之后的终点，不是尝试的替代。在每个依赖点定义：尽力什么、几轮到顶、如何降级。

因为中断流程会让用户失去所有已有进展，所以即使依赖缺失也应输出降级结果而非报错。但降级路径一旦存在，它就是阻力最小路径——模型遇到本可解决的故障也会绕过去降级。所以"尽力"和"降级"必须绑定为一个机制才互相成立。

在每个外部依赖点定义三要素：

• 尽力清单：换参数→换工具→换路径→换数据源的备选动作。区分两类故障：环境性故障（路径错、超时、限流）值得变化着重试；能力性故障（工具不存在、无权限、无数据源）重试结果不变，直接进入降级，不傻重试。
• 上限与到顶：最多 N 轮（用户定义）尽力尝试（循环上限，见 #3）；全部用尽→执行降级，次优结果 > 报错 > 死循环。
• 降级留痕：降级输出必须在输出中明示降级原因和后果——留痕既是尽力证明，也是用户介入点。

❌ WRONG: 若搜索工具不可用，直接基于已有信息评分。（对"不可用"自行认定，一轮尝试都没发生）

✅ CORRECT: 搜索失败→换关键词重试 1 次→改用备用检索→仍全部失败，基于已有信息保守评分，标注"外部搜索不可用（已尝试 X、Y），评分基于已有数据，置信度：低"。

8. 推进必过门（All Progress Gate-Checked）

每一步推进都要过一道可校验的门——机器门或者人工门，守好门控是质量底线。

为什么：没有门控时，"这一步已完成且合格"靠模型自述——自述不可信。门控把推进条件外化成可校验事实：机器门查"对不对"（结构、完整性），人工门问"该不该"（价值、责任）。

两种校验方，按职责分工：

• 机器门：模型自动校验产物文件存在、符合 schema、内容非空、数值范围合法。执行前校验依赖就绪，执行后校验输出合格。门是独立校验环节，不得与执行动作合并（不要写"生成并验证通过"）。
• 人工门 🔴：用于不可逆操作、外部副作用、关键事实澄清等应当人工校验的情形。审批请求必须用强制语言等待确认，推荐用🔴 标记（只建议不强制要求）防长流程淹没。

分工纪律：

• 可机械验证的不要交给人——逐步求确认会被机械点掉，审批退化为噪声；
• 需人拍板的不要交给机器——schema 合法证明不了决策正确。
• 非人工交互环境（自动化、用户要求直接交付结果等），禁止使用人工门。

注意事项：

• 定义失败通道：机门不过→明确是否重试、重试几次，何时终止或转人工审批；人门不过→回到上一步修改后重问。
• 门不宜过度：满地是门的流程等于没有门。底线：最终交付物至少一机门（存在 + 结构）一人门（交付确认）。

✅ CORRECT（过门再推进）: 步骤2 评估:

• 输入机门: 数据.json 存在且方案数组非空
• 输出机门: 数据.json中每个方案含评分，且评分取值 ∈ {1,2,3}
• 🔴 人门: 评分结论经用户确认后进入报告呈现阶段

❌ WRONG（自述式推进）: 没有任何门控标准。

四、编写（Craft）

单条指令怎么写：松紧、原因、示例。

9. 张弛有度（Rigor Follows Certainty）

确定的事交给机制，开放的事交给判断——能脚本就不推理，能枚举就不发挥。

为什么：模型推理的一致性远低于机械执行——算术有代码可算，路由有表可查，这类任务上留给模型发挥没有任何收益、只有风险；反过来，对开放任务强行写死，规则的缝隙里塞满的是假确定，牺牲的是模型应对未预见情况的自适应能力。

松紧的判定标准不在你的偏好，在任务本身有没有确定且可机械验证的结果。

• 可机械验证的任务（数学计算、格式转换、数据提取、渠道路由）→ 外化为确定手段：计算交给脚本、分流交给枚举、产物交给固定模板，模型只负责编排输入输出。
• 开放判断的任务（代码审查、文档撰写、设计方案）→ 原则引导、结果约束、示例参考，把判断留给模型。
• 多数任务混合两者：按环节分段定松紧——可机械验证的环节写死，需灵活判断的环节写活，不要整篇一刀切。
• 拿不准是否"确定"时，用机械验证测试：能为正确结果写出检验器的，是确定问题；检验标准本身有争议的，是开放问题。选择后解释原因（见 #10）。

❌ WRONG（确定的事写松）: 计算各地区销售增长率：仔细逐步推理，确保结果准确。

✅ CORRECT: 计算各地区销售增长率：调用 compute_growth(data)，输出表格。

❌ WRONG（开放的事写死）: 代码审查只报告以下问题：函数名超长、缺少 docstring。

✅ CORRECT: 已知问题枚举写死：函数名超过 50 字符、缺少 docstring、裸 except；清单之外的问题，按正确性、安全、性能、可读性四条原则判断。

10. 解释为什么（Explain the Why）

给出原因，而非堆砌禁令。

为什么：禁令只划定已知边界，遇到规则未覆盖的新情况模型无法自主判断。因果句传递了边界背后的意图，使模型能在边界外做出符合意图的决策。ALWAYS/NEVER/CRITICAL 是注意力噪声，遵从度并不显著高于普通语句。

• 当你想写 ALWAYS / NEVER / CRITICAL 时，改为"因为……所以……"。
• 解释目的而非过程："输出 JSON 是因为下游系统需要解析"优于"必须输出 JSON"。
• 如果你无法解释为什么，这条规则可能本身就不该存在。

11. 示例胜于说教（Show, Don't Tell）

一对 ❌/✅ 示例的教导力超过十段抽象规则。

为什么：模型的学习目标是输入→输出映射。示例直接展示了期望的映射关系，与训练目标对齐；抽象规则需要模型先"理解"再"翻译"为行为，中间多一次损耗。当模型反复违反某条规则时，问题通常在规则的表述方式，不在模型的智力。

• 最高信号的示例来自真实失败案例，不是凭空构造。
• 示例成对出现（错误+正确），让模型看到对比边界。
• 如果一条规则已经用了三句话还说不清，直接给示例。

❌ WRONG: 提交消息应该简洁明了，包含变更类型和简要描述。

✅ CORRECT: Input: 给认证模块加了JWT功能 Output: feat(auth): 实现JWT认证

Input: 修了报表里日期格式的bug Output: fix(reports): 修正时区转换中的日期格式