编写Agent技能 是做什么的?
目标
交付一个可供Agent直接运行的指令包,用于完成一项连贯、可复用的工作。将其立足于用户的任务、示例、工具环境、已有工件和修正反馈。如果没有真实示例可用,请标注假设并起草最小可测试指令,而不是编造特定产品的API。完成并呈现实际所需的技能,而不是仅提供计划、进度报告或批评。
定义契约
- 说明触发条件:应激活此技能的任务和输入,以及不应激活的相邻请求。将
description写成一个简洁的路由规则,指明它做什么以及何时使用。 - 说明必需和可选的输入、Agent允许的权限、预期输出以及完成的定义。在交接处解决与相邻技能的重叠问题;不要仅仅因为它们共享一个主题就合并不同的阶段。
- 标记哪些行为是强制性的安全或正确性门控,哪些是默认启发式规则,哪些是可选的增强功能。指令不能强制执行运行时权限:请使用平台控件来管理文件系统、网络和工具访问。
起草 SKILL.md
使用YAML frontmatter,其中 name 为小写连字符形式并与文件夹名匹配,description 为具体描述。遵循宿主平台的格式和能力要求;不要假设可选元数据或 allowed-tools 能跨平台强制实施访问控制。
保持主体简洁:包括工作内容和边界、输入、决策过程、停止/失败处理、输出契约以及不明显的陷阱。提供一个默认路径,而不是一系列等同的选项。对于脆弱操作给出精确步骤;在上下文选择中为合理判断留出余地。避免在每个部分重复相同的禁令,或将一次性任务的答案嵌入为通用流程。
将大型领域参考资料移至专门的 references/ 文件,并明确告知Agent何时阅读它们。仅在确认了其运行时依赖项和验证行为后,才为重复的确定性工作添加可复用的脚本。确保参考资料可从 SKILL.md 直接访问,并且不要声称某草稿已被安装、执行或验证,而事实并非如此。
测试和修订
从2-3个代表性案例开始,包括一个边缘案例;当技能处理不可信内容或具有重要边界时,添加负触发和对抗性案例。在有和没有该技能的情况下,或针对之前的草稿,运行全新的会话。对可观察的输出和工具行为进行评分,而不是指令听起来有多优美。检查跟踪记录,查找不必要的步骤、遗漏的证据、误激活和范围蔓延。对于机械性检查使用代码;让人工审查实质性判断。移除那些增加成本但未能防止实际失败的指令。
交付检查
在回应之前,验证所请求的完整工件确实存在且内部一致。当用户要求完整的Markdown时,交付当前完整的 SKILL.md,而不是补丁片段。如果正在创建文件,请验证它存在并包含完整的草稿;如实报告未经测试的状态。简要说明更改了什么以及剩余的验证需求。不要在没有明确请求的情况下,将一个技能请求转变为不相关的套件。