skill-writing

技能编写

技能是打包好的指令模块，激活后会加载到 Agent 的上下文中。它们是控制 Agent 行为最有效的机制，因为能在最相关的时刻提供聚焦的指令。

铁律

先有失败的测试，才能编写技能。 编写技能前，先让子 Agent 在目标任务上运行一次，且不使用该技能。记录它哪里做错了——包括具体的辩解、走捷径的做法和跳过的步骤。然后编写技能，针对这些具体问题加以解决。这就是应用于文档的 TDD。

TDD 步骤	技能对应步骤
RED	在没有技能的情况下运行场景。记录 Agent 的错误行为。
GREEN	编写解决这些具体问题的最小技能。验证 Agent 现在会遵循要求。
REFACTOR	找出 Agent 新想出的辩解。堵上漏洞。重新测试。

何时创建技能

适合创建的情况： 相关技巧并非一目了然、你会在多个项目中反复参考、其他人也能从中受益，或 Agent 在没有技能时反复出错。

不适合创建的情况： 一次性解决方案、其他地方已有文档记录的标准实践、特定于项目的约定（使用 CLAUDE.md），或机械性约束（应使用 linter/hooks 强制执行）。

核心原则

指令的预算有限。 模型通常能可靠遵循约 150 条指令。系统提示词会占用约 50 条。每增加一条指令，都会降低所有指令的遵循率。严格筛选，别轻易占用名额。

首尾位置更受关注。 开头和结尾的部分会受到格外关注。把关键规则藏在中间，它就可能被跳过。

具体性决定遵循率。 “考虑运行审计”会被忽略。“在发出 RUN_COMPLETED 前调用 accessibility_audit”则会得到遵循。

无条件要求优于条件要求。 “你必须调用 X”有效。“酌情考虑调用 X”则无效。

优化描述

description 字段决定技能何时激活。Agent 会据此判断：“我现在应该加载这个技能吗？”请描述触发条件，而不是工作流程。

不佳： description: 用于 TDD 的技能——先编写测试，观察测试失败，再编写代码 良好： description: 当测试存在竞争条件、时序依赖，或通过与失败结果不一致时使用。涵盖不稳定测试、挂起测试和僵尸进程。

描述检查清单：

• 以“Use when...”开头，重点描述触发条件
• 包含用户可能提及的具体症状和错误消息
• 包含同义词（timeout/hang/freeze、cleanup/teardown/afterEach）
• 写出能表明相关性的工具、命令和文件类型
• 最多 500 个字符。对于频繁加载的技能，少于 200 个字符
• 切勿总结技能的流程——这会导致 Agent 遵循描述，而不是加载完整技能

技能结构

.agents/skills/<skill-name>/
  SKILL.md          # Required. Under 200 lines.
  references/       # Optional. Heavy reference docs (100+ lines).

Frontmatter

---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---

使用动词开头的主动命名：creating-skills，而不是 skill-creation；condition-based-waiting，而不是 async-helpers。

编写能得到遵循的指令

先说明身份，再列出约束

用一句话说明角色，然后立即列出硬性约束。不要先铺垫。

# Browser Test Executor

You are executing adversarial browser tests against code changes.

REQUIRED for every test run:
1. Call accessibility_audit before completing
2. Call performance_metrics before completing
3. Call close to flush the session

使用以完成条件为关卡的编号清单

编号列表能体现顺序和完整性。将其与标记任务“完成”的条件关联起来。

Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.

末尾的“不得跳过”并非多余——它堵住了逃避要求的口子。

准确写出工具和命令名称

不要写“运行适当的检查”。应始终写 call accessibility_audit 或 run pnpm typecheck。

将强制行为放在末尾

最后一节是行动前最后读到的内容。把不可妥协的检查清单放在那里。

一个好的示例，一个坏的示例

示例胜过解释。

**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`

防止找借口

Agent 会编造理由来跳过规则。请预先考虑并明确堵住每一个漏洞。

堵住逃避口子： 每条强制规则后都添加：“不接受‘就这一次’‘这很简单’或‘我下次再做’等例外。”

根据 RED 阶段的测试结果建立找借口对照表。 Agent 提出的每个借口都要在技能中明确回应：

Agent 的说法	技能的回应
“这项改动太小，不用测试”	每项改动都必须测试。改动大小不能成为例外。
“我已经手动验证过了”	手动验证不能替代测试。请运行该工具。
“用户没要求这样做”	技能要求必须这样做。用户未表态不代表可以不做。

列出危险信号：“如果发现自己在想以下任何一条，请停下来并遵循检查清单。”

反模式

模式	失败原因
“适当时可以考虑运行 X”	有条件且含糊不清 = 会被忽略
超长技能文件（>200 行）	超出指令预算，遵循度会下降
重复 CLAUDE.md 中的规则	同一条指令消耗两次预算
列出每一种边缘情况	展示一个示例即可，不要列二十个——Agent 会推断其余情况
“做到全面” / “务必谨慎”	只是空泛的说法，不是指令。应具体说明“全面”的含义
多段理由说明	Agent 需要的是规则，不是背景故事。“原因”最多用一句话说明
把关键规则放在中间	容易在提示词中间被忽略。移到开头或结尾
未经测试就编写技能	你不知道需要解决哪些失败。删掉它，从 RED 阶段开始。
概述工作流的描述	Agent 会按照摘要行事，而不是加载完整技能

检查清单：发布前

• 先在不使用技能的情况下进行测试（RED 阶段），并记录失败情况
• 技能针对这些具体失败制定措施，而非假设性问题
• 描述以“Use when...”开头，并列出触发条件，而不是工作流
• 总长度少于 200 行
• 在开头或结尾以编号检查清单列出强制行为
• 准确写出每个工具/命令的名称——不要使用“适当”或“相关”等说法
• 不使用模棱两可的表达（“考虑”“适当时”“如有需要”）
• 至少有一组正确/错误示例
• 不重复 CLAUDE.md 或其他技能中的内容
• 用明确的“无例外”措辞堵住所有逃避口子
• 使用该技能重新测试（GREEN 阶段），确认 Agent 现在会遵守要求