author-skills

作者技能

技能为何存在

技能旨在从随机系统中梳理出确定性。其根本价值是可预测性：Agent 每次运行都遵循相同的流程——而不是输出完全相同的内容。一个改变框架的技能应该能稳定地产生差异：其词元会变化，行为不会变。本文档中的每条规则，都是影响可预测性的杠杆。

铁律

NO NEW SKILL AND NO EDIT TO A SKILL SHIPS WITHOUT A FAILING TEST FIRST

编写技能就是将测试驱动开发应用于流程文档。循环如下：

1. RED — 看它失败。 在不使用技能的情况下运行场景（对于编辑：使用当前版本）。逐字记录确切的失败和合理化说辞——它们定义了文本必须防范的问题。如果基线 Agent 没有失败，就停止：没有需要修复的内容，而没有失败依据的文本只是无效操作。
2. GREEN — 编写最少的文本。 编写能解决已记录失败的最少技能文本——不要处理假设的问题。使用技能重新运行相同场景。要么遵循要求，要么说明文本不清晰：修改后重新运行。
3. REFACTOR — 堵住漏洞。 面对压力，Agent 会编造新的合理化说辞。逐字记录每一条，添加明确的反制措施，并重新测试。重复此过程，直到技能在最大压力下仍然有效。

如果你在运行基线测试前就写好了文本，那么你记录的只是自己猜测 Agent 会做错什么，而不是它们实际做错了什么。现在就运行基线测试，然后再决定是否保留其中的任何内容。

测试方法——场景构建、压力类型、微型测试、描述触发、非门槛（技术／参考）测试、元测试——见本文件旁边的 pressure-testing.md。开始任何测试之前，请先阅读。有关促使 Agent 遵循要求的措辞技巧，请见 influence-principles.md。

将表单与失败类型相匹配

在动笔前，先对基线失败进行分类；修复一种失败类型的表单，在另一种类型上会明显适得其反。

基线失败	使用此表单	不要使用此表单
知道规则，却在压力下违反规则	明确禁止 + 合理化对照表（想法 → 现实）+ 危险信号列表	软性的“优先／考虑”指导
会遵守规则，但输出形式不对	正向配方或约定：说明输出是什么——包含哪些部分，以及顺序如何	禁止事项。遇到相互竞争的激励时，Agent 会和“不要做 X”讨价还价；在措辞对照测试中，禁止事项组产生的不想要内容甚至多于完全没有指导的组。配方不给讨价还价留下余地
输出已有内容中遗漏某个要素	在它填写的模板中设置一个必填项	在模板附近用散文式文字提醒
行为应取决于某个条件	以可观察的谓词为条件（“如果 design.md 存在，就引用其中的接口”）	无条件规则加豁免条款
绝不能跳过或误判的检查	列出一套确定性的基本操作配方，让技能要求 Agent 执行并读取结果——固定的 grep/git/schema 检查，加上针对其输出的固定规则（参见 audit-trace）	抽象地描述检查的散文式文字——“确认覆盖范围”会引发解释；针对指定输入执行指定检查，并规定如何处理结果，则不会

用记录下来的后果反驳，不要泛泛而谈。 基线会告诉你失败实际上造成了什么代价：rebase 悄无声息地丢弃的提交、原本会触及的计费路径，或五次运行中有四次走捷径。把这些写进文本。从一般情形出发的反驳——“发布回归的后果比错过截止时间更严重”——虽然正确，也适用于任何技能，但正因如此，它可以讨价还价，因为其中没有任何实际发生过的事。记录下来的具体后果无法被辩成假设。给三份草稿各一份 RED 记录稿并要求他们针对它作出反驳时，三份草稿都原样复述了所有合理化说辞，却遗漏了每一项能体现代价的具体细节。

不要添加细微差别条款。 “除非有必要，否则不要做 X”会重新开启这条规则刚刚终止的讨价还价——在有效配方后面追加一条细微差别条款，会让它从稳定一致变得嘈杂。真正的例外应单独设为以可观察谓词为条件的规则。豁免条款也无法限定作用范围：“代码块不受此限制”仍会压制代码块——应调整结构，让规则无法触及豁免部分。

Frontmatter 和命名

