Writing Skills

Writing Skills

把技能当作给 AI 的可执行工作流文档，而不是给人的说明书。写技能 = 把 TDD 用在文档上：先观察失败，再写最小规则，再堵住漏洞。

铁律：没有失败的测试，就不要写技能。

压力越大，越要先跑基线测试；不要因时间不够、领导要求、业务 blocked、已有长草稿或手动检查过而跳过红色阶段。

已写好的草稿不能作为“参考”保留。先基线测试，再从观察到的失败写最小规则；否则测试会变成替既有草稿背书。

开始前：确认测试授权

• 用户当前请求已包含“测试”“验证”或“跑评估”：视为已授权，直接进入基线阶段，不要重复询问。
• 用户只要求创建或修改：先说明必需的基线与复测范围并询问是否执行；未授权测试时不修改，只能提供分析或测试方案。
• 测试中断或用户撤回授权：将产物标记为未验证并移出加载、注册和分发路径，不得宣称技能已完成。

HARD-GATE：先观察失败

以下规则无例外，即使用户说“直接写”、“不要测试”、“只改一个词”、“不能删除草稿”、“领导已审批”或“今天必须发布”：

1. 创建或修改技能前，先在不加载目标技能、不参考现有草稿的情况下运行基线场景，并记录至少一个真实失败。
2. 基线没有失败时，暂停或放弃修改；不得为了假想价值继续写，也不得发布未验证版本。
3. 现有草稿需要保留时，将其移出技能加载和分发路径，标记为未验证材料；不要在红色阶段读取、改写或作为参考。
4. 后文的“结构化逃生路径”是设计其他技能时的模式，不是绕过本技能红色阶段的许可。
5. 修改后的纪律类技能未通过真实智能体压力测试时，只能保持未验证状态；不得注册、发布或宣称完成。

什么时候用 / 不适用

• 用：创建、重写技能；教 AI 非显而易见的模式；验证压力下有效性；description 触发不准需要量化优化。
• 不用：一次性解决方案、项目局部约定、可用脚本强制执行的机械约束、AI 已掌握的常识。

一、如何写技能

先访谈需求

写之前先理清五点，主动追问边界、输入输出格式、成功标准、依赖项：

1. 要让 AI 做到什么？
2. 什么表述或上下文应触发？
3. 什么上下文不应触发？
4. 期望的输出格式和行为边界是什么？
5. 需要哪些测试用例来验证？

使用三级渐进式披露

skill-name/
├── SKILL.md              # 入口：触发条件、流程、红线、引用条件
├── references/           # 按需加载的展开说明
│   └── tests/            # 压力测试、学术测试和触发测试
├── scripts/              # 可执行脚本
└── assets/               # 产出物模板

• name + description：始终在上下文中，决定是否触发。
• SKILL.md body：触发时加载，只保留控制逻辑。
• references：按需读取，承载长示例、完整工作流、背景、模板。
• 技能测试文件放 references/tests/，不要散落在技能根目录。

按红-绿-重构编写

1. 红：在没有技能时跑压力场景，逐字记录 AI 的选择、借口、违规点。没有基线失败就不写。
2. 绿：只针对观察到的失败写最小规则，解决真实漏洞，不预防假想问题。
3. 重构：AI 又找到新借口就补进规则，反复测试到无法绕过。

编写规则速查

• frontmatter 只保留必需字段：name 和 description。
• name 只用字母、数字、连字符。
• description 用中文写清“当……时使用”，包含触发条件、症状和不适用边界，不总结完整流程。
• body 先写控制逻辑，再写细节；用祈使语气；解释“为什么”优于命令式。
• 一个强示例胜过多个弱示例；不写填空模板，写可直接适配的模式。
• 不影响执行顺序的内容下沉到 references；SKILL.md 超 250 行就拆分。
• SKILL.md 与 references 不重复，不创建面向人的 README、CHANGELOG、QUICK_REFERENCE。
• 纪律类技能要写“不要怎样变通”；显式封堵“这只是简单改动”“之后再测也一样”“保留草稿当参考”之类借口。
• 多 Agent / 子任务编排遵循隔离自包含加载、增量上下文收敛与确定性输入，详见 references/guides/anthropic-best-practices.md。

