被问得最多的问题之一就是“能不能把 Agent 技能直接写成一段提示词塞进系统提示里”我的答案从来都是“别这么干”。如果你手里只有一两个技能长提示词方案确实能用但一旦技能数量上到五个、十个或者你希望技能能被不同的 Agent 复用这种思路就会迅速变成一场灾难。今天我想认真聊一聊 Agent Skills 为什么不能退化成“长提示词”以及 SKILL.md、按需加载、权限边界这三个设计到底各自解决了什么。我见过太多人把技能做成几百行的“超级指令”结果模型经常在无关任务里强行调用它上下文被占得满满当当响应慢效果还飘。问题不在于提示词水平而是结构不对。提示词本质上是“一段静态文本”而技能需要的是一套“可发现、可加载、可约束的协议”。这篇文章会从为什么长提示词不行说起然后逐个拆解 SKILL.md 的设计要点、按需加载的实现方式、权限边界的工程化落地最后给出一套可以直接参考的完整示例。无论你是在搭建个人助理、企业内部知识助手还是研究复杂 Agent 应用这篇文章的思路都能直接落地。1. 长提示词方案的根本问题静态文本撑不起动态技能先说个最常见的场景。某团队做了一个“会议纪要助手”希望它具备四个能力抽取待办项、格式化会议结论、关联历史决策、生成会议摘要。最初实现时开发者把四条指令直接写进 system prompt大概每段 800 字。单次使用时效果还行但随后团队加了“项目周报生成”“代码评审提醒”“竞品信息整理”等六个新技能整个系统提示涨到一万多字。从此问题不断。1.1 上下文被无关内容稀释模型决策质量下滑这个问题在技术上非常直白上下文窗口是硬约束。假设一个模型的有效上下文是 64K token而技能指令累计占掉 12K等于每轮对话都少了 12K 的容量来放真实对话历史、工具返回结果和中间推理。更关键的是模型在决策时不会真的读完所有技能。一项内部测试里我们给模型塞了 8 个技能指令当用户请求“查一下上月竞品动态”时模型有 20% 的概率先调用“周报生成”而不是“竞品分析”因为它被周报指令里“所有输入均可作为周报素材”这句话吸引走了。你可能会说“那我把每个技能开头写明调用条件模型就能区分了”。实测下来改善有限。条件描述得越细每条指令越长到后面连编写的人自己都分不清边界。提示词对模型只是“引导”不是“约束”模型没有能力判断自己是否正确执行了某个技能也不存在机制阻止它在无效场景乱用。1.2 技能间的指令冲突让维护成本失控长提示词的第二个致命伤是技能与技能之间容易互相污染。之前有个项目一个技能说“输出必须用 Markdown 表格”另一个技能说“所有输出用自然语言段落”。两条指令同时存在于 system prompt 时模型有时候会真的输出一个既是表格又是段落的怪东西。这种冲突不会在单技能测试时暴露只有上到多技能并行才发现。更隐蔽的是技能更新导致的“回退问题”。某天你更新了“周报生成”的格式要求加了半页新规则结果发现模型在“会议纪要”场景里突然也多出个“按周报格式输出”的倾向。原因无他——新文本恰好接在纪要技能后面模型把相邻段落理解为补充规则。这种连锁反应是纯文本方案固有的你永远要担心一段改动影响所有技能。1.3 长提示词无法表达“能力边界”还有一个常被忽略的点长提示词方案里模型只知道“你有哪些指令”不知道“你被允许动什么资源”。比如“文件搜索”技能它能读项目目录还是整个磁盘“网页抓取”技能能访问内网还是仅限公开页面这些权限信息在纯文本里只能靠“请只访问……”“不要访问……”这种措辞表达模型可能遵守也可能不遵守——它本质上还是建议不是强制。这也是我后来坚持引入权限边界的原因。技能一旦要触及文件系统、外部 API、数据库光靠提示词约束就是裸奔。你需要一套明确的资源访问描述让运行框架在调用前就能做拦截而不是等模型撞到违规再补救。2. 换个角度看技能从“指令”到“能力封装协议”既然长提示词有这么多问题那 Agent Skills 到底应该是什么我自己的理解是技能不应该是一段“给模型读的说明”而应该是一份“给 Agent 运行环境看的协议”。协议不只是自然语言还包含结构化元数据、调用前置条件、资源权限清单和验证方法。模型阅读它只是其中一个环节框架层面还要能索引它、加载它、约束它。2.1 SKILL.md 作为技能的唯一入口SKILL.md 是这套协议里的核心文件。它承担三个职责第一给模型提供“何时该用此技能”的判断依据第二给 Agent 运行环境提供可解析的元数据比如技能名称、描述、依赖资源第三给开发者提供更新技能的稳定入口。不是所有内容都要写进 SKILL.md它更像技能的说明书和档案而不是技能的正文。举个例子一个“电商评论情感分析”技能SKILL.md 里可以写“本技能接受 CSV 或 JSON 格式的评论文本输出按积极、消极、中性分类的统计表。需要访问 /data/reviews 路径的读取权限。”模型读到这里就知道自己能不能胜任运行环境读到权限声明就知道该怎么隔离。这比在 system prompt 里写“你可以读评论文件”要清晰得多。2.2 为什么叫“协议”而不是“指令集”你可能会问既然 SKILL.md 里也有很多自然语言指令它和长提示词有什么本质区别区别在于“形式”和“关系”。长提示词是“模型被动接收的一堆规则”SKILL.md 是“模型按需取用的能力条目”。SKILL.md 不会常驻上下文它有独立的生命周期注册、检索、加载、执行、注销。模型不是一次性读完所有技能再干活的它每次只加载当前任务真正需要的那一两个。这种模型与技能之间的“按需连接”关系就像操作系统里的动态链接库。程序启动时不会加载所有 DLL它只加载当前执行路径依赖的那几个。Agent 也一样用户请求“分析这份合同的风险条款”调度器检索到“合同分析”技能加载对应 SKILL.md再注入必要的参考示例。其他技能在上下文中不会出现自然不会干扰决策。2.3 技能和工具的边界在哪里实践中很多人还会混淆“技能”和“工具”。我的简单界定是工具是原子操作比如“发送 HTTP 请求”“执行一段代码”“读取某个文件”技能是把多个工具、多个推理步骤按业务逻辑组织起来的能力比如“做季度销售复盘”可能要调用“订单查询”“数据聚合”“报告模板生成”三个工具并且按特定顺序执行。技能可以内部依赖工具但工具本身不表达业务目标。SKILL.md 描述的正是这个业务目标和过程约束所以它才不能被某一行 function call 定义替代。3. 三块基石详解SKILL.md、按需加载、权限边界现在正式进入正题。我会逐个拆解这三块设计讲清楚每一块解决什么问题、应该怎么搭以及有哪些容易踩的坑。3.1 SKILL.md元数据与正文的平衡一个合格 SKILL.md 文件的结构我一般建议分成两大部分头部元数据YAML frontmatter和正文说明。头部元数据给机器读正文说明给模型读。这是长提示词方案里完全没有的“分层”也是它能被索引和检索的关键。头部元数据至少需要这些字段字段作用建议写法name技能唯一标识用于检索注册project-reviewdescription用一两句话概括适用场景、输入输出用于模型判断是否调用宜具体不宜空泛version技能版本号支持灰度更新1.3.1permissions声明所需资源权限read:/docsapi:metrics:rdependencies依赖的其它技能或工具避免技能加载后缺东少西author维护者标识方便后续问询如果是团队内部正文部分才是给模型看的操作说明。我建议控制在 400 到 800 字以内超过这个长度就说明技能拆得不够细。正文不是法律条文不需要把所有情况都列出来而是告诉模型“完成任务的目标、可用的输入来源、不可逾越的底线、什么时候要停下来向用户确认”。这比巨细无遗的长篇指令更有效因为模型真正擅长的是在约束内自主推理你给它过多指令反而压制它的判断力。举个例子一个“合同风险分析”技能正文可以这样组织目标分析合同文本中的潜在风险条款按“高、中、低”三级输出风险清单。输入用户提供的 PDF/文字或读取contracts/目录下最新文件。约束只基于合同明文内容分析不推测隐含信息风险等级不低于“中”时必须给出依据摘要。如果文本缺失关键章节直接输出缺失章节列表并停止不脑补内容。这种写法比“你要像资深法务一样仔细审阅……”有效得多。你会发现自己不再需要写那么多“你要”“你必须”模型反而更清楚该做什么。3.2 按需加载用“检索-决策-加载”替代全量注入按需加载的实现并不复杂核心就是一个调度器。流程是这样的系统初始化时只加载所有技能的 SKILL.md 元数据description、permissions 这些几百字节的概要不是全文比如 20 个技能加起来才 3K token。每轮用户请求进来调度器基于元数据做一次语义匹配选出 1 到 2 个候选技能再加载它们的完整正文到上下文。这种两段式设计有立竿见影的效果。20 个技能全量注入 12K token 的场景按需加载后平均每轮只增加约 1.5K token。上下文压力小模型注意力更集中在真实任务里响应速度也快。方案平均上下文占用技能间冲突新增技能成本运行时决策质量全量写入 system prompt约 12K token频繁出现修改可能波及其他技能被无关技能干扰按需加载 SKILL.md约 1.5K token基本消失新增独立文件互不影响聚焦当前任务3.3 权限边界把“给模型的建议”升级为“框架的强制约束”权限边界这一块我认为是整个 Agent Skills 设计里最容易被低估、也最值得投入的部分。很多人觉得“反正模型不会乱来”但实测告诉我模型在执行多步任务时对权限的把握远远没有我们想象中稳定。可能只是一句“请总结一下桌面上的文件”模型就会尝试遍历个人目录也可能在处理“检查网络配置”这类任务时莫名调用敏感接口。权限声明的核心思路是在 SKILL.md 元数据里明确列出该技能需要的资源范围运行环境在调用前后强制执行。比如read:/docs/reviews表示技能只能读取该目录写权限没有。如果模型试图访问read:/data/customer-orders框架会直接拦截并返回“权限不足”模型会基于这个反馈重新选择路径。这比在提示词里写“请不要访问客户订单数据”可靠得多因为拦截是代码级别不是建议级别。权限描述需要定义清楚资源类型和操作级别一份典型声明长这样permissions: - resource: file action: read path: /docs/reviews - resource: api action: call endpoint: review-service/* - resource: runtime action: none我给的实际建议是“最小权限原则”。开发技能时先只声明最低限度权限测试时再逐步放宽。你会发现很多技能最初声明的权限比实际需要的多收紧后不仅更安全模型乱试的概率也下降——因为可选路径少了反而更容易走对流程。4. 一份可直接参考的设计示例假设要做一个“信息聚合技巧”库理论讲再多都不如一个具体设计落地。我在这里模拟一个真实项目团队要做一个信息聚合技能库包含四个技能网络资料采集、本地文档检索、信息去重合并、周报生成。下面我从 SKILL.md 结构、按需加载流程、权限边界三个维度一一列出方案。4.1 技能库的目录与初始化结构我建议的目录结构如下skills/ web-collect/ SKILL.md reference/ fetch_examples.md doc-search/ SKILL.md dedup-merge/ SKILL.md week-report/ SKILL.md初始化阶段调度器只读取每个目录下SKILL.md的 YAML 元数据构建一个“技能摘要索引”。这一步开销极小100 个技能也能在毫秒级完成内存加载。web-collect/SKILL.md的元数据示例--- name: web-collect description: 根据主题词抓取公开网页内容提取正文与来源链接适用于快速收集背景资料。 version: 1.2.0 permissions: - resource: network action: fetch allow_domains: [*.example-news.com, *.example-tech.com] block_local: true dependencies: [] --- # 网络资料采集技能 目标根据用户提供的主题词检索公开网络信息并返回结构化摘要。 输入主题词、可选时间范围、可选站点白名单。 输出Markdown 列表包含标题、来源、摘要、抓取时间。 约束 - 只访问 permissions 允许的域名不访问内网地址不访问本地文件。 - 每次最多抓取 5 个页面避免重复抓取同一站点。 - 页面标题缺失时标注“未命名来源”不推测标题。 - 如果 all results 来自同一域名停止抓取并提示用户是否继续。注意这里的 description 写得既具体又克制模型能很快判断“什么时候该用”而不是读完整篇正文才能意会。权限也明确了allow_domains框架会在网络访问层面做真实拦截而不是指望模型自觉。4.2 按需加载的调度流程表达我不画图直接用文字描述这个流程用户输入“帮我找一下最近一个月关于边缘计算在工业场景的落地案例然后整理成周报素材。”调度器读取技能摘要索引对请求做语义匹配。命中web-collect需要网络抓取以及week-report需要周报输出格式两个候选技能的 description 匹配分数均高于阈值。只加载这两个目录下的 SKILL.md 完整正文其余技能保持未加载状态。Agent 先执行web-collect获得若干抓取结果再执行dedup-merge此时发现需要它动态加载对重复内容合并最后交给week-report生成素材。动态加载这个机制很有意思它允许 Agent 在实际执行到第二步时“突然想起来”还需要去重能力此时再加载第三个技能不会导致系统一开始就把所有技能都注入上下文。这就解决了长提示词方案里“预测所有可能路径”的难题。4.3 权限边界如何在实际运行中体现在运行时框架会维护一个“当前会话权限上下文”。当一个技能被加载它的权限声明被合并进当前上下文技能执行完毕卸载时权限也随之回收。这样不同技能不会累积权限避免了长会话里权限开销越来越大的问题。比如doc-search技能声明了read:/docs/archive和read:/docs/reviews而week-report只声明read:/docs/reviews和write:/tmp/report。当 Agent 从“文档搜索”切换到“生成周报”时它的读取权限缩窄到仅 reviews 目录而获得的是临时目录的写入权。这比一个全局超级权限上下文安全得多也更容易审计。如果模型在周报生成过程中忽然想读取归档目录也许它认为周报需要旧数据框架会返回“权限不足”错误模型便会意识到自己的操作超出了当前技能边界。它可能向用户确认也可能在不带权限需求的前提下完成任务。这种强约束机制是纯提示词方案给不了的。5. 实操中的关键细节把 SKILL.md 写对、写薄、写清楚理论模型聊完了来看一些我实际用下来的经验。这些细节决定你照着方案落地是顺利还是到处踩坑。5.1 描述别用“万能词”用“触发场景”我发现很多初版 SKILL.md 的 description 都有一个问题太抽象。比如“处理文本”“辅助工作”“提供信息”这种。模型没法从这些词推断触发条件。正确写法是把触发场景、输入特征、期望输出都融合进去。不推荐的写法推荐的写法处理文本将 Markdown 格式的会议记录转换为带待办事项列表的结论摘要提供信息根据主题词检索公司内部 wiki 页面输出摘要和原始链接辅助分析对 CSV 格式的销售数据做月度同比分析输出趋势图和异常标注写周报将本周完成的任务列表按“进展、问题、下周计划”三段式整理为周报模型做技能匹配时本质上是在读这段描述所以描述的语气应该是“当用户想要……并且……时技能可以提供……”这样具体的句式而不是罗列一堆形容词。5.2 正文的“三段式”模板我写 SKILL.md 正文时基本遵循一个三段式模板既能控制长度又不会遗漏关键要素目标一句话说明技能完成什么给模型一个稳定方向。输入/输出明确输入来自哪里、输出用什么格式减少模型自由发挥空间。约束与边界列出底线清单包括不该访问什么、不该推断什么、什么情况下需要向用户确认。这个模板的好处是维护方便。每次要改技能先看是哪一段出了问题是方向没立住还是格式没说清还是又一次越权访问。对应区段修改即可不必像长提示词那样担惊受怕改一行影响全局。另外如果某次更新要新增一大段逻辑我通常会反思是不是该拆新技能了这个“膨胀感”是拆分技能的好信号。5.3 别把技能间的关系写死在 SKILL.md 正文里另一个常见失误是把“技能调用其它技能的方式”直接写死。比如说“请先调用 web-collect 再调用 dedup-merge”。这种做法当时可能有效但一旦技能升级或者参数变化硬编码的调用关系就会失效而且会让模型囿于固定流程失去自主规划能力。更好的做法是只声明依赖dependencies让调度器自行解决执行顺序。SKILL.md 里只需要说“本技能需要具备访问粗粒度文本合并能力”并在元数据里加dependencies: [dedup-merge]。调度器在加载本技能时自动检查依赖是否已加载未加载则按依赖顺序加载。这既保证了执行所需能力又给模型留下了灵活调度的空间。6. 排查指南按需加载和权限拦截的常见问题我在实际操作中遇到过不少问题这里把最常见的几种整理成一张速查表并补充对应的排查思路。6.1 技能“召之不来”或“招之即错”怎么办按需加载最常见的抱怨是“该用技能 A 的时候模型却加载了技能 B”。排查时我一般按以下顺序检查先看 description 是否有足够具体的触发词和场景。描述里写“网络资料收集”“事务提醒”模型很难区分。检查是否技能数量太少导致匹配阈值过低。只有三四个技能时模型可能把“任何请求”都当成“需要技能帮助”此时要调高匹配阈值允许“无技能可用”的空场景存在。检查候选技能之间是否存在描述重叠。比如“网络文本抓取”和“网页正文解析”两个技能如果都描述为“处理网页内容”模型就会随机挑一个。解决方式是明确区分“抓取”和“解析”的使用阶段。6.2 技能加载了但模型就是不按正文做这种情况通常不是提示词问题而是加载顺序或正文的结构问题。检查 SKILL.md 正文是否超过 800 字是否在开头就明确说“目标”是否把约束放在目标之前。模型在执行时如果先读到一大堆“不要”容易陷入保守模式连正常操作都不敢执行。把约束从正数第二段挪到正文最后一节往往效果会有明显改善。另一个实操技巧是在正文末尾加一个“完成标志”示例。比如“当输出包含‘来源:’字段时即视为任务完成”。这能给模型一个明确的终止信号减少它在任务边缘反复横跳。6.3 权限拦截太频繁导致模型“什么都干不了”权限边界如果配得过严框架会拦截大量本可安全完成的操作。典型表现是模型明明只是想读取某个文档却因为没有声明该文档目录的读取权限而被拒绝整个流程卡死。这种情况不是权限体系有问题而是技能拆分或权限声明不细致。解决思路是不要把权限声明到“技能”这一级粗粒度而是细化到“技能具体操作”的组合。比如“net-article-fetch”技能可以声明“只允许访问目标网站正文内容页面”而给它一个独立的、窄化的网络访问通道。不要让它拥有对整个公网的任意 URL 访问权。合适的边界是“卡住异常、放行正常”需要小步迭代才能找到平衡点。6.4 长会话中权限漂移的问题还有一个容易让人措手不及的问题在长会话中多个技能依次加载和卸载但框架如果忘记回收已卸载技能的权限就会出现“权限漂移”。某段时间内Agent 明明已经切换到低权限技能却仍持有之前高权限技能的授权存在越权风险。解决办法是在调度器里实现“权限快照”机制每次技能切换时对比新旧技能权限集合差量回收与授予。这相当于给 Agent 的权限做了版本管理。我在项目里用一个权限哈希表来记录当前会话的权限指纹任何一次技能变更都会触发快照比对一旦发现有不属于当前技能的额外权限条目就在日志里标红并自动回收。这个机制上线后权限相关的事故几乎降为零。7. 什么时候不要用这套设计讲了很多“为什么要用”最后补充一个重要观点这套设计不是银弹它适合的是“技能数量较多、能力边界复杂、需要安全隔离”的场景。如果你只是给一个临时 Demo 写两个简单技能全用上 SKILL.md、按需加载、权限边界反而会显得过度设计。那种情况下一段 200 字的提示词就够了。我的判断标准很简单技能数量超过 5 个或某个技能要触达外部资源文件目录、网络、数据库、第三方 API或技能需要被多个 Agent 复用——只要满足任意一条就值得切换到 SKILL.md 体系。规模越大收益越明显。规模较小的时候没有必要为了架构而架构。另一个值得留意的时间点是团队协作。如果多个开发者维护同一个 Agent 的技能库SKILL.md 的文件规范和权限声明比任何口头约定都更可靠因为它是代码化的、可 review、可回溯的。这种“代码化约束”在团队场景里的价值往往比单机个人项目里更大。最后分享一个经验我在开始搭建技能库时习惯先写三个“又宽又浅”的技能练手感知一下 SKILL.md 各字段在实际运行中的表现差异再逐步细化成五个“窄而深”的技能。别在项目第一天就把 20 个技能全部建好你会发现自己对技能边界的理解会在第一周剧烈变化。留出重构的耐心比一次设计完美重要得多。