AI Coding Agent 的 Skill，不是提示词合集：把它设计成可交付的工程契约
很多人把 Agent Skill 理解成一段更长的提示词：告诉模型多做几步、多检查几次、语气更严格一些。
但一旦任务进入真实工程流程，问题往往不在「它有没有听懂」，而在「它交付的东西能不能被别人检查」。如果没有明确产物、验证证据和暂停边界，再流畅的输出也可能只是看起来合理。
我更愿意把一个好的 Skill 看成一份小型工程契约。
先区分：提示词与 Skill 解决的不是同一层问题
提示词主要帮助 Agent 理解当前意图，例如「帮我定位这个构建失败」。它可以补充背景和偏好，但通常不会天然定义交付标准。
Skill 则应该补上后半段：
- 输入是什么：允许使用哪些文件、命令、外部资料；哪些信息不能碰。
- 要交付什么：是分析结论、修改清单、代码补丁，还是一份可复现的命令记录。
- 如何验证：需要哪些测试、日志、截图或人工检查，才能说结果可信。
- 何时停止：遇到权限、敏感数据、范围扩大或关键信息缺失时，应该停下来等待确认。
这四项不必写得很长，但缺一项，结果就会更难复查。
一个实用的最小结构
假设要做一个「分析视频转码失败」的 Skill，它不该只写“分析日志并给出修复方案”。更可检查的描述是：
输入：一段脱敏日志、FFmpeg 命令、媒体探测信息。
产物：失败点判断、可验证的候选原因、最小修复建议。
验证：给出需要复跑的命令；区分已验证与待验证结论。
停止：缺少输入媒体、涉及客户路径或需要改生产配置时，先要求人工确认。
注意，这不是要把 Agent 变成僵硬的表单。它的价值在于让下一位审阅者能快速回答三个问题：它依据什么得出结论？改了什么？还有什么不知道？
为什么“验证证据”比“多写几条规则”重要
Agent 最常见的风险不是完全不输出，而是输出一个很像答案的结论。此时继续叠加语气要求，例如“务必严谨”“仔细检查”，帮助有限。
相反，要求它提供证据会改变工作方式：
- 判断构建修复是否有效，就附上对应测试或构建结果；
- 判断资料是否支持某个结论，就给出原始公开来源；
- 无法验证时，明确标成“待确认”，不要用确定语气补齐空白。
这也是我认为 Skill 应该包含停止条件的原因。知道什么时候不继续编造，比在不完整上下文里强行完成任务更重要。
公开项目给我们的启发
例如 Addy Osmani 的 agent-skills、obra 的 Superpowers，都把 Agent 的能力组织成面向任务的公开工作流。它们的具体格式并不相同，但可以用同一把尺子评审：输入是否清楚？产物是否可检查？验证由谁、用什么完成？遇到边界问题是否会停下来？
另一个更偏内容生产的例子是 guizang-social-card-skill。它提醒我们，Skill 的“输出”不只有文字；也可能是图片、文件或一组可发布素材。输出越具体，越需要提前说明素材版权、隐私和审核边界。
本文只基于这些项目的公开材料做方法讨论，不代表我已经在任何生产项目中部署或验证它们。
结尾：把 Skill 当成交付接口
下次评估一个 Skill 时，不妨少问一句「它的提示词写得长不长」，多问四个问题：
- 它接收什么输入？
- 它必须给出什么产物？
- 我如何检查这个产物？
- 什么情况下它应该停止并交给人？
当这四个问题都有清晰答案时，Agent 才更可能从“能聊天的工具”变成团队可以放心接手的工程协作对象。
发布前检查：确认标签可选项中存在 AI 编程、Agent、开发工具；若掘金标签库名称略有不同，选择最接近的三个，不新增虚构标签。
