被问得最多的问题之一，就是“能不能把 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-review |
| description | 用一两句话概括适用场景、输入输出 | 用于模型判断是否调用，宜具体不宜空泛 |
| version | 技能版本号，支持灰度更新 | 1.3.1 |
| permissions | 声明所需资源权限 | read:/docs，api:metrics:r |
| dependencies | 依赖的其它技能或工具 | 避免技能加载后缺东少西 |
| 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 个技能全部建好，你会发现自己对技能边界的理解会在第一周剧烈变化。留出重构的耐心，比一次设计完美重要得多。
