skill-design-patterns — 技能设计模式

技能设计模式概述 设计可靠、高质量的代理技能的最佳实践。这些模式是从数十个生产技能的实际使用中提炼出来的，并解决了最常见的故障模式：代理知道该做什么，但找到了不做的理由。创建或审查技能时应使用此技能。它编码了防止微妙质量侵蚀的模式。

何时使用 从头开始创建新技能 改进或审查现有技能 为团队或项目建立技能编写约定 审计技能套件以检查完整性 何时不使用 一次性脚本或简单提示：如果任务是单个命令执行，技能是过度的——可以写一个shell脚本代替。 纯粹的对话式指导：如果输出是建议，而不是可重复的工作流程，技能会添加不必要的仪式。 可以使用现有工具解决的任务：如果标准库函数或CLI工具已经处理了它，不要将其包装在技能中。

四个必需部分 每个设计良好的技能必须包含以下四个部分。省略它们的技能会随着时间的推移而恶化，因为代理会找到合理化的理由来跳过步骤。

• 何时不使用

位置：在角色/Persona定义之后，主工作流之前。 目的：防止错误触发。 明确列出此技能不应激活的场景，并指向正确的替代方案。 指南：2-4个条目，每个条目命名一个不适用的场景和正确的替代方案。 使用一致的措辞：“不应触发此技能” 防止代理在不适合的地方应用技能 示例（数据库迁移技能）：

• 纯SQL脚本迁移无对应应用代码 → 使用SQL linting工具代替
• 存储过程更改 → 使用存储过程迁移技能
• 配置更改 → 使用配置管理技能

• 反合理化表

位置：在主工作流/规则之后，验证检查清单之前。 目的：预防代理使用的借口来跳过步骤。 这是最有影响力的模式——直接解决代理找到合理化的理由来偷工减料的倾向。 指南：3-6行表格：| 合理化 | 为什么是错误的 | 每行针对此技能最容易出错的步骤的特定捷径 反驳必须引用具体的技术后果（例如“这会导致运行时ClassNotFoundException”），而不是模糊的“质量”警告。 思考每次代理说“我稍后会添加测试”或“这足够简单，可以跳过”——这些都属于这里。 示例（代码审查技能）： 合理化 | 为什么是错误的 “它可以工作，这就足够了” | 可工作但不可读或不安全的代码会产生累积债务。 “我写了它，所以我知道它是正确的” | 作者对自己的假设视而不见。 每个更改都能从另一套眼睛中受益。 “测试通过，所以它是好的” | 测试不能捕获架构问题、安全问题或可读性问题。

• 红旗

位置：在反合理化表之后。 目的：提供可观察的警告信号，表明技能被违反。 这些信号作为代理和人类审查者的快速健康检查。 指南：3-6个条目，每个条目是一个可观察的违反信号。 使用引言：“以下信号表明此技能未正确执行：” 每个信号必须是可验证的（例如“Mapper.java存在，但没有对应的Mapper.xml”），而不是主观的（例如“代码质量似乎低”）。 设计这些信号，使审查者可以在一分钟内扫描它们。 示例（部署技能）： 部署工件缺少所需的数据库驱动程序 配置文件仍引用旧的连接字符串 健康检查端点在部署后返回非200 回滚程序未记录或测试

• 验证检查清单

位置：在技能的末尾。 目的：用基于证据的复选框列表替换模糊的“接受标准”。 每个项目必须有具体的、可验证的输出。 指南：每个项目以 - [ ]（复选框格式）开头。 每个项目必须引用具体的、可验证的证据（构建输出、脚本结果、文件存在、运行时数据）。 禁止使用短语：“看起来正确”，“似乎正确”，“功能正常”——这些不是证据。 检查清单应全面到足以让通过它给出技能执行正确的信心。 示例（数据迁移技能）： 构建退出代码为零 迁移验证报告零未迁移引用 所有目标资源确认可访问 示例操作返回预期结果 回滚程序测试并确认功能

平台级设计原则 核心操作行为 这六个不可协商的行为应在平台的入口配置（AGENTS.md或等效文件）中定义。 它们适用于所有技能和会话。 表面假设 —— 在实施任何内容之前