AI Agent Skill 设计体系从行为编程到工程化落地1. Skill 的核心定义Skill 是自包含的能力包通过 SKILL.md、脚本、引用资料和资产把一个通用 Agent 转化为在特定任务上更可靠的专用 Agent。它提供四类能力能力类型说明示例专用工作流多步骤、可复用的任务流程写技术方案、处理 PR 评论、生成报告工具集成使用特定文件格式、API 或 CLI 的方法处理 PDF、调用 GitHub、操作表格领域知识业务规则、数据口径、组织约定公司指标口径、内部权限边界捆绑资源脚本、模板、参考资料、素材scripts/、references/、assets/Skill 与提示词模板的本质区别提示词模板在模型状态好、上下文充足、任务简单时生效高质量 Skill 应该在任务复杂、信息不完整、执行压力下把 Agent 拉回正确路径。2. 三层加载策略上下文预算管理上下文窗口是公共资源。Agent 执行任务时上下文窗口要同时容纳系统提示、用户请求、对话历史、已触发 Skill、工具结果、代码片段和中间推理。Skill 多占一个 token其他上下文就少一个 token。因此 Skill 采用渐进披露而不是把所有信息塞进一个长文件。分为三层元数据层frontmattername description负责发现和路由。Agent 在触发前只看到这一层用于判断是否应该加载该 Skill正文层SKILL.md body核心执行流程Agent 触发后加载引用层references/按需查阅的知识不抢占上下文name 和 description 的职责必须分离description 应该包含这个 Skill 做什么和什么时候使用它但不能变成完整工作流摘要。它的职责是让 Agent 正确加载正文而不是让 Agent 读完描述就开始凭印象执行。每一段内容都应该经受两个问题挑战Agent 真的需要这段解释吗这段内容值得它占用的 token 成本吗3. 资源组织脚本、引用、资产各司其职scripts/确定性任务当同一段代码会被反复重写或者任务需要确定性时放进 scripts/。脚本的价值是减少上下文消耗和行为漂移。让 Agent 每次临时生成旋转 PDF 的代码和让它调用一个已经验证过的脚本是不同级别的可靠性。references/按需查阅的知识当信息是任务执行时需要查阅的知识而不是每次都必须读的流程就放进 references/。比如用户问销售指标Agent 只需要读对应的领域文件不应该同时加载所有规则。这就是渐进披露在真实 Skill 中的价值信息可发现但不抢占上下文。assets/输出材料当文件不会被读入上下文而是作为输出材料被复制、修改或引用时放进 assets/例如模板工程、字体、图片、品牌素材。关键原则信息只放一个地方。不要在 SKILL.md 和 references/ 中重复同一段规则。重复会带来漂移漂移会让 Agent 在两个版本之间自行解释增加维护成本。4. 自由度控制匹配任务脆弱度Skill 不是越详细越好也不是越开放越好。关键是让自由度匹配任务的脆弱度和变化空间。自由度控制方式适用场景高自由度结构原则、语气规则、示例引导写技术文章、创意任务中自由度SQL 模板、字段说明控制口径查询内部指标、数据分析低自由度脚本确定性执行、门控旋转 PDF、格式转换、固定报告常见错误脆弱操作写成开放建议导致 Agent 每次重写一遍容易出错的逻辑。另一个错误把判断任务写成死流程导致 Skill 在真实场景里僵硬不可迁移。门控机制在条件满足前明确禁止后续动作。门控不是语气问题而是执行边界。它能减少 Agent 的解释空间让 Skill 在关键路径上更像程序而不是建议。常见门控类型门控类型作用示例依赖门控前置条件未满足时禁止执行未规划好资源前不要创建 SKILL.md顺序门控强制步骤顺序未验证前不要交付验证门控输出未通过检查时禁止继续格式验证不通过不要提交安全门控高风险操作前要求确认涉及生产环境操作前暂停并请求人工5. 创建流程从例子到 Skill六步流程理解具体使用例子规划可复用资源初始化 Skill编辑 SKILL.md 和资源验证 Skill基于真实使用迭代关键原则不要从抽象能力开始写 Skill。先问用户会怎么触发它哪些请求应该触发哪些不应该触发任务输入是什么成功输出是什么哪些步骤最容易出错对每个例子从零执行一遍识别可复用部分。当 Skill 包含非线性判断、循环、回退或容易提前终止的步骤时流程图比纯文本更稳定。初始化 Skill 时应使用初始化脚本而不是手写目录结构。初始化脚本的意义是减少结构错误并生成符合规范的模板。6. 验证方法基于 TDD 的 Skill 测试基础验证完成基础验证至少应覆盖YAML frontmatter 合法性、name 和 description 是否存在、命名是否符合规则、资源目录是否合理、脚本是否能运行、UI 元数据是否与 SKILL.md 同步。格式验证不能证明 Skill 好用但可以排除低级错误。前向测试用子代理模拟真实用户任务但要把它当评估面而不是审稿人。正确做法使用位于 /path/to/skill-x 的 skill-x 来解决问题 y。不好做法审查这个 Skill我认为它存在问题 A预期修复方案是 B。后者会泄露诊断和预期答案测试结果会被污染。合理化防御AI Agent 在压力下会给跳过规则找到听起来合理的理由。Skill 需要提前写出这些借口并给出反驳。审查循环应该围绕真实失败风险而不是措辞偏好。应该阻塞的问题触发条件模糊、资源引用缺失、脚本不可运行、验证流程缺失、自由度设置错误、关键信息重复且容易漂移。不应该阻塞的问题纯粹风格偏好、不影响执行的标题顺序、可由 Agent 自行判断的轻微表达差异。7. 生态边界发现机制description 是路由器不是教程。它应该覆盖 Skill 做什么、何时使用、典型触发词、相关症状、输入或任务类型但不要写完整执行流程。Skill 间引用声明关系不硬编码路径不强制加载大文件。引用分为三层必需子 Skill、推荐、另见。不要用一次性强制加载大量内容的方式组合 Skill那会破坏渐进披露。平台适配不同平台的工具名、hook、插件机制和子 Agent 能力可能不同。Skill 应该尽量写行为规则再用平台层适配具体工具。平台能力不足时优雅降级。真正应该稳定的是行为规则而不是某个平台的私有工具名。8. 反模式与自查表常见反模式反模式特征后果文档式 Skill把背景知识完整搬进 Skill占用大量上下文Agent 找不到关键指令一次性 Skill针对单一任务设计不可复用维护成本高技能库膨胀过度设计把简单任务写成复杂流程执行成本高容错率低无验证 Skill写完即冻结不测试上线后行为不可控交付前自查如果多数问题答不上来Skill 还不是能力包只是一份草稿。9. 总结好 Skill 是小而准的行为系统。设计一个 Skill 要回答三个问题Agent 在什么情况下应该发现并加载它Agent 应该获得多少自由度哪些部分必须被脚本或门控固定如何用真实任务证明它确实改变了行为核心提醒简洁、分层、可验证、可迭代。上下文窗口是公共资源SKILL.md 只放核心流程脚本承接确定性引用承接领域知识资产承接输出材料复杂 Skill 要通过真实任务前向测试而不是靠作者自信。