智能体技能设计模式是什么?五种 SKILL.md 写法解析
作者:起个名字好难2026.11.16 11:40浏览量:0简介:本文系统解析智能体技能(Skill)设计模式:它是什么、为什么能减少 Token 浪费,以及工具包装器、生成器、脚本执行器、编排器、校验器五种 SKILL.md 设计模式各自的结构、原理与适用边界。同时梳理技能与提示词、工具调用、检索增强等概念的区别及落地注意事项,帮助开发者编写出触发精准、结构规范、易于协作的高质量技能包。
一、什么是智能体技能设计模式
智能体技能(Agent Skill,业内常称”技能包”)是一种面向特定任务的可复用能力封装。它以一份说明文件为核心,文件按约定命名为 SKILL.md,并搭配若干资源文件或脚本,为智能体提供完成某类任务所需的规则、流程、模板或领域知识。
技能设计模式,是指在组织技能包时反复出现、可供借鉴的结构范式,它约定说明文件怎么写、资源目录如何划分、知识按什么顺序加载。其目标可以概括为一句话:让智能体在正确的时间激活正确的技能,并只加载当前任务真正需要的知识。
可以从三个视角理解:
- 技术视角:技能是”结构化元数据 + 说明正文 + 可选资源”组成的轻量扩展单元,不依赖特定模型或框架,以文件形式存在,可纳入版本管理。
- 业务视角:技能把团队的编码规范、文档模板、操作流程沉淀为机器可读的资产,新成员与新建智能体可以直接复用,不必在每次对话中重复交代。
- 使用视角:智能体像查阅专业手册一样使用技能。先通过简短的元数据判断相关性,再读取正文获取工作步骤,最后按需查阅附录中的参考资料。
技能的作用imo不是让模型”知道得更多”,而是让它在需要时”恰好知道该知道的”。
二、背景与价值:Token 浪费从何而来
在原生智能产品的开发实践中,大量 Token 浪费主要来自两个方面:
- 反复猜测用户意图:本可清晰明确的意图被含糊表达,模型只能试探性输出,用户再纠正、模型再重试,一个简单需求可能消耗数倍 Token。
- 用复杂指令表达极简逻辑:本应一两句话就能说清的约束,被层层嵌套的长提示词包裹,关键信息反而被淹没。
常见的应对方式是把所有规范、示例都塞进系统提示词,常驻上下文。这种方式在规则较少时尚可维持,一旦规范增多,就会带来三重代价:
- 成本上升:与当前任务无关的知识同样按输入 Token 计费。
- 效果下降:上下文越长,关键信息越容易被稀释,模型遵循指令的稳定性变差。
- 维护困难:提示词变成不断堆叠的”长文本”,谁都可以改,却没人能说清哪一句还有用。
针对这些问题,结构化技能设计模式的价值主要体现在四个方面:
- 减少猜测成本:明确的触发条件让正确行为精准发生,少走弯路就少消耗 Token。
- 降低Token消耗:通过渐进式知识加载,只有被激活的技能才会进入上下文。
- 标准化编写方式:统一的目录结构与文件格式,让团队协作、代码评审和版本管理都有章可循。
- 明确激活时机:技能按任务需要被唤起,而非始终占用注意力。
说明:各来源的归纳角度不同,但核心诉求一致——用结构化的知识组织方式,替代不断堆叠的提示词。
三、核心组成:技能包的四层结构
一个典型的技能包包含三个部分。按”加载时机”划分,可以看作四层:
| 层级 | 主要内容 | 加载时机 | 作用 |
|---|---|---|---|
| 第一层:元数据层 | 文件头部的结构化元数据,通常包含名称、描述等字段 | 始终随技能清单加载 | 声明技能的用途与适用边界,供智能体检索和判断是否相关 |
| 第二层:说明层 | SKILL.md 正文,如激活规则、执行步骤、约束条件 | 技能被激活后加载 | 告诉智能体”这类任务该怎么做” |
| 第三层:资源层 | references/ 下的规范与最佳实践、assets/ 下的模板、可选脚本 | 正文需要时按需读取 | 提供细则、样例和可执行能力 |
| 第四层:发现层 | 技能目录与清单 | 智能体初始化时加载 | 决定技能能否被”看见” |
各层的写法取决于所采用的设计模式,下文会结合具体示例说明。
四、工作原理:渐进式知识加载
智能体使用技能的过程可以拆解为五步:
- 发现:初始化时只加载所有技能的元数据,形成一份轻量级”技能清单”。
- 匹配:根据当前任务,将用户需求与元数据(尤其是描述字段)进行比对,判断是否相关。
- 激活:命中后读取 SKILL.md 正文,把该技能的工作流程与规则加入上下文。
- 加载资源:正文中的加载指令指向具体的参考文件、模板或脚本,此时才读取对应内容。
- 执行与沉淀:按技能规范完成任务;也可把本次经验整理为新资源,供后续复用。
这种分层加载的思路类似操作系统中的多级缓存,可以用以下通用伪代码表示:
def build_context(task: str) -> str:# 第一步:只加载元数据,形成技能清单catalog = [load_meta(skill) for skill in discover_skills()]# 第二步:匹配与当前任务相关的技能matched = [s for s in catalog if is_relevant(s, task)]# 第三步:逐个激活,仅读取命中技能的正文sections = [catalog, f"当前任务:{task}"]for skill in matched:sections.append(read_text(skill.body_path))# 第四步:按正文中的加载指令按需读取资源for res in skill.declared_resources:sections.append(read_text(res))return "\n\n".join(sections)
Token 消耗也随之分级:
- 元数据常驻,开销为 O(n);
- 命中的正文按 m 累加;
- 资源文件只在真正用到时读取。
n 为技能总数,m 为命中数量,通常 m 远小于 n。技能库不断扩充时,常驻上下文仍能保持可控。
五、五种常见的技能设计模式
上文已指出,”工具包装器”和”生成器”是两种有代表性的模式。结合业界关于智能体技能组织的通行实践,下面系统梳理五种常见设计模式。它们的区别在于:技能包主要向智能体提供什么,以及知识以什么形式加载。
模式一:工具包装器(Tool Wrapper)——纯知识封装
核心理念:SKILL.md 只声明触发条件并给出加载指令,由智能体加载 references/ 目录中的规范文件,并依据这些规则开展工作,从而在该领域”瞬间成为专家”。整个模式没有脚本,也没有输出模板,本质是对领域知识的封装。
文件结构
my-skill/├── SKILL.md # 触发描述 + 加载指令(无脚本、无模板)└── references/└── conventions.md # 规范、约定与最佳实践
适用场景:Web 开发框架的路由与依赖注入约定、响应模型规范;基础设施即代码(IaC)的资源命名与模块化约定;关系型数据库的查询优化实践;企业内部 API 设计规范等。只要存在成文且相对稳定的工程规范,都适合采用这种模式。
SKILL.md 示例
---name: web-framework-expertdescription: 帮助编写符合团队 Web 开发框架最佳实践的代码;当用户需要编写该框架的路由、依赖注入相关代码,或检查接口定义是否符合规范时触发。---# Web 开发框架规范模式## 激活规则- 加载参考文档:`references/conventions.md`- 按照文档中的约定,确保所有生成的代码符合规范
关键点:描述字段相当于技能的”搜索索引”,必须包含具体的业务关键词,例如框架名称、路由、依赖注入等。描述过于宽泛,技能就无法被正确触发。
模式二:生成器(Generator)——模板与风格双轨制
核心理念:assets/ 中的模板决定”输出什么结构”,references/ 中的风格指南决定”如何写”。模板强制输出结构,风格指南保证内容质量,两者分工明确、互不干扰。
文件结构
my-skill/├── SKILL.md├── assets/│ └── report-template.md # 输出结构模板(必须包含哪些章节)└── references/└── style-guide.md # 语气、措辞与格式风格指南
SKILL.md 示例
---name: weekly-report-generatordescription: 根据本周工作记录生成结构化周报;当用户需要撰写周报、项目进展汇报或阶段总结时触发。---# 周报生成模式## 输出结构- 严格遵循 `assets/report-template.md` 中的章节顺序,不得增删一级标题- 每个章节先给结论,再列要点## 写作风格- 参考 `references/style-guide.md`:客观、简洁,避免主观修饰与营销化表达- 数据与日期保持原始精度,不做四舍五入
适用场景:周报、技术方案、评审记录、需求文档、接口文档等格式相对固定的产出。使用这种模式时,模板负责”骨”,风格负责”肉”,二者可以分别演进。例如公司调整汇报口径时,只需更新风格指南,无须改动模板。
模式三:脚本执行器(Script Runner)——确定性工作交给代码
核心理念:部分任务要求严格确定性,比如文件格式转换、批量数据校验、结构化代码生成。这类工作应封装为可执行脚本,SKILL.md 只负责说明脚本何时运行、如何传参、输出放在哪里、失败如何处理。模型负责理解与决策,脚本负责执行与产出。
文件结构
my-skill/├── SKILL.md└── scripts/└── convert_format.py # 输入文件路径,输出转换后的文件
SKILL.md 示例(节选)
## 执行规则1. 读取用户提供的数据文件路径2. 运行 `scripts/convert_format.py <输入路径> <输出路径>`3. 若脚本返回非零退出码,读取日志说明原因,不要自行修改原始数据
适用场景:结构化文档转换、配置校验、大批量文本处理等规则明确、不需要创造力的环节。
注意事项:脚本须有清晰的输入输出约定,并对错误给出明确反馈;模型只能调用,不应改写脚本逻辑。
模式四:编排器(Orchestrator)——多技能协作的调度者
核心理念:复杂任务往往需要依次调用多个技能或工具。编排器模式把”调用顺序、分支条件、汇总方式”写入 SKILL.md,让智能体像项目经理一样调度其他能力,自己只负责决策和整合。
文件结构
release-check/├── SKILL.md # 描述整体流程与分支条件└── references/├── checklist.md # 上线检查项└── rollback.md # 回滚流程
SKILL.md 示例(节选)
## 执行流程1. 调用"代码评审"技能检查变更2. 调用"测试执行"技能运行用例3. 全部通过后,按 `references/checklist.md` 逐项确认4. 任一环节失败时,按 `references/rollback.md` 处理并终止流程
适用场景:需求评审、上线检查、故障排查等需要多个专项能力配合的流程性工作。这种模式下,技能数量随业务增加而增长,元数据的规范命名与准确描述就越发重要。
模式五:校验器(Evaluator)——质量守门人
核心理念:生成不等于合格。校验器模式把验收标准写入 SKILL.md,规定任务完成后必须执行的检查项以及不通过时的修正路径,形成”生成—检查—修正”的闭环。
SKILL.md 示例(节选)
## 完成标准- 代码通过项目约定的静态检查- 新增逻辑具备对应的单元测试,且测试全部通过- 检查不通过时,根据报错信息修正后重新校验,最多重试 3 次
适用场景:代码提交前的质量把关、文档完整性检查、数据结果一致性核对等。它可以单独使用,也可以叠加在其他模式之上:生成器产出内容后,再由校验器确认是否满足规范。
五种模式对比
| 模式 | 核心载体 | 主要解决的问题 | 适用任务特征 |
|---|---|---|---|
| 工具包装器 | references/ 规范文档 | 领域知识缺失、行为不规范 | 有成文规范可依 |
| 生成器 | assets/ 模板 + references/ 风格指南 | 输出结构不统一、风格不一致 | 产出格式相对固定 |
| 脚本执行器 | scripts/ 可执行脚本 | 确定性操作靠模型执行,结果不稳定 | 规则明确、可程序化 |
| 编排器 | SKILL.md 流程 + 多份 references/ | 多环节任务缺统筹 | 需要多技能协同 |
| 校验器 | SKILL.md 检查清单 | 输出质量无法保证 | 有明确验收标准 |
六、与相关概念的区别
| 概念 | 本质 | 与技能的关系 |
|---|---|---|
| 提示词(Prompt) | 一次性输入的指令文本,通常写在代码或配置中并长期占用上下文 | 技能也是提示信息,但按目录组织、按需加载;提示词直接嵌入流程,技能则在需要时才被读取 |
| 工具调用(Function Calling) | 模型通过结构化参数调用外部函数,返回执行结果 | 工具提供”做”的能力,技能提供”何时做、怎么做、遵守什么规则”的知识;脚本执行器模式是二者结合,模型决策、脚本执行 |
| 检索增强生成(RAG) | 从知识库中检索文本片段拼接进上下文 | 两者都按需注入信息。RAG 检索的是不断更新的海量文档,技能加载的是人工编写、结构固定的规范与流程,更接近”操作手册” |
| 子智能体(Sub-agent) | 拥有独立上下文与职责的智能体实例 | 技能是知识单元,子智能体是执行单元;复杂系统中技能可被多个智能体共享 |
| 工作流(Workflow) | 预先定义好的确定性流程编排 | 工作流节点固定,技能由模型判断并调用,更灵活;高度确定的流程也可用技能中的脚本实现 |
简言之,技能介于”静态提示词”与”动态工具”之间:比提示词更结构化、更节省上下文,比工具更强调知识与规范。
七、使用注意事项
- 写好描述字段:采用”用途 + 触发场景 + 典型关键词”的写法,必要时补充”何时不应使用”。避免”帮助用户完成任务”这类空泛表述,也要避免与已有技能重叠。
- 保持单一职责:一个技能只解决一类问题。职责过多会让描述难以精确,增加误触发风险。
- 控制加载层级:SKILL.md 正文只保留决策所需信息,细则放进 references/。正文像 README,细节像手册章节,不要让一次加载吃掉过多上下文。
- 注意内容可信与执行安全:规范文件可能来自外部,运行脚本可能接触敏感数据。技能资源应来自可信来源,脚本宜在受控环境中运行并遵循最小权限原则,同时避免把密钥等敏感信息写入技能文件。
- 纳入版本管理:技能本质是”给智能体看的代码”,应像代码一样进行评审、测试与版本记录。描述字段的改动会直接影响触发行为,需要回归验证。
- 建立可观测性:记录技能被触发或未触发的情况、上下文消耗和任务完成质量,据此持续优化描述与结构。
- 明确适用边界:技能依赖大模型的理解与遵循能力,并不适合替代严格确定性的业务逻辑。涉及资金、权限、数据安全等关键操作时,应在程序层面做硬校验。
八、总结
智能体技能设计模式,是把领域知识、输出规范和执行流程组织成”元数据 + 正文 + 资源”三层结构的方法论,核心是渐进式知识加载:智能体先凭元数据判断是否相关,再读取正文与资源,从而在不牺牲效果的前提下减少 Token 浪费。
五种模式各有侧重:工具包装器封装知识,生成器约束产出,脚本执行器负责确定性执行,编排器统筹多技能协作,校验器保障质量。实际项目中它们常常组合使用,例如”校验器 + 生成器”确保产出合规,”工具包装器 + 编排器”覆盖完整流程。
技能设计模式的意义不止于省 Token,更在于让智能体的能力从依赖个人经验,变成团队可复用、可评审、可持续演进的工程资产。借助百度智能云等主流云平台的智能体开发能力时,这些模式同样可以作为技能工程化建设的参考框架。

登录后可评论,请前往 登录 或 注册