logo

智能体技能设计模式是什么?五种 SKILL.md 写法解析

作者:起个名字好难2026.11.16 11:40浏览量:0

简介:本文系统解析智能体技能(Skill)设计模式:它是什么、为什么能减少 Token 浪费,以及工具包装器、生成器、脚本执行器、编排器、校验器五种 SKILL.md 设计模式各自的结构、原理与适用边界。同时梳理技能与提示词、工具调用、检索增强等概念的区别及落地注意事项,帮助开发者编写出触发精准、结构规范、易于协作的高质量技能包。

一、什么是智能体技能设计模式

智能体技能(Agent Skill,业内常称”技能包”)是一种面向特定任务的可复用能力封装。它以一份说明文件为核心,文件按约定命名为 SKILL.md,并搭配若干资源文件或脚本,为智能体提供完成某类任务所需的规则、流程、模板或领域知识。

技能设计模式,是指在组织技能包时反复出现、可供借鉴的结构范式,它约定说明文件怎么写、资源目录如何划分、知识按什么顺序加载。其目标可以概括为一句话:让智能体在正确的时间激活正确的技能,并只加载当前任务真正需要的知识。

可以从三个视角理解:

  • 技术视角:技能是”结构化元数据 + 说明正文 + 可选资源”组成的轻量扩展单元,不依赖特定模型或框架,以文件形式存在,可纳入版本管理。
  • 业务视角:技能把团队的编码规范、文档模板、操作流程沉淀为机器可读的资产,新成员与新建智能体可以直接复用,不必在每次对话中重复交代。
  • 使用视角:智能体像查阅专业手册一样使用技能。先通过简短的元数据判断相关性,再读取正文获取工作步骤,最后按需查阅附录中的参考资料。

技能的作用imo不是让模型”知道得更多”,而是让它在需要时”恰好知道该知道的”。

二、背景与价值:Token 浪费从何而来

在原生智能产品的开发实践中,大量 Token 浪费主要来自两个方面:

  1. 反复猜测用户意图:本可清晰明确的意图被含糊表达,模型只能试探性输出,用户再纠正、模型再重试,一个简单需求可能消耗数倍 Token。
  2. 用复杂指令表达极简逻辑:本应一两句话就能说清的约束,被层层嵌套的长提示词包裹,关键信息反而被淹没。

常见的应对方式是把所有规范、示例都塞进系统提示词,常驻上下文。这种方式在规则较少时尚可维持,一旦规范增多,就会带来三重代价:

  • 成本上升:与当前任务无关的知识同样按输入 Token 计费。
  • 效果下降:上下文越长,关键信息越容易被稀释,模型遵循指令的稳定性变差。
  • 维护困难:提示词变成不断堆叠的”长文本”,谁都可以改,却没人能说清哪一句还有用。

针对这些问题,结构化技能设计模式的价值主要体现在四个方面:

  • 减少猜测成本:明确的触发条件让正确行为精准发生,少走弯路就少消耗 Token。
  • 降低Token消耗:通过渐进式知识加载,只有被激活的技能才会进入上下文。
  • 标准化编写方式:统一的目录结构与文件格式,让团队协作、代码评审和版本管理都有章可循。
  • 明确激活时机:技能按任务需要被唤起,而非始终占用注意力。

说明:各来源的归纳角度不同,但核心诉求一致——用结构化的知识组织方式,替代不断堆叠的提示词。

三、核心组成:技能包的四层结构

一个典型的技能包包含三个部分。按”加载时机”划分,可以看作四层:

层级 主要内容 加载时机 作用
第一层:元数据层 文件头部的结构化元数据,通常包含名称、描述等字段 始终随技能清单加载 声明技能的用途与适用边界,供智能体检索和判断是否相关
第二层:说明层 SKILL.md 正文,如激活规则、执行步骤、约束条件 技能被激活后加载 告诉智能体”这类任务该怎么做”
第三层:资源层 references/ 下的规范与最佳实践、assets/ 下的模板、可选脚本 正文需要时按需读取 提供细则、样例和可执行能力
第四层:发现层 技能目录与清单 智能体初始化时加载 决定技能能否被”看见”

