上周我在调一个多步执行的工作流被一个问题卡了很久每次给Agent换一个新任务就得把一堆说明、参数格式、处理逻辑全部塞进系统提示里塞完发现指令之间互相打架输入稍微变一变输出就跑偏。后来我把这套东西完全拆掉换成基于“技能”的组织方式——也就是 agent-skills 的思路问题才算真正解决。这篇文章我会把技能的构成、描述方法、目录组织、运行时加载和避坑经验一次性说清楚。先明确一件事我这里说的 agent-skills不是某一家平台的专属功能而是一种通用的Agent能力组织范式。核心思想很简单——把Agent需要具备的每一种能力抓网页、提数据、写摘要、发消息封装成一个独立的“技能”每个技能自带说明书、示例代码和运行脚本Agent在对话中按需发现、加载和执行。你可以把它理解成给Agent装了一套随取随用的工具箱而不是把所有工具焊死在桌子上。这套思路适合谁如果你手头有一个基于大模型开发的Agent并且在为“指令越来越长、任务越来越杂、复用越来越难”头疼那这篇文章应该能给你一套可以立刻动手的方案。下面按真实落地顺序来拆解。1. 技能在Agent体系里的真实位置它不是插件也不是工具函数1.1 单一Prompt为什么走不通我把所有指令堆进系统提示的那段时间系统提示从几百字涨到几千字效果不升反降。原因并不神秘大模型处理长上下文时注意力会被稀释。你把“如何抓网页”“如何清洗数据”“如何按模板生成周报”这些规则全部铺在模型面前它在执行具体任务时反倒不知道该重点参考哪一段。更麻烦的是参数冲突。比如我在系统提示里规定“日期统一用YYYY-MM-DD格式”另一个模块的示例里又写了“2024年1月5日”模型遇到类似矛盾时会随机发挥你根本没法稳定复现同一个任务的输出。把指令抽离成独立技能后冲突的指令不再同时出现每次只把相关的那份说明注入上下文问题直接从根上消掉了。1.2 技能、工具函数、插件的边界划分很多朋友会问这不就是函数调用Function Calling吗早期我也这么以为但实际对比下来两者粒度完全不同。对比维度工具函数Function技能Skill插件Plugin载体单个函数 参数Json Schema目录 SKILL.md 脚本整套扩展包触发方式模型按函数名调用模型按技能描述匹配用户手动安装启用包含内容只能做一次原子操作包含说明、示例、模板、失败处理可能包含多个技能和运行时复用粒度细中粗维护成本低中高大致可以这样理解函数是“手脚”技能是“一套完整的动作”插件是“打包好的整套动作集”。技能在函数之上多了一层“说明书”在插件之下又比整包扩展轻盈得多。我要实现“抓取某网页并提取核心观点”函数只能保证“给一个URL返回HTML”而技能能保证“根据URL抓取、清洗正文、提炼观点、按格式输出”——它把模型需要知道的前置知识、处理逻辑、输出格式全部打包了。1.3 技能库带来的三个核心价值第一是上下文减负。Agent不需要在每次对话里携带全部指令只需要携带一份技能索引每个技能一句话描述用到哪个加载哪个。第二是能力资产化。一个技能调试好了换一个Agent、换一个项目还能继续用能力变成了可积累的文件资产。第三是多Agent共享。团队多个Agent共用一套技能库行为一致性会大幅提升不用每个Agent里复制粘贴同一套Prompt。这三个价值是我在实际切换后感受最明显的部分。整个系统的可维护性比“单一长Prompt 一堆散装函数”高出一个数量级。2. 技能描述SKILL.md才是成败关键怎么写才能被稳定触发技能能不能被正确调用七成功力在描述文件里。模型读技能不是像人一样扫一眼“哦这个大概是干嘛的”它是在意图匹配的边界上做决策。描述写得含糊模型就会在相似技能之间犹豫描述写得太长重要信息又被淹没。2.1 先写触达条件再写功能说明我见过大量技能描述是这么开头的本技能用于数据处理。这等于没写。模型看到一个网页抓取任务时无法判断“数据处理”这个词和当前请求是否匹配。我把写法改成下面这种当用户需要从一个或多个网页URL中提取正文内容时使用本技能。典型场景包括抓取新闻页面、提取产品描述、采集博客文章。如果用户需要的是结构化字段如价格、评论数请优先选用其他技能。注意这里的关键动作明确触发条件“当……时使用”给出一组典型场景帮助模型判断匹配度再给出排除条件“如果……请优先选用其他技能”。模型做意图路由时靠的就是这些可判断的信号词。2.2 输入输出约定要有格式原型描述文件里光说“输出提取结果”是不够的模型不知道提取结果长什么样。必须给一个具体的输出结构越具体越好。我自己常用的SKILL.md里输出约定长这样输出格式 { url: 原文URL, title: 页面标题, content: 清洗后的正文纯文本最长不超过5000字, word_count: 正文字数, extracted_at: ISO8601格式的当前时间 }同时还要规定异常情况下的输出异常处理 - 页面无法访问时在content字段返回空字符串并在error字段描述原因 - 页面没有正文内容时同样返回空content不要凭空编造内容这个细节我栽过跟头。有一次技能描述里只写了“提取正文”模型在页面内容为空时竟然开始编造“本页面暂无内容”的假正文后来加上明确的异常输出规定情况才好转。模型在决策时是需要边界感的你给它的边界越清晰它发挥越稳定。2.3 示例是给模型看的电梯测试好的SKILL.md里一定有一到两个输入输出对。模型在运行时会把当前请求和示例做隐式的相似度匹配示例的形态直接决定了模型对技能的“直觉”。下面是一个简短的示例写法示例 用户输入请帮我抓取 https://example.com/news/2024/01/agent-trends 这篇页面 技能输出{ url: https://example.com/news/2024/01/agent-trends, title: Agent Trends in 2024, content: ……正文纯文本……, word_count: 1203, extracted_at: 2025-01-14T10:32:00Z }示例不需要多一个示忙场景足以。关键是这个输入要尽量贴近真实使用不要用抽象的空壳数据否则模型学不到匹配信号。2.4 从一次误调用看描述精修的完整过程我在一个技能库里跑过这样的问题。技能A叫“提取正文”描述是“从网页中提取文章内容”技能B叫“抽取实体”描述是“从网页中抽取人名、机构名、时间”。有一次用户输入“帮我从这篇新闻里提炼出讲了什么”模型没有选择技能A反而调了技能B输出一堆实体列表。根因在于两条描述都用了“从网页中提取”的句式模型在语义空间里把两个技能的距离拉近了。修复方式是在技能A描述尾部加上反向触发词如果用户希望获得的是语义总结、观点提炼、事件梳理而不是简单抽取字段请勿使用本技能。同时给技能B也加了一句“仅当用户明确要求提取结构化实体时使用”。这种双向边界一划误调用率立刻下来。所以描述文件里加一个“When NOT to use”小节不是冗余是必要配置。3. 技能库的组织形式与运行时加载不是堆一堆目录那么简单3.1 技能目录与命名规范技能在文件系统里应该遵守一个规则一个技能一个目录目录内标准文件布局。我的项目里一般长这样skills/ ├── fetch_and_extract/ │ ├── SKILL.md │ ├── src/ │ │ ├── fetcher.py │ │ └── cleaner.py │ ├── requirements.txt │ └── tests/ │ └── test_fetcher.py ├── summarize/ │ ├── SKILL.md │ ├── src/ │ │ └── summarizer.py │ └── requirements.txt为什么这样设计因为SKILL.md承载“给模型看的说明书”src承载“给解释器执行的Python代码”requirements.txt承载“运行这个技能需要的外部依赖”tests承载“这个技能的回归验证”。这样拆分模型层、代码层、依赖层、验证层互不干扰。技能目录命名我坚持用小写字母加下划线避免不同操作系统之间的大小写敏感差异。3.2 技能元信息metadata是建立索引的基础除了SKILL.md我还会给每个技能写一个轻量的元信息文件用来支持加载器的快速索引。格式用YAML或JSON都可以关键在于字段设计。字段有经验讲究这字段是给加载器做能力索引用的不是给模型看的完整说明书。加载器启动时只需要扫元信息就能生成一份“技能地图”等模型选中某个技能后再读取完整的SKILL.md注入上下文。这种两级加载策略是控制上下文开销的关键手段。3.3 技能加载器的核心工作流程技能加载器实际上承担了四个环节的工作。第一步是扫描注册。启动时遍历技能根目录读取每个技能的元信息文件检查目录结构是否合法依赖文件是否存在。不合法或依赖缺失的技能不能直接丢弃而是标记为“不可用”并记录原因。第二步是构建索引。把技能名称、触发场景、能力类型汇总成简短文本。这里有个原则每个技能在索引里只保留不超过30个字的核心描述这样即使有20个技能索引总长度也能控制在几百字以内。第三步是按需注入。模型在对话中根据索引选择了某个技能后加载器把完整的SKILL.md读到上下文里。我的实现里用的是会话级缓存同一个会话内第二次使用同一个技能时不再重复读取直接复用。第四步是执行与回写。模型输出结构化调用指令后执行器启动独立的子进程或容器来运行技能代码结束后把stdout状态和执行结果返回给模型。这四步走完一次技能调用才算完整。很多自建技能的方案只做到了前两步后面执行和回写完全缺失导致技能只能“看”不能“用”。3.4 多Agent共享时的权限与资源隔离如果多个Agent共用同一个技能库还要考虑隔离问题。比如“发送邮件”这个技能不能允许所有Agent无限制调用再比如“读取本地文件”这个技能如果不加限制AgentA就能看到AgentB的工作目录。我的处理方式是在运行时加载器里引入作用域scope概念。每个Agent实例绑定一个允许访问的技能名单和资源白名单执行器在启动子进程时通过环境变量传入白名单技能代码内部只能访问白名单内的路径。同时给技能执行加超时时间我用的是30秒超时加5MB输出大小上限。一个Agent被恶意或误用代码拖住不影响其他Agent的正常运行。这套机制实现不算复杂但在多Agent场景里属于必需品。4. 从零跑通一个“信息收集内容产出”技能库完整实操4.1 一个具体场景的需求拆解为了把上面这些概念串起来我以一个真实小项目为例让Agent自动完成“浏览一批新闻页面→提取文章要点→生成一份简报”。这个流程可以拆成三个技能fetch_and_extract抓取并清洗网页正文summarize对正文做要点提炼report_builder把多条要点按模板拼接成简报每个技能独立可复用尤其是 fetch_and_extract 和 summarize以后在其他任务里还能单独拿出来用。4.2 搭建技能工程的过程先写 fetch_and_extract 的 SKILL.md描述部分用第二节讲的方法# fetch_and_extract ## 触发条件 当用户需要从一个或多个URL获取网页内容并提取正文时使用。 ## 输入参数 - url必填需要抓取的网页地址 - max_words可选正文截断长度默认5000 ## 输出格式 { url: ..., title: ..., content: ..., word_count: 123, error: } ## 示例 用户输入抓取 https://example.com/news/1 技能输出{url:https://example.com/news/1, title:Example News, content:..., word_count:800, error:} ## 异常处理 页面不可访问时content为空error字段描述原因。不得编造正文内容。然后在 src/fetcher.py 里写抓取和清洗逻辑。技术要点是使用 requests BeautifulSoup对抓到的HTML先做标题抽取再摘除script/style/nav等噪音标签最后提取正文段落。用 fake_useragent 避免部分简单反爬拦截加上超时和重试机制这些细节网上都能查到关键是记得把异常结构化返回给模型。summarize 技能的写法和它类似区别在输入是正文文本输出是分条要点列表。report_builder 技能则是读取多条摘要数据按既定模板生成Markdown格式的周报。4.3 在Agent对话里让模型自主选择技能技能跑通后需要在Agent主流程里把它们组织起来。我的实现里系统提示只保留一份简短索引可调用技能 - fetch_and_extract抓取网页正文 - summarize对正文生成要点摘要 - report_builder将多条摘要组装成简报模型判断当前任务需要哪个技能后输出一个结构化调用指令例如{skill: fetch_and_extract, parameters: {url: https://example.com/news/1}}加载器解析后执行代码把结果返回给模型。模型再据此决定是否调用下一个技能。整个过程里模型上下文只出现了当前相关技能说明而不是全部指令。我实际跑下来同样任务的行为稳定性比之前长Prompt方案好很多。4.4 技能执行失败时的降级回退设计任何技能都可能失败设计时必须预留降级逻辑。我在每个技能的执行结果里统一加入 exit_code 字段0表示成功非0表示失败。模型看到失败结果后可以决定是更换参数重试还是改用其他技能。比如 fetch_and_extract 返回“目标站点超时”模型可以选择稍后重试也可以直接读取用户提供的备用数据源。更复杂一点的降级是我在 summarize 技能失败时会触发 report_builder 直接使用原文第一段作为摘要占位。这看起来微不足道但在真实业务流程里一个不会因为小失败就中断整体流程的Agent才具备可用性。5. 真正跑起来才遇到的坑技能冲突、描述误触与上下文膨胀5.1 相似技能的“选择困难症”与解法第一节和第二节都提到了技能描述相似导致的误调用这里再展开一种更隐蔽的情况两个技能A和B功能确实有重叠且用户请求落在重叠区域。比如“抓取正文”和“抓取页面所有链接”两个技能遇到“帮我看看这个页面上有哪些内容”时模型可能随机选择。解法是人为制造差异化信号。我在技能A的触发条件开头直接写入“当用户提到提取正文、文章内容、阅读全文等词汇时”技能B则写“当用户提到链接、URL列表、外链等词汇时”。关键词信号比模糊的意图描述可靠得多。如果一个技能不能被两个以上关键词唯一触发说明技能边界划得有问题应当合并或拆分。5.2 技能之间的依赖冲突与环境隔离这是自建技能库时最容易被低估的问题。技能A用requests2.28技能B必须用requests2.31如果都跑在同一个Python环境里要么一起升级要么互相踩依赖。我在方案里让每个技能目录自带 requirements.txt并在执行阶段使用虚拟环境隔离。实现方式并不复杂执行器为每个技能创建 .venv-{skill_id} 的虚拟环境安装依赖后运行如果虚拟环境已存在直接复用。首次安装确实会慢几秒但换来的是技能之间的彻底隔离。对于依赖较重或多语言技能可以考虑直接切到容器执行——更重但更干净。5.3 SKILL.md过长引起的上下文膨胀技能说明不是越详细越好。我在一次调试中把SKILL.md写到了2000多字结果单个技能加载后上下文窗口被吃掉一大截对话历史反而被挤压。经验值是单个SKILL.md控制在800字以内。超出部分尽可能放到src目录下的参考文件里描述文件只保留触发条件、输入输出、异常处理、一条示例。实现上还可以给加载器加一个按需读取机制初始化时只读取描述文件技能代码源码不进入上下文只在执行时由解释器加载。5.4 技能版本管理改一行描述引发的连锁反应技能描述和代码一样会演化但它的影响会更隐蔽。我改动过一个技能的触发条件加了两个新关键词结果当天所有类似请求开始优先命中它另一个技能的调用量直线下降下游流程输出风格整个变了。所以现在我对技能目录做版本管理元信息文件里保留 version 字段遵循语义化版本号。描述改动属于行为变化至少升Minor版本只改示例或微调参数说明升Patch版本。改动后在测试集上跑一遍回归验证确认影响范围再同步给其他依赖该技能的Agent。技能不是写出来就完事的它需要持续打磨而这恰恰是它比普通函数调用更有价值的地方——每一次线上反馈都能沉淀回说明文档里让Agent一步一步变得更聪明。跑通这套体系之后我最大的感受是你不再是为Agent编写一次性指令而是在经营一套不断演进的能力资产。随着技能库逐渐变大新任务大概率能复用已有技能少数需要新技能的因为有了清晰的“说明书-代码-验证”范式开发一个也很快。如果你正被长Prompt和散装工具函数折磨不用一步到位先挑一个高频重复的任务改造成独立技能跑顺一个案例之后整个模式的价值你自然就能体会到了。
上周我在调一个多步执行的工作流被一个问题卡了很久每次给Agent换一个新任务就得把一堆说明、参数格式、处理逻辑全部塞进系统提示里塞完发现指令之间互相打架输入稍微变一变输出就跑偏。后来我把这套东西完全拆掉换成基于“技能”的组织方式——也就是 agent-skills 的思路问题才算真正解决。这篇文章我会把技能的构成、描述方法、目录组织、运行时加载和避坑经验一次性说清楚。先明确一件事我这里说的 agent-skills不是某一家平台的专属功能而是一种通用的Agent能力组织范式。核心思想很简单——把Agent需要具备的每一种能力抓网页、提数据、写摘要、发消息封装成一个独立的“技能”每个技能自带说明书、示例代码和运行脚本Agent在对话中按需发现、加载和执行。你可以把它理解成给Agent装了一套随取随用的工具箱而不是把所有工具焊死在桌子上。这套思路适合谁如果你手头有一个基于大模型开发的Agent并且在为“指令越来越长、任务越来越杂、复用越来越难”头疼那这篇文章应该能给你一套可以立刻动手的方案。下面按真实落地顺序来拆解。1. 技能在Agent体系里的真实位置它不是插件也不是工具函数1.1 单一Prompt为什么走不通我把所有指令堆进系统提示的那段时间系统提示从几百字涨到几千字效果不升反降。原因并不神秘大模型处理长上下文时注意力会被稀释。你把“如何抓网页”“如何清洗数据”“如何按模板生成周报”这些规则全部铺在模型面前它在执行具体任务时反倒不知道该重点参考哪一段。更麻烦的是参数冲突。比如我在系统提示里规定“日期统一用YYYY-MM-DD格式”另一个模块的示例里又写了“2024年1月5日”模型遇到类似矛盾时会随机发挥你根本没法稳定复现同一个任务的输出。把指令抽离成独立技能后冲突的指令不再同时出现每次只把相关的那份说明注入上下文问题直接从根上消掉了。1.2 技能、工具函数、插件的边界划分很多朋友会问这不就是函数调用Function Calling吗早期我也这么以为但实际对比下来两者粒度完全不同。对比维度工具函数Function技能Skill插件Plugin载体单个函数 参数Json Schema目录 SKILL.md 脚本整套扩展包触发方式模型按函数名调用模型按技能描述匹配用户手动安装启用包含内容只能做一次原子操作包含说明、示例、模板、失败处理可能包含多个技能和运行时复用粒度细中粗维护成本低中高大致可以这样理解函数是“手脚”技能是“一套完整的动作”插件是“打包好的整套动作集”。技能在函数之上多了一层“说明书”在插件之下又比整包扩展轻盈得多。我要实现“抓取某网页并提取核心观点”函数只能保证“给一个URL返回HTML”而技能能保证“根据URL抓取、清洗正文、提炼观点、按格式输出”——它把模型需要知道的前置知识、处理逻辑、输出格式全部打包了。1.3 技能库带来的三个核心价值第一是上下文减负。Agent不需要在每次对话里携带全部指令只需要携带一份技能索引每个技能一句话描述用到哪个加载哪个。第二是能力资产化。一个技能调试好了换一个Agent、换一个项目还能继续用能力变成了可积累的文件资产。第三是多Agent共享。团队多个Agent共用一套技能库行为一致性会大幅提升不用每个Agent里复制粘贴同一套Prompt。这三个价值是我在实际切换后感受最明显的部分。整个系统的可维护性比“单一长Prompt 一堆散装函数”高出一个数量级。2. 技能描述SKILL.md才是成败关键怎么写才能被稳定触发技能能不能被正确调用七成功力在描述文件里。模型读技能不是像人一样扫一眼“哦这个大概是干嘛的”它是在意图匹配的边界上做决策。描述写得含糊模型就会在相似技能之间犹豫描述写得太长重要信息又被淹没。2.1 先写触达条件再写功能说明我见过大量技能描述是这么开头的本技能用于数据处理。这等于没写。模型看到一个网页抓取任务时无法判断“数据处理”这个词和当前请求是否匹配。我把写法改成下面这种当用户需要从一个或多个网页URL中提取正文内容时使用本技能。典型场景包括抓取新闻页面、提取产品描述、采集博客文章。如果用户需要的是结构化字段如价格、评论数请优先选用其他技能。注意这里的关键动作明确触发条件“当……时使用”给出一组典型场景帮助模型判断匹配度再给出排除条件“如果……请优先选用其他技能”。模型做意图路由时靠的就是这些可判断的信号词。2.2 输入输出约定要有格式原型描述文件里光说“输出提取结果”是不够的模型不知道提取结果长什么样。必须给一个具体的输出结构越具体越好。我自己常用的SKILL.md里输出约定长这样输出格式 { url: 原文URL, title: 页面标题, content: 清洗后的正文纯文本最长不超过5000字, word_count: 正文字数, extracted_at: ISO8601格式的当前时间 }同时还要规定异常情况下的输出异常处理 - 页面无法访问时在content字段返回空字符串并在error字段描述原因 - 页面没有正文内容时同样返回空content不要凭空编造内容这个细节我栽过跟头。有一次技能描述里只写了“提取正文”模型在页面内容为空时竟然开始编造“本页面暂无内容”的假正文后来加上明确的异常输出规定情况才好转。模型在决策时是需要边界感的你给它的边界越清晰它发挥越稳定。2.3 示例是给模型看的电梯测试好的SKILL.md里一定有一到两个输入输出对。模型在运行时会把当前请求和示例做隐式的相似度匹配示例的形态直接决定了模型对技能的“直觉”。下面是一个简短的示例写法示例 用户输入请帮我抓取 https://example.com/news/2024/01/agent-trends 这篇页面 技能输出{ url: https://example.com/news/2024/01/agent-trends, title: Agent Trends in 2024, content: ……正文纯文本……, word_count: 1203, extracted_at: 2025-01-14T10:32:00Z }示例不需要多一个示忙场景足以。关键是这个输入要尽量贴近真实使用不要用抽象的空壳数据否则模型学不到匹配信号。2.4 从一次误调用看描述精修的完整过程我在一个技能库里跑过这样的问题。技能A叫“提取正文”描述是“从网页中提取文章内容”技能B叫“抽取实体”描述是“从网页中抽取人名、机构名、时间”。有一次用户输入“帮我从这篇新闻里提炼出讲了什么”模型没有选择技能A反而调了技能B输出一堆实体列表。根因在于两条描述都用了“从网页中提取”的句式模型在语义空间里把两个技能的距离拉近了。修复方式是在技能A描述尾部加上反向触发词如果用户希望获得的是语义总结、观点提炼、事件梳理而不是简单抽取字段请勿使用本技能。同时给技能B也加了一句“仅当用户明确要求提取结构化实体时使用”。这种双向边界一划误调用率立刻下来。所以描述文件里加一个“When NOT to use”小节不是冗余是必要配置。3. 技能库的组织形式与运行时加载不是堆一堆目录那么简单3.1 技能目录与命名规范技能在文件系统里应该遵守一个规则一个技能一个目录目录内标准文件布局。我的项目里一般长这样skills/ ├── fetch_and_extract/ │ ├── SKILL.md │ ├── src/ │ │ ├── fetcher.py │ │ └── cleaner.py │ ├── requirements.txt │ └── tests/ │ └── test_fetcher.py ├── summarize/ │ ├── SKILL.md │ ├── src/ │ │ └── summarizer.py │ └── requirements.txt为什么这样设计因为SKILL.md承载“给模型看的说明书”src承载“给解释器执行的Python代码”requirements.txt承载“运行这个技能需要的外部依赖”tests承载“这个技能的回归验证”。这样拆分模型层、代码层、依赖层、验证层互不干扰。技能目录命名我坚持用小写字母加下划线避免不同操作系统之间的大小写敏感差异。3.2 技能元信息metadata是建立索引的基础除了SKILL.md我还会给每个技能写一个轻量的元信息文件用来支持加载器的快速索引。格式用YAML或JSON都可以关键在于字段设计。字段有经验讲究这字段是给加载器做能力索引用的不是给模型看的完整说明书。加载器启动时只需要扫元信息就能生成一份“技能地图”等模型选中某个技能后再读取完整的SKILL.md注入上下文。这种两级加载策略是控制上下文开销的关键手段。3.3 技能加载器的核心工作流程技能加载器实际上承担了四个环节的工作。第一步是扫描注册。启动时遍历技能根目录读取每个技能的元信息文件检查目录结构是否合法依赖文件是否存在。不合法或依赖缺失的技能不能直接丢弃而是标记为“不可用”并记录原因。第二步是构建索引。把技能名称、触发场景、能力类型汇总成简短文本。这里有个原则每个技能在索引里只保留不超过30个字的核心描述这样即使有20个技能索引总长度也能控制在几百字以内。第三步是按需注入。模型在对话中根据索引选择了某个技能后加载器把完整的SKILL.md读到上下文里。我的实现里用的是会话级缓存同一个会话内第二次使用同一个技能时不再重复读取直接复用。第四步是执行与回写。模型输出结构化调用指令后执行器启动独立的子进程或容器来运行技能代码结束后把stdout状态和执行结果返回给模型。这四步走完一次技能调用才算完整。很多自建技能的方案只做到了前两步后面执行和回写完全缺失导致技能只能“看”不能“用”。3.4 多Agent共享时的权限与资源隔离如果多个Agent共用同一个技能库还要考虑隔离问题。比如“发送邮件”这个技能不能允许所有Agent无限制调用再比如“读取本地文件”这个技能如果不加限制AgentA就能看到AgentB的工作目录。我的处理方式是在运行时加载器里引入作用域scope概念。每个Agent实例绑定一个允许访问的技能名单和资源白名单执行器在启动子进程时通过环境变量传入白名单技能代码内部只能访问白名单内的路径。同时给技能执行加超时时间我用的是30秒超时加5MB输出大小上限。一个Agent被恶意或误用代码拖住不影响其他Agent的正常运行。这套机制实现不算复杂但在多Agent场景里属于必需品。4. 从零跑通一个“信息收集内容产出”技能库完整实操4.1 一个具体场景的需求拆解为了把上面这些概念串起来我以一个真实小项目为例让Agent自动完成“浏览一批新闻页面→提取文章要点→生成一份简报”。这个流程可以拆成三个技能fetch_and_extract抓取并清洗网页正文summarize对正文做要点提炼report_builder把多条要点按模板拼接成简报每个技能独立可复用尤其是 fetch_and_extract 和 summarize以后在其他任务里还能单独拿出来用。4.2 搭建技能工程的过程先写 fetch_and_extract 的 SKILL.md描述部分用第二节讲的方法# fetch_and_extract ## 触发条件 当用户需要从一个或多个URL获取网页内容并提取正文时使用。 ## 输入参数 - url必填需要抓取的网页地址 - max_words可选正文截断长度默认5000 ## 输出格式 { url: ..., title: ..., content: ..., word_count: 123, error: } ## 示例 用户输入抓取 https://example.com/news/1 技能输出{url:https://example.com/news/1, title:Example News, content:..., word_count:800, error:} ## 异常处理 页面不可访问时content为空error字段描述原因。不得编造正文内容。然后在 src/fetcher.py 里写抓取和清洗逻辑。技术要点是使用 requests BeautifulSoup对抓到的HTML先做标题抽取再摘除script/style/nav等噪音标签最后提取正文段落。用 fake_useragent 避免部分简单反爬拦截加上超时和重试机制这些细节网上都能查到关键是记得把异常结构化返回给模型。summarize 技能的写法和它类似区别在输入是正文文本输出是分条要点列表。report_builder 技能则是读取多条摘要数据按既定模板生成Markdown格式的周报。4.3 在Agent对话里让模型自主选择技能技能跑通后需要在Agent主流程里把它们组织起来。我的实现里系统提示只保留一份简短索引可调用技能 - fetch_and_extract抓取网页正文 - summarize对正文生成要点摘要 - report_builder将多条摘要组装成简报模型判断当前任务需要哪个技能后输出一个结构化调用指令例如{skill: fetch_and_extract, parameters: {url: https://example.com/news/1}}加载器解析后执行代码把结果返回给模型。模型再据此决定是否调用下一个技能。整个过程里模型上下文只出现了当前相关技能说明而不是全部指令。我实际跑下来同样任务的行为稳定性比之前长Prompt方案好很多。4.4 技能执行失败时的降级回退设计任何技能都可能失败设计时必须预留降级逻辑。我在每个技能的执行结果里统一加入 exit_code 字段0表示成功非0表示失败。模型看到失败结果后可以决定是更换参数重试还是改用其他技能。比如 fetch_and_extract 返回“目标站点超时”模型可以选择稍后重试也可以直接读取用户提供的备用数据源。更复杂一点的降级是我在 summarize 技能失败时会触发 report_builder 直接使用原文第一段作为摘要占位。这看起来微不足道但在真实业务流程里一个不会因为小失败就中断整体流程的Agent才具备可用性。5. 真正跑起来才遇到的坑技能冲突、描述误触与上下文膨胀5.1 相似技能的“选择困难症”与解法第一节和第二节都提到了技能描述相似导致的误调用这里再展开一种更隐蔽的情况两个技能A和B功能确实有重叠且用户请求落在重叠区域。比如“抓取正文”和“抓取页面所有链接”两个技能遇到“帮我看看这个页面上有哪些内容”时模型可能随机选择。解法是人为制造差异化信号。我在技能A的触发条件开头直接写入“当用户提到提取正文、文章内容、阅读全文等词汇时”技能B则写“当用户提到链接、URL列表、外链等词汇时”。关键词信号比模糊的意图描述可靠得多。如果一个技能不能被两个以上关键词唯一触发说明技能边界划得有问题应当合并或拆分。5.2 技能之间的依赖冲突与环境隔离这是自建技能库时最容易被低估的问题。技能A用requests2.28技能B必须用requests2.31如果都跑在同一个Python环境里要么一起升级要么互相踩依赖。我在方案里让每个技能目录自带 requirements.txt并在执行阶段使用虚拟环境隔离。实现方式并不复杂执行器为每个技能创建 .venv-{skill_id} 的虚拟环境安装依赖后运行如果虚拟环境已存在直接复用。首次安装确实会慢几秒但换来的是技能之间的彻底隔离。对于依赖较重或多语言技能可以考虑直接切到容器执行——更重但更干净。5.3 SKILL.md过长引起的上下文膨胀技能说明不是越详细越好。我在一次调试中把SKILL.md写到了2000多字结果单个技能加载后上下文窗口被吃掉一大截对话历史反而被挤压。经验值是单个SKILL.md控制在800字以内。超出部分尽可能放到src目录下的参考文件里描述文件只保留触发条件、输入输出、异常处理、一条示例。实现上还可以给加载器加一个按需读取机制初始化时只读取描述文件技能代码源码不进入上下文只在执行时由解释器加载。5.4 技能版本管理改一行描述引发的连锁反应技能描述和代码一样会演化但它的影响会更隐蔽。我改动过一个技能的触发条件加了两个新关键词结果当天所有类似请求开始优先命中它另一个技能的调用量直线下降下游流程输出风格整个变了。所以现在我对技能目录做版本管理元信息文件里保留 version 字段遵循语义化版本号。描述改动属于行为变化至少升Minor版本只改示例或微调参数说明升Patch版本。改动后在测试集上跑一遍回归验证确认影响范围再同步给其他依赖该技能的Agent。技能不是写出来就完事的它需要持续打磨而这恰恰是它比普通函数调用更有价值的地方——每一次线上反馈都能沉淀回说明文档里让Agent一步一步变得更聪明。跑通这套体系之后我最大的感受是你不再是为Agent编写一次性指令而是在经营一套不断演进的能力资产。随着技能库逐渐变大新任务大概率能复用已有技能少数需要新技能的因为有了清晰的“说明书-代码-验证”范式开发一个也很快。如果你正被长Prompt和散装工具函数折磨不用一步到位先挑一个高频重复的任务改造成独立技能跑顺一个案例之后整个模式的价值你自然就能体会到了。
 函数计算年龄与任意两个时间点之间的时间跨度)