• description 说明**触发条件 + 结果，绝不描述工作流。**点明技能产出的交付成果（结果名词——“tasks.md 实施计划”“双轴评审结论”），以及它在何时触发；绝不要概述步骤。流程概述会让 Agent 走捷径，只按概述行事而不读正文：“在设计获批且需要编写 tasks.md 计划时使用”会促使 Agent 阅读正文；“在规划时使用——在任务之间分派评审者”则会让 Agent 只遵循概述、忽略正文。这调和了外部规则的两部分（说明它做什么和何时使用）与跳过正文的问题——结果名词能让人从众多技能中区分出该技能，而步骤列表才是隐患。将“做什么”写成结果；禁止将“做什么”写成工作流。
• 动词优先的名称：author-skills、vet-feedback、root-cause——命名动作，而非主题。工程技能不带前缀：它们是默认词汇。Personal OS 工具包则使用命名空间前缀 life-，因为两个工具包都安装后，其裸动词（capture、orient、replan）会与工程技能名称冲突。动词优先适用于前缀之后：life-plan-day、life-review-week。前缀是为了帮助用户从 / 菜单中辨认技能，而非用于路由——发现仍然依赖 description，遵循下文的关键词规则。
• 关键词覆盖：在 description 中加入 Agent 或用户实际会搜索或联想到的词——症状、具体错误文本（error、exception、e2e、tech debt）、工具和文件名（tasks.md），以及同义词（spike、mock up）。发现依靠关键词匹配；找不到的技能就等于不存在。结果名词在这里也有双重作用。
• **两种失败方向，都要测试而不是猜测。**过度概括会导致上述失败；更常见的是规格不足——技能根本不会触发。关键词覆盖和结果名词可以避免后一种问题；省略工作流步骤则可以避免前一种问题。description 是技能中影响最大的那一行，也是唯一不能靠目测把关的字段——按照 pressure-testing.md 对其进行触发测试。
• 项目约定——为支持自调用而有意偏离通用指南。description 以第二人称开头（“Use when…”），因为这行内容读起来像是直接向负责决策的 Agent 发出的指令；不可遗漏的内容使用 ## Red Flags、## The Iron Law 或 <NON-NEGOTIABLE> 块，作为项目约定中相当于通用 ## Critical 标题的写法。整套技能都必须保持一致——风格混杂的异类是偏离规范，而非多样性。
• 用户调用的技能应设置 disable-model-invocation: true——这样它们无法自动调用，且任何技能正文都不得指示 Agent 去调用此类技能。只有在为用户指定技能名称、让用户运行时，才能将任务交接给用户调用的技能（/write-handoff、/cut-release）；REQUIRED SUB-SKILL: use \x`只适用于可由模型调用的目标技能。指示 Agent 调用disable-model-invocation` 技能会导致交接无路可走——这是实际错误，而非风格小问题。
• **两类 description 的受众，以上所有规则都针对面向模型的那一类。**可由模型调用的技能通过 description 进行路由：需要涵盖关键词、症状词和结果名词。disable-model-invocation 技能的 description 不承担路由功能——Agent 看不到它，用户通过输入技能名称来使用技能。此类 description 应写成一行简洁、面向用户的文字，点明交付成果。用户调用技能的 description 中堆砌关键词毫无用处，因为没有人会读取；“发现仍取决于用户输入的词语”是错误的——用户输入的是名称。

词汇

编写技能时使用这些术语；审查技能时也要依据这些术语。