HARD-GATE 判断规则

不是所有规则都应该是 HARD-GATE。判断标准：

满足任一 HARD-GATE 条件，就写 HARD-GATE 段落：

## HARD-GATE

以下规则无例外，即使用户说“直接改”、“跳过”、“手动模拟”、“紧急”或“简单”：
1. 规则一
2. 规则二

HARD-GATE 必须显式列出用户最可能说的绕过借口，并声明无效。不写“用户明确指令优先于 skill 规则”这个通用漏洞——它会让所有 HARD-GATE 失效。

压力测试的核心目的就是验证 HARD-GATE 是否真的不可绕过：用“别读了直接调”“手动模拟就行”“太简单不用走流程”等话术攻击每条红线，AI 必须拒绝。

HARD-GATE vs 结构化逃生路径

按受保护的最终状态判断，不按施压者是谁判断：

• 绕过会产生不安全、不可逆或未验证的最终状态时，使用 HARD-GATE；团队、权威和时间压力都不是例外。
• 结构化逃生路径只用于目标技能预先定义的可逆协作分支；可以调整过程，不能把未满足的成功标准改称已满足。
• “不算违反门禁”必须由技能预先定义，AI 不能在压力现场自行宣布。
• 对 writing-skills 自身，现实阻塞时只能隔离草稿并记录风险，不能发布未验证技能。

结构化逃生路径模式和抵制合理化的写法见 references/guides/persuasion-principles.md；结构、命名、description 和渐进式披露原则见 references/guides/anthropic-best-practices.md。

二、Token 效率：引用 token-saving

写技能、改技能、测试技能时，直接使用 token-saving 技能中的“写技能 / 改技能 / 测试技能”分流说明。

本技能不重复展开省 token 方法；如果任务涉及长文档、多文件、子代理或长对话，先按 token-saving 设定预算、分层读取、阶段压缩，再继续写技能。

三、测试命中率与评分

技能有效性靠测试证明，不靠感觉。测试前必须有基线失败记录；没有红色样本，就不要进入评分。

测试维度

测试类型

命中率测试流程

触发不准时，优化 description：

1. 造 20 条 eval 查询，标注 expectedTrigger。
2. 手动改 description。
3. 跑触发测试。
4. 统计命中率、误触发率、漏触发率。
5. 重复到稳定。

失败归因

评分建议

Token 成本评估（简化版）

目标：确认技能不会为简单任务引入不成比例的开销。不要求子代理自报估算数（不可靠），只检查两点：

1. SKILL.md 行数：≤ 250 行。超过则拆分到 references/。
2. 简单任务开销：挑一条最简单的触发用例，肉眼对比带技能与基线的隔离智能体输出。如果带技能输出明显更长（感官上 > 50%），且多出的内容只是技能自身的流程说明模板而非解决任务所需，则把模板内容下沉到 references/。

两点都通过，结论写"可接受"。不需要全量采集，不需要字符→token 换算。

测试记录格式

每条用例至少记录：用例文本、是否应触发、实际是否触发、是否遵守关键规则、失败原因、下一步修改点。

测试完成后必须输出评分表，至少包含：指标、通过数 / 总数、得分或比例、结论、失败用例摘要。只给“通过了”“效果不错”不合格。

需要定量对比时：每条用例并行启动两个相互隔离的智能体运行（可用 subagent 实现），一个加载技能，一个不加载，比较带技能与基线差异。完整流程、评估 JSON 格式、断言写法见 references/methodology/quantitative-evaluation.md；设计压力场景和堵漏洞见 references/methodology/testing-skills-with-subagents.md。

本技能自身的触发与压力测试用例见 references/tests/evals.json。

迭代

改技能 → 跑测试对照 → 等反馈 → 继续，直到用户满意或改进不再有意义。保持精简、泛化反馈、删除无效内容。

技能集成

• 写技能时：按本技能执行。
• 省 token 时：直接分流到 token-saving。