writing-skills

编写技能

目的

创建最小化的可复用技能，在不限制无关工作的前提下改变决策或提升任务执行效果。技能变更通过行为验证，而不是代码 TDD 流程。此验证无需加载 aegis:test-driven-development。

默认流程

1. 确定需求和归属

• 明确可复用的行为缺口、目标用户／宿主，以及非目标。
• 检查是否已有技能、项目规则、宿主适配器或自动化检查负责此事。优先选择最小的现有归属方。
• 对于现有技能，修改或废弃之前，检查其引用、清单或生成副本、发现测试以及捆绑资源。
• 仅为可复用且不显而易见的指导创建技能。将一次性的项目约定保留在项目归属方中，并在可行时自动化机械性约束。

2. 编辑前记录行为

使用有代表性的任务，而不是只要求 Agent 复述指令的问题。

• 新技能：运行无技能对照测试。
• 对于现有技能，先运行当前版本；只有在测试技能本身是否有存在必要时，才添加无技能消融测试。
• 覆盖正向触发、容易混淆的负向近似案例，以及适合该技能类型的压力或应用案例。
• 记录决策、遗漏或多余的调用、不安全的变通方案、证据引用和未知项。不要将行数或字节数视为行为证明。

如果无法评估有意义的行为，请停在 needs-verification；不要声称该技能已可部署或保留了原有能力。

3. 设计最小指令表面

• 假定 Agent 有能力。仅包含不显而易见的背景信息、决策标准、安全边界，以及省略后导致已观察到缺口的步骤。
• 让具体程度与风险相匹配：开放式工作允许判断；仅对脆弱、涉及权限或安全关键的操作使用精确步骤。
• 保持描述简洁、使用第三人称且具有区分度。说明能力及其适用时机；只有在能避免可能的错误路由时才添加排除项。不要把描述写成流程捷径。
• 将可执行的默认流程和不可省略的约束放在 SKILL.md 中。将大量条件性细节移至直接引用的文档，并说明触发阅读的证据。
• 在可行时，让引用层级保持为一层。不要默认加载所有引用，也不要在正文中重复其内容。
• 仅当示例能显著稳定决策或输出时才添加。通常一个有代表性的示例就足够。
• 让可移植的方法说明不依赖特定宿主。将宿主工具名称、安装路径和 UI 操作流程放入由宿主负责的文档中。

规范的仓库结构为 skills/<skill-name>/SKILL.md，并且只包含工作流实际使用的支持性引用、脚本或资源。对于可选元数据，应使用仓库的宿主文档或目标宿主的现行规范，不要将供应商手册复制到技能中。

4. 做最小改动

在同一改动范围内解决已观察到的缺口，并移除已被取代的重复内容。保留公开署名和任何由外部支持的契约。废弃内部归属方、回退方案或资源时，组合使用 aegis:anti-entropy-governance；没有依赖证据时，不要留下兼容副本。

不要将某个模型的措辞、某个历史事件或假设性的边缘案例转化为普遍规则。

5. 验证候选方案

在可比的模型、工具和宿主配置下，重新运行相同的正向、负向和压力／应用场景。比较结果，而非措辞。

另请验证：

• 受支持的宿主能否解析 frontmatter、名称和描述；
• 预期请求仍能发现该技能，近似但不匹配的请求则不能；
• 每个条件引用都能从明确的触发条件到达；
• 修改后的脚本能否成功运行；
• 已弃用的文件和说明没有仍在使用的引用；
• 与修改范围相关的仓库工作流、边界、打包和宿主检查均已通过。

如果行为出现回退，应恢复缺失的义务或缩小修改范围；不要添加第二个负责人或回退方案来掩盖问题。

场景选择

技能类型	代表性证据
纪律或安全	真实的压力场景和授权边界
技巧	应用、变化和信息缺失场景
模式	识别、应用和反例场景
参考	检索、正确使用和常见缺漏场景

对于复杂或高风险的技能，如果独立评估者能增强信心，请阅读 testing-skills-with-subagents.md。

完成记录

用简洁、可审计的自然语言或等效字段记录结果：

• 行为差距和规范负责人；
• 基线和候选方案的场景结果；
• 保留和弃用的义务／资源；
• 触发条件和引用检查；
• 验证命令以及尚未覆盖的宿主／模型；
• 状态：verified、needs-verification 或 blocked。

这是方法包证据，并非权威的完成确认或部署批准。