• 引导词 — 模型已通过预训练掌握的精简概念（“seam”“tracer bullet”“red”），可用少量 token 锚定一整片行为。作为 token 反复出现时，它会在技能中逐步累积出分布式定义；三句话的重复说明往往可以浓缩成这样一个词。新造的词无法调动已有的先验知识——优先选用预训练中已有的词。
• 完成标准 — 每个步骤都以 Agent 可以检查的条件结束（“测试套件全绿，输出无瑕”，而不是“测试看起来不错”）。这是防止过早结束的保障：界限含糊，就会让注意力从工作本身滑向“已经完成”。
• 无效操作测试 — 与完全没有技能相比，这一行是否会改变行为？一行内容可能真实、相关，却仍是无效操作（“小心谨慎”）。默认行为究竟是什么，应通过运行场景来判定，而不是争论。未通过测试的句子应整句删除，而不是删减。
• 重复 — 同一个含义有了第二个落脚点。这与引导词刻意相反：引导词重复的是一个 token，以集中注意力；重复则重复 含义，导致修改行为时必须改动多个位置，而且重述的规则读起来会比其实际级别更重要。无效操作检查不会发现重复——每个副本都有效，单独检查也能通过——所以要单独排查：为每条规则指定唯一落脚点，并删除或替换所有其他表述，改为指向该落脚点。规定的关卡形式不在此限：## Red Flags 项目符号或合理化表格中的行会有意呼应规则，作为失败表要求的反制措施——它是规则的症状，而不是第二个落脚点。只有当两处都是普通正文时，才将重述视为重复。
• 否定陷阱 — 禁令会把被禁止的行为带入上下文，读起来就像半条指令。应改用正向提示（“写一行注释”），避免提及被禁止的模式。唯一例外是压力关卡技能：严格禁令加上明确的反制措施正是合适的工具——参见上文的失败表。
• 信息层级 — 技能内的步骤，其次是技能内的参考资料，再其次是通过上下文指针引出的外部参考资料。把每次运行都需要的内容内嵌；只有某些分支会用到的内容则放在指针后面。决定材料是否会被加载的是指针的 措辞，而不是它的目标——必读文件若由含糊无力的指针引出，就是方差错误：先强化指针，再考虑内嵌内容。参考文件与 SKILL.md 之间最多 一层（只能通过另一文件才能访问的文件会被略读，而非阅读）；超过约 100 行的参考文件，应在顶部添加目录。
• Token 预算 — 注入会话的技能应保持精简：每个 token 都要在每轮付出代价。三种加载级别决定了预算：元数据（名称 + 描述，约 100 个 token）在每个会话的每一轮都会计费；正文在技能触发后，每一轮都会计费；参考文件只有在其指针被跟进后才会产生代价。规范类技能的核心正文应控制在约 500 个词以内（表格和代码块除外）；SKILL.md 正文应尽量控制在 200 行以内，硬上限为 300 行，由 scripts/lint-skill-length.py 检查，并且预算只能减少——超过 200 行后，应先把细节拆分到指针后面，或删除未通过无效操作测试的内容；正文只留必须保留的内容。没有检查机制的上限只是愿望：曾有一个文件精简了 225 行，却因缺乏检查机制，在几周内又回到了 300 行。长度本身就是一种失败模式，即使每一行都有效也不例外。

何时完全不该编写技能

有一条可机械检查的规则，并不意味着可以跳过技能；而是应该让技能运行检查，而不是描述检查。如果仓库已有环境级强制检查机制（例如预先配置的 linter、CI schema 检查或 git hook），技能只需指出它并读取检查结果。如果没有——这很常见，因为这一套内容不会安装到使用它的仓库中——技能就应自带确定性的操作步骤：Agent 要运行的具体 grep/git/schema 检查，以及针对其输出的具体规则。技能绝不能只是冗长地重述已有检查所编码的规则。文档应将上下文预算用于检查无法做出的判断；确定性部分应写成具体的检查步骤，而不是散文。

何时拆分

只在以下两种情况下拆分技能：

1. 触发条件确实不同。 应有独立的条件或开头用词能单独触发它，或者另一项技能必须能够独立调用它。
2. 隐藏完成后的步骤。 后续步骤明显会促使 Agent 仓促完成当前任务，而拆分后能将它们放到真正的上下文边界之后——例如移交给子技能或派发给子 Agent。行内提及会让这些步骤继续留在上下文中，起不到隐藏作用。

其他情况都只是为了拆分而拆分，代价是增加上下文负担或占用用户的记忆。

示例

一个出色的完整示例胜过许多平庸的示例：完整、可运行、注释说明 WHY、取材于真实场景，并采用最相关的单一语言。不要将它移植成五种语言的版本，也不要把它简化成填空模板。

交叉引用

将这套内容中的其他技能作为正文提及——REQUIRED SUB-SKILL: use \verify``——绝不要链接到其他技能文件夹中的文件。链接会强制加载内容，还会耦合文件夹。与自己的 SKILL.md 存放在一起的文件，应使用相对文件名引用，并说明何时加载这些文件。

自我安慰

想法	事实
“这项技能显然很清楚”	只有作者觉得清楚，这种视角永远不算数。运行它
“这只是个小改动”	技能修改也会像代码一样引入回归。先与旧版本进行基线对比
“测试文档太小题大做了”	未经测试的技能会在生产环境中失效，而每次失败都会耗费整个会话
“读一遍基本上就是测试”	阅读衡量的是流畅度，而不是行为。只有实际运行才能回答是否空操作
“出了问题我再修”	问题会表现为 Agent 悄悄忽略技能。你永远不会看到失败
“批量处理几项技能更高效”	一批未经测试的技能，就是一批未经测试的代码

部署检查清单

为每一项创建一个待办事项。

RED

