把“技能”做成一段塞进系统提示词里的长文本是这个领域里最常见的偷懒方案。表面上看模型确实“会了”这个技能但只要技能一多、逻辑一绕、权限一敏感这套思路的代价就会成倍放大。这篇文章要把 Agent Skills 这件事讲透为什么技能不能退化成“长提示词”SKILL.md 这种结构化文件到底解决了什么问题按需加载是怎么省上下文和省推理成本的权限边界又该划在哪一层。内容偏工程实践适合正在做 Agent 产品原型、想在现有提示词方案上往前迈一步的开发者。1. 为什么技能不能只是“长提示词”1.1 长提示词方案的三大结构性硬伤先说一个我在实际项目里反复遇到的场景。某次给内部的知识库助手做技能改造当时的做法特别朴素把每个技能的需求、步骤、注意事项全部以 Markdown 文本的形式堆在系统提示词里最后形成了将近两万字的“技能大全”。模型确实能引用其中的片段团队内部甚至一度觉得这方案挺省事——不用改代码想加技能就加一段文字改技能就改一段文字。但很快痛点就集中爆发了。第一个硬伤是上下文预算。系统提示词本身是有长度上限的塞两万字技能进去留给对话历史、工具返回结果、用户输入的余量就被压缩了。更麻烦的是几乎所有主流模型对“长距离指令”的遵循率都不是线性的指令越靠后、上下文越拥挤模型就越容易忽略关键约束。我在测试中发现当技能文本超过一定阈值之后模型开始自作主张地合并步骤、跳过校验环节甚至连最基本的“必须询问确认后才能执行”这种硬性要求都会丢。第二个硬伤是纯文本没有结构化信息。长提示词里的技能对模型来说是一段文字但对程序来说它不是一个“可寻址的单元”。没有名字、没有描述摘要、没有参数定义、没有依赖声明。你想在运行时判断“当前用户意图是否匹配某个技能”只能靠模型自己从一大段文字里“悟”完全无法用代码去精确路由。更别提做权限控制了——技能里哪些操作是危险的、哪些文件路径是可写的、哪些工具是允许调用的这些元信息在纯文本里基本无法表达。第三个硬伤是可维护性。二十个技能叠在一起彼此之间可能还存在隐性的依赖关系。你以为只是改一个技能的文字描述实际上可能影响其他技能的匹配结果。这种“改一处挂一片”的体验做过长提示词维护的人应该都有共鸣。1.2 技能的本质结构化资产而非文本片段那 Agent Skills 的正确打开方式是什么我的理解是技能的本质是一份可寻址、可声明、可校验的结构化资产。所谓可寻址是指技能有一个唯一标识程序能通过这个标识加载、覆盖、卸载它可声明是指技能开头就写明它的触发条件、参数契约、权限清单、依赖关系而不是用叙事性的文字去“暗示”可校验是指运行时能根据这些声明去做参数检查、权限拦截、输出校验。用一个生活化的类比长提示词技能就像在一张纸上手写了一本“菜谱合集”每次做饭都把整本纸递给厨师而结构化技能就像后厨里的一排食材柜每个柜子贴了标签——名字、适用菜系、需要什么食材、有没有过敏原、需要什么厨具。厨师接到点单先看标签决定要不要打开柜子打开之后按照柜子里的步骤操作操作之前还要检查该食材是否在这个菜单的许可范围内。一句话总结技能是给 Agent 和运行时共同消费的“半成品组件”不是写给模型看的“散文”。2. SKILL.md把技能变成机器可读的资产2.1 SKILL.md 的整体结构技能文件通常由两部分组成YAML frontmatter和Markdown 正文。frontmatter 是给程序读的正文是给模型读的。这种“双层结构”是设计上最值得学习的一点——它让同一个文件既能被路由器和权限系统解析又能被模型当作执行依据。frontmatter 里常见的关键字段包括name技能的唯一标识必须全局唯一建议用短横线连接的英文。description一段结构化的功能描述用于意图匹配。parameters技能的入参定义包含参数名、类型、必填性、默认值、描述。permissions技能运行所需的权限声明比如允许读取的路径、允许调用的工具、允许访问的网络域。version技能的版本号改了行为逻辑就应该递增。metadata作者、更新时间等方便团队协作追溯。正文部分则是实际的执行指令。要注意的是正文里尽量写“确定性流程”而不是“开放式建议”。比如“遇到 X 情况先执行 A再检查 B最终输出 C 格式”这种指令模型遵循起来的成功率明显高于“根据实际情况灵活处理”这类模糊表述。2.2 description 是技能路由的入口很多人写技能的时候把 90% 的精力花在正文上却对 description 一笔带过。这其实是舍本逐末。在一个按需加载的体系里description 是技能被“选中”的第一道漏斗。模型或路由器要从几十个技能的描述里判断当前用户的意图最匹配哪一个描述写得差技能写得再好也是“酒香巷子深”。关于 description 的写法我有几条经验描述要写“这个技能处理什么任务、在什么场景下被触发”而不是写“这个技能能做什么”。要包含典型的任务动词和对象名词比如“代码评审”“生成单元测试”“解析日志文件”这类明确的关键词。一个技能只承担一个职责描述里不要塞进多个不相关的场景否则路由会左右摇摆。如果某些触发条件带有排他性建议明确写清楚“不要将这个技能用于……”作为负面提示。比如同样是“文档处理”技能如果你只写“处理各种文档”那遇到一个“把 PDF 转成 Word”的需求路由器会犹豫不决。如果你写成“将 PDF 文档转换为可编辑的 Word 格式支持批量转换并保留原始布局”命中率就会高得多。2.3 parameters 定义与参数校验没有参数契约的技能本质上是“黑盒提示词”。模型在调用技能时如果不知道入参的格式和类型很容易生成长得奇怪的调用数据。建议的做法是在 frontmatter 里明确每一个参数的type、required、default和description。例如一个“查询订单状态”的技能参数应该定义成parameters: order_id: type: string required: true description: 订单号例如 ORD-2024-0001 with_detail: type: boolean required: false default: false description: 是否返回订单项级明细定好契约之后运行时可以在调用技能前做参数校验。这一步能拦截掉大量无意义的模型幻觉参数也能让技能更适配“函数调用”类型的 Agent 架构——毕竟很多 Agent 框架天生就是围绕参数化工具设计的。参数校验还有个额外的收益它对上下文注入是友好的。技能一旦参数化运行时就不需要把大段提示词直接塞给模型而是通过结构化的调用数据驱动执行。3. 按需加载精打细算的上下文预算3.1 全量注入为什么不可行继续用前面那个知识库助手的例子。如果把全部技能一次性注入系统提示词每次对话都要付出全量的“技能税”。假设二十个技能平均每个 600 token那就是一万二 token 的固定开销。哪怕用户只是问一句“今天天气怎么样”模型也要背着这一万二 token 的负担去理解指令既浪费成本又增加响应延迟。token 成本是可以算的如果你的 Agent 平均每天处理一万次请求全量注入和按需加载在技能文本上的 token 消耗差距可能就是上百万甚至上千万。你愿意为“省事”支付这笔账单吗如果愿意那长提示词方案确实可以继续用但一旦流量上来这笔账很快会倒逼你重构。3.2 两级索引机制按需加载的核心设计是“两级索引”。第一级技能注册表。只包含每个技能的name和description。这个注册表的体积很小几十个技能加起来也就几千 token可以常驻在系统提示词或工具列表里。第二级完整技能体。包含 SKILL.md 的全文。只有在“用户意图匹配到某个技能”时才将这个技能的完整内容注入到上下文中。工作流程大致是用户提出请求 → 模型/路由器基于第一级注册表判断“哪个技能可能能解决” → 按需加载完整的 SKILL.md 到上下文中 → 模型根据技能指令执行。这个方案的好处是显而易见的上下文里的技能内容只跟当前任务相关无关技能的 token 开销为零。更重要的是第一级注册表天然形成了一套“导航页”模型不需要在海量技能文本里自己翻找。3.3 加载策略的工程实现在实际代码里按需加载可以做成一个简单但可靠的服务。下面是我在某个项目里的简化示意用 Python 描述整个流程class SkillRegistry: def __init__(self, skills_dir): self.index [] self.contents {} for skill_path in skills_dir.glob(*/SKILL.md): meta parse_frontmatter(skill_path) self.index.append({name: meta[name], description: meta[description]}) self.contents[meta[name]] skill_path.read_text() def build_loading_table(self): # 将索引格式化成轻量的导航描述 return \n.join( f- {item[name]}: {item[description]} for item in self.index ) def load_skill(self, name): return self.contents.get(name, None)在对话开始时把build_loading_table()的输出作为系统提示词的一部分。当模型或调度逻辑判定需要某个技能时再从load_skill(name)中取出完整内容注入。这个架构落地起来不难但它把所有“技能清单”和“技能细节”的耦合彻底解开了。需要提醒的是如果你的 Agent 是基于 function calling 这类原生工具机制第一级注册表也可以表现为一组“工具定义”由模型直接选择。两者的核心逻辑是一样的先消费低成本的索引只在命中时才加载高成本的完整技能。4. 权限边界技能不是万能钥匙4.1 权限设计的四层模型技能系统里最容易出问题的不是加载逻辑而是权限边界。很多长提示词方案里权限完全依赖模型自觉——“注意你没有权限删除文件”这种文字在提示词里写了等于没写。模型生成的文本里夹带危险操作你能怎么办靠模型自律吗我在设计某内部工具的技能体系时把权限拆成了四层声明层技能在 SKILL.md 的 permissions 字段里声明自己需要什么权限。校验层运行时根据声明在调用技能前校验参数和操作合法性。执行层真正的文件操作、网络请求、命令执行都经过沙箱或受限执行环境。审计层所有技能的调用记录、参数上下文、执行结果都有日志。这四层里声明层和校验层是开发者最容易掌控的部分执行层需要依赖平台的隔离能力审计层则是判断题不是不好查的关键。4.2 最小权限原则怎么落地权限的黄金法则是默认拒绝按需放行。每个技能只声明它完成职责所需的最小权限集合。比如一个“读取日志”的技能它的权限声明应该是“允许读取 /var/logs/ 下的文件”而不是“允许读取任意路径”一个“发送通知”的技能权限声明应该是“允许访问通知服务 API”而不是“允许调用任何工具”。落地时我会把权限声明和参数校验放在一起做。技能的参数是 order_id权限却是“允许删除任意订单”这种不匹配就应该在校验层直接拦截。这里有一个比较实用的检查清单这个技能为什么要访问这个路径能不能只限定到目录这个技能的网络调用是只读还是写操作能不能限定域名这个技能会执行命令吗命令是白名单化的还是在 shell 里自由拼接技能执行过程中如果出现意外情况默认是中断还是继续4.3 危险操作的二次确认机制不是所有操作都必须自动执行。对于“删除文件”“批量改写数据”“发送外部请求”这类高风险操作我建议在设计上就把“需要用户确认”写进技能正文和运行时逻辑。技能的指令里要明确执行前先向用户复述将要执行的操作并请求确认运行时层面也可以为这类操作挂上确认钩子只有当用户明确批准后才放行。这个“双重确认”看起来啰嗦但它真的能从根上避免灾难性事故。我见过一个没有加确认机制的自动化脚本技能在一次批量处理中因为描述文件里的路径写错了一个层级直接把一批未归档的原始数据覆盖了。事后复盘如果技能里哪怕有一句“删除前提示用户输入‘确认删除’四个字”这个事故就不会发生。5. 实操从长提示词到技能化改造的完整步骤5.1 第一步从现有提示词里拆出“可复用单元”假设你手上有一段两千字的“代码评审助手”提示词里面混杂了代码规范检查、性能分析、安全漏洞审查、变更日志生成四个子任务。按技能化的思路这段提示词应该拆成四个技能code-style-review负责代码风格与规范检查。performance-analysis负责性能瓶颈分析。security-audit负责安全漏洞审查。changelog-generator负责根据变更内容生成变更日志。拆分的判断标准是如果一个子任务能被独立唤起、独立测试、独立授权就应该是一个独立技能。拆完之后原先的两千字提示词变成四个 SKILL.md每个平均五百字。虽然总 token 数没有减少甚至略增但这些技能不再同时压进上下文用户说“看看这段代码风格”的时候系统只加载 code-style-review 一个开销大幅下降。5.2 第二步写一份可以直接抄的 SKILL.md 模板这里给出一份我最近在某个跨平台项目里验证过的基础模板可以直接改着用--- name: performance-analysis description: 分析 Python 代码中的性能瓶颈。适用于 CPU 密集型函数、循环内 I/O、数据库查询高频调用等场景。不适用于前端渲染性能问题。 version: 1.0 parameters: code_snippet: type: string required: true description: 待分析的代码片段或文件内容 analysis_depth: type: string required: false enum: [quick, deep] default: quick description: quick 只做静态热点判断deep 执行复杂路径分析 permissions: read: - paths: [${code_dir}/src/**] network: - domains: [] execute: - allowed: [] --- 你是一名资深性能分析工程师。用户提供了代码片段你需要定位最可能的性能瓶颈并给出优化建议。 执行步骤 1. 通读代码识别循环、递归、文件 I/O、网络访问、数据库操作等潜在热点。 2. 如果 analysis_depth 为 quick输出 Top 3 瓶颈并给出优化建议。 3. 如果 analysis_depth 为 deep绘制函数调用路径评估时间复杂度并对比两种可选优化方案。 4. 输出格式要求按“问题位置 - 原因分析 - 优化建议 - 预期收益”四段式组织。 注意 - 不要修改用户代码只输出分析结论。 - 如果代码片段中不存在明显瓶颈明确说明“当前未见显著性能问题”。注意这段 SKILL.md 里分析步骤和输出格式是有“确定性”的模型不会自由发挥太多。这也验证了前面说的技能正文的本质是“约束下的执行框架”不是自然语言聊天。5.3 第三步注册、测试与逐步替换技能写完后放到指定目录skills/performance-analysis/SKILL.md然后在注册表里确认它能被索引到。接下来做一轮专门的测试直接调用测试给模型一段有明显循环瓶颈的代码看它是否命中。路由命中测试给一个无关请求看它是否错误加载了这个技能。权限拦截测试试着让这个技能读取 src 目录以外的路径看校验层是否拦截。全部通过之后再把原来那两万字的长提示词里对应段落移除。不要一次性替换所有技能先替换两三个观察几天的日志确认没有回退regression再继续。这个渐进替换的思路本质上是在切一条大动脉的时候给自己留了足够的止血时间。6. 常见问题与排查技巧实录6.1 技能命中率低总是不被触发问题通常出在 description。如果路由器是基于模型打分选技能描述里的歧义词会让模型“猜不准”。排查方法把用户实际输入与技能描述一起打印出来看模型是否把输入匹配给了其他技能。一个常见的修复是给 description 增加“not for”负面清单比如“不适用于数据库表结构设计咨询”能在很大程度上减少误命中。6.2 技能加载了但模型不按 SKILL.md 里的指令执行这种问题十有八九是技能正文的组织方式出了偏差。如果正文里用大段散文描述流程模型的执行稳定性就差。我一般会把正文强制改成分步执行的编号列表并且在关键节点写明输出格式。还有一招很管用在正文末尾加一行“你最终输出的内容必须严格遵循上述格式”这种“收口式”约束对模型有实际效果。6.3 权限配置太严导致技能功能“残废”权限边界划得过死会把合法操作也拦掉。我在某次改造中给一个“数据导出”技能只开放了读取数据库权限结果技能在执行时连写入导出文件的目标路径都进不去。排查后发现写导出文件其实也是这个技能职责的一部分应该一并声明。修改完权限声明后功能恢复正常。对于这种问题我的建议是先按最严配置上线再根据审计日志逐步放开。日志里经常出现“权限拒绝”记录的技能看它是否在合理场景下触发了拒绝如果是就谨慎放权。谨慎放权比一开始就大开权限要安全得多。6.4 技能版本升级后行为不一致很多团队改了 SKILL.md 却忘了更新 version 字段导致调试时新旧行为混杂难查。排查思路检查注册表缓存是否过期。按需加载体系里注册表索引有可能驻留在内存如果你更新了 SKILL.md 但没重启或触发重新索引模型加载到的还是旧版本。规范的流程是改文件 - 升 version - 重新构建索引 - 跑一遍技能自测用例。7. 一些实践体会和扩展想法我自己在技能化改造踩过的最大的坑就是低估了“权限边界”和“评审机制”的复杂度。技能化看起来是一个纯工程层面的改进但它本质上是给智能体做架构设计——一个没有边界概念的智能体能力再强也是不可控的。个人建议从一个小而关键的技能做起用真实流量跑两周把路由命中率、加载 token 数和权限拦截率这三个指标记录下来有了数据之后你再决定要不要全量推广。另外技能体系后续还可以在一个方向延伸技能之间的依赖编排。目前我们做的还是“一个技能处理一个任务”但真实场景里经常是“查订单 - 分析异常 - 生成报告”三个技能串起来。如果能在 SKILL.md 里声明依赖关系和衔接条件Agent 就能在运行时动态串联多个技能这才是技能化改造的下一个价值高地。