各层的写法取决于所采用的设计模式,下文会结合具体示例说明。

四、工作原理:渐进式知识加载

智能体使用技能的过程可以拆解为五步:

  1. 发现:初始化时只加载所有技能的元数据,形成一份轻量级”技能清单”。
  2. 匹配:根据当前任务,将用户需求与元数据(尤其是描述字段)进行比对,判断是否相关。
  3. 激活:命中后读取 SKILL.md 正文,把该技能的工作流程与规则加入上下文。
  4. 加载资源:正文中的加载指令指向具体的参考文件、模板或脚本,此时才读取对应内容。
  5. 执行与沉淀:按技能规范完成任务;也可把本次经验整理为新资源,供后续复用。

这种分层加载的思路类似操作系统中的多级缓存,可以用以下通用伪代码表示:

  1. def build_context(task: str) -> str:
  2. # 第一步:只加载元数据,形成技能清单
  3. catalog = [load_meta(skill) for skill in discover_skills()]
  4. # 第二步:匹配与当前任务相关的技能
  5. matched = [s for s in catalog if is_relevant(s, task)]
  6. # 第三步:逐个激活,仅读取命中技能的正文
  7. sections = [catalog, f"当前任务:{task}"]
  8. for skill in matched:
  9. sections.append(read_text(skill.body_path))
  10. # 第四步:按正文中的加载指令按需读取资源
  11. for res in skill.declared_resources:
  12. sections.append(read_text(res))
  13. return "\n\n".join(sections)

Token 消耗也随之分级:

  • 元数据常驻,开销为 O(n);
  • 命中的正文按 m 累加;
  • 资源文件只在真正用到时读取。

n 为技能总数,m 为命中数量,通常 m 远小于 n。技能库不断扩充时,常驻上下文仍能保持可控。

五、五种常见的技能设计模式

上文已指出,”工具包装器”和”生成器”是两种有代表性的模式。结合业界关于智能体技能组织的通行实践,下面系统梳理五种常见设计模式。它们的区别在于:技能包主要向智能体提供什么,以及知识以什么形式加载。

模式一:工具包装器(Tool Wrapper)——纯知识封装

核心理念:SKILL.md 只声明触发条件并给出加载指令,由智能体加载 references/ 目录中的规范文件,并依据这些规则开展工作,从而在该领域”瞬间成为专家”。整个模式没有脚本,也没有输出模板,本质是对领域知识的封装。

文件结构

  1. my-skill/
  2. ├── SKILL.md # 触发描述 + 加载指令(无脚本、无模板)
  3. └── references/
  4. └── conventions.md # 规范、约定与最佳实践

适用场景:Web 开发框架的路由与依赖注入约定、响应模型规范;基础设施即代码(IaC)的资源命名与模块化约定;关系型数据库的查询优化实践;企业内部 API 设计规范等。只要存在成文且相对稳定的工程规范,都适合采用这种模式。

SKILL.md 示例

  1. ---
  2. name: web-framework-expert
  3. description: 帮助编写符合团队 Web 开发框架最佳实践的代码;
  4. 当用户需要编写该框架的路由、依赖注入相关代码,或检查接口定义是否符合规范时触发。
  5. ---
  6. # Web 开发框架规范模式
  7. ## 激活规则
  8. - 加载参考文档:`references/conventions.md`
  9. - 按照文档中的约定,确保所有生成的代码符合规范

关键点:描述字段相当于技能的”搜索索引”,必须包含具体的业务关键词,例如框架名称、路由、依赖注入等。描述过于宽泛,技能就无法被正确触发。

模式二:生成器(Generator)——模板与风格双轨制

核心理念:assets/ 中的模板决定”输出什么结构”,references/ 中的风格指南决定”如何写”。模板强制输出结构,风格指南保证内容质量,两者分工明确、互不干扰。

