writing-skills

编写技能

概述

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

技能是塑造行为的代码，而不是散文。你要编写一个失败测试（即 Agent 在没有技能时会处理错误的压力场景），观察它失败，再编写能解决问题的最精简技能，观察它通过，然后堵住漏洞。

**核心原则：**如果你没有观察到 Agent 在没有技能时失败，就无法判断该技能是否教会了正确的做法，甚至无法判断它是否教会了任何东西。

铁律：

NO SKILL WITHOUT A FAILING BASELINE FIRST

这适用于新技能，也适用于现有技能的修改。“简单补充”“只加一个章节”“文档更新”——都属于同一种违规行为。先写技能再测试？删掉它，重新开始。

何时使用

• 为此仓库创建新技能（另请阅读 CONTRIBUTING.md——新技能必须先在 issue 中达成一致，并附带评估覆盖）
• 编辑任何 skills/**/SKILL.md 内容
• 审查修改技能内容的 PR

**何时不使用：**用于项目特定约定（这些应作为 CDR 放入 team-ai-directives 仓库），或用于可通过脚本或测试强制执行的机械性约束——将其自动化，把文档留给需要判断的事项。

核心流程

RED — 建立失败基线

在未加载技能的情况下运行场景。逐字记录：

• Agent 实际做了什么
• 它用来跳过正确行为的具体理由
• 哪些压力导致了失败（时间、沉没成本、权威、“反正都能运行”）

如果 Agent 在没有技能时已经表现正确，**就此停止——没有需要修复的问题。**强制执行本来就能自然做到的行为，只会增加上下文噪声（此仓库旨在消除上下文噪声，而不是增加噪声）。

GREEN — 编写最精简的技能

从模板开始（本目录中的 templates/SKILL-template.md）。只处理你在 RED 阶段观察到的失败，不要处理假设性的失败。

加载技能后运行相同场景。Agent 现在应该遵循要求。

REFACTOR — 堵住漏洞

发现新的理由？添加明确的反制措施，然后重新测试。循环往复，直到技能在压力下也无懈可击。

在完整场景前对措辞进行微测试

完整的压力测试耗时较长。先用低成本方式验证措辞：每个样本进行一次全新的 API/子 Agent 调用，每个变体至少重复 5 次，并始终包含一个无指导对照组。如果对照组未出现该失败，就没有需要修复的问题。手动阅读每个标记出的匹配项——自动统计会夸大失败和成功的数量。

结构规则（本仓库）

规则	原因
恰好 2 层深：skills/<domain>/<skill>/SKILL.md	由 test_skill_directory_depth 强制执行；可解决 skills CLI 深度限制
Frontmatter：必须包含 name 和 description（总计 ≤1024 个字符）	由 test_skill_description_presence_and_length 强制执行
可选的 scripts:（sh:/ps:）和 disable-model-invocation: true	用于标记不得由模型调用的技能
描述 = 仅用于触发	见下文——这是技能悄无声息地失效的最常见原因
标题：Overview → When to Use → Core Process → Red Flags → Verification	标准结构；仅当技能包含可调参数时才使用 Configuration
Token 预算：SKILL.md 正文尽量少于 500 行（强制规则：超过 500 行警告，超过 800 行失败——见 test_skill_token_budget）	大型参考资料放入 references/；脚本放入 scripts/{bash,powershell}/
新技能必须附带评估覆盖	Goldset 标准 + 二元评分器（{"pass": bool, "score": 1.0|0.0}）——见 evals/promptfoo/

技能发现优化（SDO）

description 是触发界面：factory-mission 会将每个技能的名称和描述交给其子 Agent，模型再根据列表决定要加载什么。

描述 = 何时使用。绝不是技能的作用。

已测得的失败模式（参见本技能改编的 superpowers 的 writing-skills）：当描述概述工作流时，Agent 会遵循描述，而不是阅读技能正文——一条写着“在任务之间进行代码审查”的描述，导致只进行了一次审查，而技能流程图明确要求进行两次。

# BAD: workflow summary — agents will follow this shortcut
description: Bootstraps the session by injecting the team context index and pulls rules on demand

# GOOD: trigger only
description: Use when a session starts and the team AI directives context is not yet loaded

• 以“Use when…”开头，并指出具体症状和情境
• 使用第三人称（它会被注入提示词）
• 包含 Agent 可能会搜索的关键词：错误消息、症状、工具名称
• 设置了 disable-model-invocation: true 的技能可豁免（不会由模型进行路由），但仍不得造成误导

根据失败类型选择形式

撰写指导前，先对基线失败进行分类。能防住某种失败的形式，可能会加剧另一种失败。

基线失败	合适的形式	不合适的形式
压力下跳过规则（明知不该做，却还是做了）	禁令 + 合理化理由表 + 危险信号	软性指导（“优先……”“考虑……”）
输出形式不对（内容冗长、结论埋得太深）	正向方案：说明输出是什么，以及各部分的顺序	禁止事项列表（“不要重述”“绝不要叙述”）
遗漏必需内容	结构性要求：在模板中设定一个必填栏位	在模板附近用散文式提醒
行为取决于某个条件	基于可观察谓词的条件规则	无条件规则 + 豁免条款

两种形式都不要添加细微差别条款：“除非有必要，否则不要做 X”会重新开启协商；在有效方案中加入一条细微差别条款，也会削弱其效果。

让纪律类技能坚不可摧

对于执行规则的技能，要明确堵住每个漏洞：禁止具体的规避方式（“不要留作参考——删除就是删除”），尽早加入根本原则（“违反规则字面要求，就是违背规则精神”），根据你的 RED 记录整理合理化理由表，并列出 Agent 可用于自检的危险信号。

危险信号

• 基线运行前就编写了技能——删除并从头开始
• 描述概述了技能的作用，而不是何时使用
• “Agent 显然会做正确的事”——这正是 RED 的用武之地
• 技能篇幅超过约 500 行，且所有内容都内联，而不是放在 references/ 中
• 新技能发布时没有配套的评估标准和评分器
• 只处理了假设中的失败模式，却遗漏了观察到的失败模式

出现以上任一情况都意味着：停下，重新运行基线，并修复技能。

验证

只有满足以下所有条件，技能变更才算完成：

• 在不使用技能的情况下运行基线场景；逐字记录失败内容
• 使用技能后，同一场景通过
• pytest tests/unit/test_playbook_integrity.py -q 通过（深度、前置元数据、描述规则）
• 已添加评估标准和二元评分器，且评分器有单元测试（evals/promptfoo/tests/）
• 重新生成的安装构件保持同步： pytest tests/unit/test_generated_artifacts_sync.py -q
• 在真实 Agent 中进行人工验收检查（CONTRIBUTING 中的“Manual testing”）——该触发时技能会触发，不该触发时则保持静默

参考资料

• templates/SKILL-template.md — 新技能的起点
• references/skill-testing.md — 压力场景、压力类型、微测试方法
• CONTRIBUTING.md — PR 流程、评估覆盖要求、手动测试协议