• 按照 pressure-testing.md 编写压力场景（门控技能至少组合 3 种压力）
• 按照 pressure-testing.md 清理场景：Agent 能看到的任何路径中都不得出现测试相关词汇，提示词中也不得出现受测文本及其关键词
• 列出模型清单；在该技能要部署到的每个模型上运行基线测试，并为每份记录标注模型名称
• 在不使用该技能（或使用旧版本）的情况下运行基线测试；逐字记录失败情况和自我安慰
• 基线测试确实失败——否则就停止，不要写任何内容 通过
• 已对失败进行分类，且表单与之匹配（禁止项集合／操作配方／REQUIRED 槽位／可观察的条件项）
• 描述 = 触发条件 + 结果名词，不包含工作流步骤；名称以动词开头；包含用户会输入的字面关键词
• 已对描述进行触发测试：运行应触发／不应触发查询，并检查两个方向（参见 pressure-testing.md）
• 仅用最少文本解决已记录的失败；最多提供一个完整示例
• 反制内容包含基线记录的具体信息——数字、路径、差一点就成功的情况——而非笼统后果
• 在名单中的每个模型上重新运行，并启用该技能：最弱的模型也能遵循
• 依据产物和对话记录评分，绝不依赖 Agent 自己的报告；不得将引用视为规则发挥作用的证据

重构

• 明确反制新出现的自我开脱；构建自我开脱表和危险信号列表（门禁类技能）
• 对塑造行为的措辞进行微测试：无技能对照组、每个样本使用全新上下文、至少 5 次重复、人工阅读每份被标记的对话记录
• 已完成元测试：测试 Agent 确认文本清晰，并指出没有任何能让其更容易遵循规则的内容
• 持续重新测试，直到不再出现新的自我开脱

发布

• 无操作项检查：每个句子都通过无操作测试，否则整句删除
• 重复内容检查（单独进行——无操作项检查无法发现重复）：每条规则只有一个明确归属位置；删除重复表述或替换为指向原文的链接
• 每条 disable-model-invocation 描述都是一行简洁、面向用户的文字——不含触发关键词或症状词
• 正文核心内容不超出令牌预算（≤300 行，lint-skill-length.py 检查通过；超过 200 行时，说明正文为何需要这么长）；通过措辞恰当的指向链接披露参考资料，且只深入一层；任何超过 100 行的参考资料都须有目录
• 交叉引用使用 REQUIRED 子技能的正文说明；通过相对名称引用支持文件
• 每次交接只调用可由模型调用的技能；任何 disable-model-invocation 目标都应命名为供用户运行，绝不调用
• 结构与路由检查（由 Agent 运行）：frontmatter 有效（包含 name 和 description；用户调用的技能需设置 disable-model-invocation: true）、名称以动词开头、正文符合行数预算；并手动对描述进行触发测试——按照 pressure-testing.md 运行应触发和不应触发的查询，并确认每个查询都按预期路由
• 已递增 version:——不改变行为的措辞调整递增补丁版本，新增规则或槽位递增次要版本，导致现有用法失效时递增主要版本。此次编辑的 RED/GREEN 证据已记录在技能的 TESTS.md 中，且由此建立的任何可运行断言都已写入其 eval.json（scripts/lint-skill-evals.py 会验证格式；scripts/lint-skill-frontmatter.py 会在版本缺失或格式错误时失败）

不要批量创建技能。 完整完成、测试并验证一个技能后，再开始下一个。

同时编辑多个技能是另一回事，答案是各自处理互不重叠的部分。 上述规则针对的是发布一个从未完成测试周期的技能，并不禁止并行工作。并行的代价在于共享状态；本仓库有一次为期一天、涉及 22 个文件的长度检查，就为此付出了三次代价，而每项单独编辑都经过了正确测试。派发第二位工作者之前，先明确两位工作者都会修改哪些内容。

• 共享台账只能有一位写入者。 有一轮重新生成了仓库的长度预算，并重置了三个文件的条目，而其他工作者当时仍在编辑这些文件；重置依据是那一刻磁盘上的内容。工作者报告某个条目可以清除后，审核者在整批处理完成后统一清除。
• 切勿用尚未提交的工作来证明某个现存位置。 有一轮以一个相邻工作者几分钟前创建但尚未提交的同级文件为由，证明应当删除某个位置。请使用 git show HEAD:<path> 来核实位置，而不是查看工作树。
• 工作者报告之前，不要读取其文件。 正在编辑的目录处于一种无人选择的状态。同一天根据这种状态得出的两个结论都错了，其中一个还发布了一个强制执行从未发生过的故障的 linter，直到问题被发现并删除。