文件结构

  1. my-skill/
  2. ├── SKILL.md
  3. ├── assets/
  4. │ └── report-template.md # 输出结构模板(必须包含哪些章节)
  5. └── references/
  6. └── style-guide.md # 语气、措辞与格式风格指南

SKILL.md 示例

  1. ---
  2. name: weekly-report-generator
  3. description: 根据本周工作记录生成结构化周报;
  4. 当用户需要撰写周报、项目进展汇报或阶段总结时触发。
  5. ---
  6. # 周报生成模式
  7. ## 输出结构
  8. - 严格遵循 `assets/report-template.md` 中的章节顺序,不得增删一级标题
  9. - 每个章节先给结论,再列要点
  10. ## 写作风格
  11. - 参考 `references/style-guide.md`:客观、简洁,避免主观修饰与营销化表达
  12. - 数据与日期保持原始精度,不做四舍五入

适用场景:周报、技术方案、评审记录、需求文档、接口文档等格式相对固定的产出。使用这种模式时,模板负责”骨”,风格负责”肉”,二者可以分别演进。例如公司调整汇报口径时,只需更新风格指南,无须改动模板。

模式三:脚本执行器(Script Runner)——确定性工作交给代码

核心理念:部分任务要求严格确定性,比如文件格式转换、批量数据校验、结构化代码生成。这类工作应封装为可执行脚本,SKILL.md 只负责说明脚本何时运行、如何传参、输出放在哪里、失败如何处理。模型负责理解与决策,脚本负责执行与产出。

文件结构

  1. my-skill/
  2. ├── SKILL.md
  3. └── scripts/
  4. └── convert_format.py # 输入文件路径,输出转换后的文件

SKILL.md 示例(节选)

  1. ## 执行规则
  2. 1. 读取用户提供的数据文件路径
  3. 2. 运行 `scripts/convert_format.py <输入路径> <输出路径>`
  4. 3. 若脚本返回非零退出码,读取日志说明原因,不要自行修改原始数据

适用场景:结构化文档转换、配置校验、大批量文本处理等规则明确、不需要创造力的环节。

注意事项:脚本须有清晰的输入输出约定,并对错误给出明确反馈;模型只能调用,不应改写脚本逻辑。

模式四:编排器(Orchestrator)——多技能协作的调度者

核心理念:复杂任务往往需要依次调用多个技能或工具。编排器模式把”调用顺序、分支条件、汇总方式”写入 SKILL.md,让智能体像项目经理一样调度其他能力,自己只负责决策和整合。

文件结构

  1. release-check/
  2. ├── SKILL.md # 描述整体流程与分支条件
  3. └── references/
  4. ├── checklist.md # 上线检查项
  5. └── rollback.md # 回滚流程

SKILL.md 示例(节选)

  1. ## 执行流程
  2. 1. 调用"代码评审"技能检查变更
  3. 2. 调用"测试执行"技能运行用例
  4. 3. 全部通过后,按 `references/checklist.md` 逐项确认
  5. 4. 任一环节失败时,按 `references/rollback.md` 处理并终止流程

适用场景:需求评审、上线检查、故障排查等需要多个专项能力配合的流程性工作。这种模式下,技能数量随业务增加而增长,元数据的规范命名与准确描述就越发重要。

模式五:校验器(Evaluator)——质量守门人

核心理念:生成不等于合格。校验器模式把验收标准写入 SKILL.md,规定任务完成后必须执行的检查项以及不通过时的修正路径,形成”生成—检查—修正”的闭环。

SKILL.md 示例(节选)

  1. ## 完成标准
  2. - 代码通过项目约定的静态检查
  3. - 新增逻辑具备对应的单元测试,且测试全部通过
  4. - 检查不通过时,根据报错信息修正后重新校验,最多重试 3 次

适用场景:代码提交前的质量把关、文档完整性检查、数据结果一致性核对等。它可以单独使用,也可以叠加在其他模式之上:生成器产出内容后,再由校验器确认是否满足规范。

五种模式对比

模式 核心载体 主要解决的问题 适用任务特征
工具包装器 references/ 规范文档 领域知识缺失、行为不规范 有成文规范可依
生成器 assets/ 模板 + references/ 风格指南 输出结构不统一、风格不一致 产出格式相对固定
脚本执行器 scripts/ 可执行脚本 确定性操作靠模型执行,结果不稳定 规则明确、可程序化
编排器 SKILL.md 流程 + 多份 references/ 多环节任务缺统筹 需要多技能协同
校验器 SKILL.md 检查清单 输出质量无法保证 有明确验收标准

六、与相关概念的区别

概念 本质 与技能的关系
提示词(Prompt) 一次性输入的指令文本,通常写在代码或配置中并长期占用上下文 技能也是提示信息,但按目录组织、按需加载;提示词直接嵌入流程,技能则在需要时才被读取
工具调用(Function Calling) 模型通过结构化参数调用外部函数,返回执行结果 工具提供”做”的能力,技能提供”何时做、怎么做、遵守什么规则”的知识;脚本执行器模式是二者结合,模型决策、脚本执行
检索增强生成(RAG) 从知识库中检索文本片段拼接进上下文 两者都按需注入信息。RAG 检索的是不断更新的海量文档,技能加载的是人工编写、结构固定的规范与流程,更接近”操作手册”
子智能体(Sub-agent) 拥有独立上下文与职责的智能体实例 技能是知识单元,子智能体是执行单元;复杂系统中技能可被多个智能体共享
工作流(Workflow) 预先定义好的确定性流程编排 工作流节点固定,技能由模型判断并调用,更灵活;高度确定的流程也可用技能中的脚本实现

简言之,技能介于”静态提示词”与”动态工具”之间:比提示词更结构化、更节省上下文,比工具更强调知识与规范。

七、使用注意事项

  1. 写好描述字段:采用”用途 + 触发场景 + 典型关键词”的写法,必要时补充”何时不应使用”。避免”帮助用户完成任务”这类空泛表述,也要避免与已有技能重叠。
  2. 保持单一职责:一个技能只解决一类问题。职责过多会让描述难以精确,增加误触发风险。
  3. 控制加载层级:SKILL.md 正文只保留决策所需信息,细则放进 references/。正文像 README,细节像手册章节,不要让一次加载吃掉过多上下文。
  4. 注意内容可信与执行安全:规范文件可能来自外部,运行脚本可能接触敏感数据。技能资源应来自可信来源,脚本宜在受控环境中运行并遵循最小权限原则,同时避免把密钥等敏感信息写入技能文件。
  5. 纳入版本管理:技能本质是”给智能体看的代码”,应像代码一样进行评审、测试与版本记录。描述字段的改动会直接影响触发行为,需要回归验证。
  6. 建立可观测性:记录技能被触发或未触发的情况、上下文消耗和任务完成质量,据此持续优化描述与结构。
  7. 明确适用边界:技能依赖大模型的理解与遵循能力,并不适合替代严格确定性的业务逻辑。涉及资金、权限、数据安全等关键操作时,应在程序层面做硬校验。

八、总结

智能体技能设计模式,是把领域知识、输出规范和执行流程组织成”元数据 + 正文 + 资源”三层结构的方法论,核心是渐进式知识加载:智能体先凭元数据判断是否相关,再读取正文与资源,从而在不牺牲效果的前提下减少 Token 浪费。

五种模式各有侧重:工具包装器封装知识,生成器约束产出,脚本执行器负责确定性执行,编排器统筹多技能协作,校验器保障质量。实际项目中它们常常组合使用,例如”校验器 + 生成器”确保产出合规,”工具包装器 + 编排器”覆盖完整流程。

技能设计模式的意义不止于省 Token,更在于让智能体的能力从依赖个人经验,变成团队可复用、可评审、可持续演进的工程资产。借助百度智能云等主流云平台的智能体开发能力时,这些模式同样可以作为技能工程化建设的参考框架。

发表评论

活动