1. 项目概述与核心思路这两年做 AI 应用大家的关注点慢慢从“模型能不能答对”转移到了“模型能不能干活”。“agent-skills”这个项目本质上就是一套给智能体Agent用的技能库——把高频、可复用的能力封装成一个个独立工具让大模型在任务执行过程中按需调用。你可以把它理解成给模型装了一个工具箱模型不需要知道每个工具的内部实现只需要知道“什么场景该用哪个工具、传什么参数进去、能拿回什么结果”就行。我最早做这个项目是因为一个很实际的痛点我自己写过一个聊天机器人单纯靠提示词让模型扮演“助手”但一旦涉及查询实时天气、操作本地文件、跑一小段代码模型就完全没法落地。后来我调研了业界的思路开始尝试把“技能”做成独立的模块而不是写死在系统提示里。事实证明这个方向是对的技能和服务端、模型解耦之后新增能力只需要加一个新技能文件模型侧的 prompt 基本不用动。这个项目适合谁参考如果你正在做智能客服、个人助理、自动化工作流或者你想让模型能在自己的服务器上执行一些受限操作那这套技能库的设计思路和代码骨架可以直接拿来用。即使你没有完整的大模型推理服务只想先看看“工具调用”到底怎么组织、怎么调试这篇文章也可以帮你建立起一套清晰的心智模型。先说结论agent-skills 的设计价值不在于某个技能写得有多复杂而在于它定义了一套让“模型、技能、运行时”三者稳定协作的协议。后面我会按架构设计、核心实现、实操过程、问题排查的顺序把完整的方法论拆开来讲。2. 整体架构设计与技能协议2.1 为什么不能把所有逻辑写进 system prompt早期做 Agent 的人最容易犯的错就是把所有工具说明都塞进系统提示词。模型知道“有个工具能查天气”但它不知道这个工具的参数结构也不清楚调用失败后该怎么重试更麻烦的是每次新增工具都要改动提示词模型输入 token 越来越多响应速度越来越慢行为还容易漂移——今天能调通明天换个模型版本就乱了。agent-skills 采用的方式是“技能注册 元数据驱动”。每个技能是一个独立文件通过统一的描述字段暴露名称、说明、参数 JSON Schema、返回格式。系统启动时读取全部技能生成一份索引模型在对话中看到这份索引就能自主决定是否调用某个技能、传什么参数。这和“把所有说明写进提示词”的本质区别在于技能信息是结构化数据不是自然语言文本模型解析起来更稳定调用的成功率也更高。另外从工程维护角度看独立技能文件意味着可以多人并行开发。某个技能出问题不会影响其他模块甚至可以做成动态加载不用重启服务。这个设计对团队协作和持续迭代都友好得多。提示技能索引不要一股脑全部发给模型。最好按任务粒度做一次粗筛选或者让模型用“检索”技能去查可用技能否则技能数量超过 20 个以后模型的选择准确性会明显下降。2.2 技能包的三层结构我把一个完整的技能包拆成三层声明层、执行层、校验层。声明层管“模型怎么看这个技能”。这里会写清楚技能名必须短、唯一、语义明确、描述说明什么场景用、不用会造成什么后果、参数定义用 JSON Schema 描述每个字段的类型、是否必填、取值范围。执行层是真正的业务逻辑可以是一段脚本、一个外部 API 调用或者一个系统命令。校验层负责在调用前验证参数合法性、在返回后验证结果格式防止脏数据污染 Agent 的状态。这个分层有一个明显的好处模型侧的感知和执行侧的实现被隔离。你想换掉底层实现比如从本地文件系统换到对象存储只要保持技能名和参数不变模型完全无感。我实测下来这种隔离对长期维护意义特别大尤其是在底层依赖频繁升级的业务场景里。2.3 命名与参数设计的约定技能命名我有一条硬性原则动词开头目标词结尾。比如get_weather、execute_python、create_calendar_event。动词开头是为了让模型一眼识别动作类型目标词提示操作对象。命名里禁止使用 acronym缩写比如不要用cc表示创建日历事件因为模型很可能猜不出含义宁可让名字长一点也要保证语义完整。参数设计要遵循“能少则少”的原则。每个技能的参数尽量控制在 3~5 个以内超过 5 个模型出错的概率会显著上升。参数名也要和领域直觉一致比如查天气用city而不是geographic_location_identifier。另外所有参数必须提供默认值除非业务上确实禁止缺省。这里我补一个常见的坑JSON Schema 的required字段别写太多。前期我习惯把能校验的字段全部标成必填结果是模型经常因为漏传某个次要参数而导致技能直接报错实际体验非常差。正确的做法是只把真正影响执行完整性的字段设为必填其余字段全部可选执行层内部用默认值兜底。3. 核心技能模块与关键实现解析3.1 代码执行技能安全是第一约束execute_python是技能库里使用率最高的一个。它的实现逻辑不复杂接收模型传来的代码片段在沙箱环境里执行然后把 stdout 和 stderr 返回给模型。但这个技能涉及的安全问题非常敏感不能随便传一个 Python 解释器就完事否则一个不小心的系统调用就可能带来风险。我实际的方案是使用 Docker 容器作为执行运行时。每次调用创建新容器执行完立即销毁。镜像内预先安装常用依赖但网络策略默认禁止出站只有显式配置的白名单域名才允许访问。镜像内运行的用户是非 root 用户工作目录限制在/workspace配合seccomp配置禁用部分危险系统调用。import docker import uuid client docker.from_env() def execute_python(code: str, timeout: int 15): container_id str(uuid.uuid4()) container client.containers.run( imageskill-python-runner:latest, command[python, -c, code], network_disabledTrue, usersandbox, working_dir/workspace, mem_limit256m, cpu_quota50000, detachTrue, namefexec-{container_id} ) try: result container.wait(timeouttimeout) logs container.logs().decode(utf-8) return { exit_code: result[StatusCode], stdout: logs } finally: container.remove(forceTrue)代码里几个参数值得说明一下network_disabledTrue彻底禁用网络从根源上防止数据外传mem_limit限制内存防止模型生成的代码无限申请资源cpu_quota50000把 CPU 限制在单核的 50% 左右避免影响宿主机其他服务。注意如果技能执行过程中允许读联网一定要加白名单机制并且确保环境变量里没有敏感密钥。我见过不少团队因为图省事直接把宿主机环境变量透传给容器结果模型把密钥当作普通参数传出去几乎酿成事故。每次执行创建一个容器的做法冷启动确实有开销大概多出 1~3 秒但换来的是安全隔离这个代价完全值得。实测下来在需要连续执行多段代码的调试场景里这种隔离方式并没有对用户体验造成明显瓶颈。3.2 浏览器操作技能从“截图”到“可交互”browser_act是一个稍微复杂的技能它让 Agent 能操作真实的浏览器页面。这里涉及两个子能力一是页面感知二是动作执行。页面感知通常靠截图或 DOM 转文本实现动作执行则靠浏览器自动化框架比如 CDP 协议。我采用的是 Playwright 的 CDP 连接方式先启动一个持久化浏览器进程暴露调试端口然后让技能模块通过 WebSocket 发送指令。每次调用browser_act时传入action参数click、fill、scroll、goto等以及选择器或坐标信息。这个技能的参数设计我调了很久最终简化成三种动作类型读取类获取标题、URL、可见文本、操作类点击、输入、导航类打开链接、刷新。模型不需要关心底层的 CSS 选择器细节只需要提供元素在页面中的人类可读描述比如“页面顶部的搜索框”执行层内部用视觉定位或文本匹配来实现。浏览器技能的一个核心难点是“等待策略”。直接固定等 2 秒再操作大概率会失败最好实现一个轮询机制操作后持续检测页面状态比如 DOM 变化、网络请求完成标志直到稳定或超时。我会统一封装一个wait_for_stable()方法默认轮询 5 次间隔 500 毫秒。async def wait_for_stable(page, timeout5000, interval500): elapsed 0 last_state await page.content() while elapsed timeout: await page.wait_for_timeout(interval) elapsed interval current_state await page.content() if current_state last_state: return True last_state current_state return False提示实际场景里页面内容一直在变比如有轮播图wait_for_stable很容易超时。更稳妥的策略是只关注目标元素的稳定而不是整页稳定。比如先定位到目标元素再判断它的innerText是否连续两次一致。3.3 文件操作技能工具越简单越可靠文件操作技能的设计目标是让模型能在授权目录内读写文件。表面上很简单但实际实现里需要思考路径穿越、二进制安全、编码一致性等问题。我封装的read_file和write_file必须做一件事把参数里的路径解析后确认它在允许的根目录之下否则直接拒绝。路径解析要用os.path.realpath而不是os.path.abspath因为 abspath 不解析符号链接攻击者可以用软链接绕过限制。同时要注意 Windows 和 Linux 路径分隔符的差异在服务器上统一用 POSIX 风格处理。文件技能还有一个隐藏需求给模型返回的内容大小必须适度。一次返回整个 100MB 的文件内容会直接把上下文撑爆。我的策略是默认只返回文件的前 N 行默认 200 行如果模型还需要更多再通过参数offset和limit分页获取。这种“增量读取”思路对长文件特别管用。3.4 系统监控技能主动发现问题除了处理“模型主动请求”的技能我还会设计一类“系统主动提供”的技能。这里最典型的例子就是check_system_status——查看 CPU、内存、磁盘占用率。这类技能通常不会由模型在对话中直接触发而是由定时任务或事件钩子主动调用把状态摘要注入模型上下文。这个设计想实现的效果是让 Agent 具备“感知环境状态”的能力而不只是被动响应。比如磁盘占用率超过 90% 时系统会主动提醒 Agent 运行清理逻辑或者生成一份警告摘要。这种机制对长期运行的自动化任务非常关键能避免很多“用到的时候才发现环境早就出问题”的尴尬场景。4. 从零搭建技能运行时实操全流程4.1 目录结构与加载器先说总体的运行时骨架。我倾向于用一个轻量级 Python 包来组织技能库目录结构大概是agent-skills/ skills/ __init__.py execute_python.py browser_act.py read_file.py write_file.py get_weather.py loader.py schema_validator.py runtime.py config.yamlloader.py负责扫描skills目录导入每个技能模块提取声明层信息构建技能索引。这里我会用一个统一基类或者装饰器来约定接口方便同时兼容纯函数技能和类级技能。装饰器方式写起来更顺手# skills/execute_python.py from skill_base import skill skill( nameexecute_python, description在沙箱容器中执行Python代码并返回输出结果。适用于计算、数据处理、脚本测试等场景。, parameters{ type: object, properties: { code: {type: string, description: 要执行的Python代码}, timeout: {type: integer, description: 超时时间单位秒, default: 15} }, required: [code] } ) def execute_python(code: str, timeout: int 15): # 核心实现 return resultloader.py在启动时遍历模块收集所有被skill装饰的函数构建一个字典{skill_name: {description: ..., parameters: ..., function: ...}}。模型侧的技能索引就是这个字典的轻量化视图。4.2 参数校验与错误标准化模型生成参数的过程本质是概率采样所以某些字段类型可能不符合 JSON Schema 定义——比如定义integer传了字符串15。我在调用技能函数之前会先做一次宽松的类型校准这是在“严格校验”和“容忍容错”之间取的平衡点。def normalize_parameter(value, expected_type): if expected_type integer: try: return int(value) except (ValueError, TypeError): return None if expected_type number: try: return float(value) except (ValueError, TypeError): return None if expected_type boolean: if isinstance(value, bool): return value if value in (true, True, 1): return True if value in (false, False, 0): return False return value所有技能返回值的格式我会统一成{status, result, error_message}三元结构。这样模型容易解析调试也方便。比如execute_python返回{status: success, result: 42}文件读取异常时返回{status: error, error_message: File not found: xxx}。模型通过 status 判断结果然后根据 error_message 决定如何调整参数重试这种标准化的错误反馈是模型自我纠错的前提。4.3 运行时调度与并发控制技能运行时最容易被忽略的一点是并发控制。如果多个对话会话同时触发execute_python而 Docker 容器数量没有限制服务器可能被瞬时打爆。我在 runtime 层加了简单的信号量控制每个技能可以配置最大并发数。超出的请求进入队列等待而不是直接报错这样可以避免模型感知到“服务忙”。from asyncio import Semaphore, wait_for _concurrency_limits { execute_python: Semaphore(8), browser_act: Semaphore(3), read_file: Semaphore(20) } async def dispatch_skill(skill_name: str, params: dict): semaphore _concurrency_limits.get(skill_name, Semaphore(5)) async with semaphore: return await wait_for( call_skill_function(skill_name, params), timeoutSKILL_TIMEOUT.get(skill_name, 30) )这里我把技能调度做成异步接口支持并发调用不同的技能。实际效果是比如一个 Agent 同时执行文件读取和代码运行两个任务可以并行整体延迟明显降低。4.4 一次完整的链路演示我自己在内部接了一个演示场景“帮我算出日期。从今天起 45 个工作日后是哪一天然后写进备忘录文件里。”这个请求会触发两个技能calculate_date和write_file。模型先调用calculate_date传入days45、skip_weekendstrue技能返回一个日期字符串模型再调用write_file把结果写进备忘文件。调试这个链路时我发现模型经常把一个参数用错它会给skip_weekends传字符串true而不是布尔值True。这就是前面说到的类型校准发挥作用的地方——我在执行层做了布尔值的宽松解析所以即使模型传了字符串函数仍然能正常工作。否则一次合理的任务请求就会白白失败。告警不要相信模型生成的任何数字参数。如果业务对精度敏感在执行层再做一次校验必要时让技能内部调用额外校验函数不要怕麻烦。5. 常见问题与排查技巧实录5.1 模型不调用技能直接给伪造结果这是最常见的问题模型没走工具调用在返回文本里直接写了“已执行成功”实际上什么都没发生。原因多半是技能描述不够清晰或者系统提示里没有明确要求“必须调用工具才能获取实时信息”。排查思路先检查技能描述里有没有明确边界条件比如“这个技能是获取实时天气的唯一方式不要自行推测天气信息”。同时检查模型侧的工具调用配置确认 return 格式和触发关键词设置。还有一个隐藏因素当技能描述太长、包含大量无关修饰词时模型可能从中提取不到调用意图。我的写法是描述控制在三句话以内第一句说什么功能第二句说什么时候必须用第三句说不用会有什么后果。5.2 技能参数频繁解析失败这种情况多发生在参数数量超过 5 个时。模型生成的 JSON 要么多了一个多余的逗号要么把布尔值写成了字符串。我的处理方案不是依赖大模型 API 自身的严格 JSON 修复而是在执行层做“二次解析”先用json.loads尝试失败后用基础正则提取键值对再交给类型校准函数。这套容错逻辑能挽回约 20% 的调用失败。如果你用的是标准的 JSON Schema 校验库建议把coerce_types打开同时自定义一个 pre-validation 函数。这个函数只做“类型清洗”不做“值范围校验”避免把模型生成的合理枚举值误杀。5.3 技能执行时间过长导致模型超时很多模型推理平台对工具调用的响应时间有限制。如果某个技能执行超过 30 秒比如浏览器加载慢模型侧会先抛超时错误。我的解法是“异步技能 进度回调”真正耗时的技能立刻返回一个{status: processing, task_id: xxx}让模型知道任务在跑执行完成后由后端通过消息通道主动通知模型或者提供一个check_task_status技能供模型主动查询。这个设计代价是要额外管理任务状态但收益很明显所有技能都能以统一的方式支持长时间任务而不是在模型侧频繁撞超时。实际测试下来一部 3 分钟长的视频处理任务也能平滑串联进 Agent 流程。5.4 技能返回内容过长撑爆上下文这个问题在browser_act返回整页 DOM 时最容易出现。模型上下文是奢侈品不能拿大段无意义文本填满它。我的做法是返回内容只保留结构化摘要。浏览器技能只返回页面的标题、主要可见文本、输入框数量、可点击元素位置而不返回完整 DOM。文件读取同理只返回分片片段。页面摘要 - 标题某某网站首页 - 可见文本欢迎来到...共120字符 - 可交互元素3个输入框2个按钮5个链接 - 当前URLhttps://example.com这种摘要的格式模型读起来非常高效决策也更快。你要在技能内部做一层“内容压缩”而不是让模型自己承担信息筛选的任务。5.5 技能权限管理失控技能一旦多了权限管理很容易出问题。比如write_file和execute_python如果被同时授权给一个模型理论上模型可以自写代码、自执行形成一个完整的“越狱链”。我的规避办法是给技能分等级执行敏感技能前需要额外的确认令牌或者在运行时检测到连续调用敏感技能组合时强制中断并触发人工审核。在设计技能库的早期就要想清楚“技能之间的组合关系”。单独看每个技能可能是安全的但组合起来可能有风险。我会维护一张边缘矩阵记录哪些技能组合需要二次授权。后续新增技能时自动检查是否存在新的危险组合。6. 技能迭代与扩展的个人经验6.1 技能描述需要定期 A/B 调整技能代码本身好测但模型对技能描述的理解是概率性的很难一次写对。我养成了一个习惯每两周复盘一次模型调用日志专门看“模型尝试调用 A 技能但失败”的记录然后分析失败原因——是参数名有歧义还是描述里缺少边界条件还是技能本身设计不合理。经验是很多失败不是因为模型笨而是技能的“用户界面”设计得不好。技能描述里如果出现“通常”“一般”“可能”这类模糊词模型的调用准确率会明显下降。把所有描述改成明确句式准确率能提升不少。6.2 不要追求大而全的技能库技能库不是越大越好。每增加一个技能模型选择时的信息噪声就多一分。我在内部只保留真正有用的 15~20 个核心技能。很多临时需求可以通过组合已有技能实现而不是新增技能。比如“发送日报邮件”这个技能我可以用read_file读报表、execute_python生成 HTML、send_email发送邮件三步组合完成没有必要单独封装一个send_daily_report_email。当你发现很多技能内部逻辑高度相似只是一个参数不同说明抽象层次出了问题。这时候应该考虑把技能“下调”成参数配置而不是继续堆积技能文件。6.3 给模型“错误学习”的机会技能执行出错不要只返回错误文本最好在错误信息里附上“可能的原因”和“建议调整方向”。比如文件读取失败返回的错误信息里可以写“请检查文件是否存在或者尝试用 list_files 查看当前目录下的可用文件”。这相当于在推理时给了模型一个即时提示让它能自主完成下一次尝试。实测下来这个细节能让任务完成率提升约 15%。这个机制的本质是把调试经验沉淀进错误信息里而不是藏在开发者文档里。模型和人类一样需要有效的反馈来修正自己的下一步行为。7. 后续可扩展的方向我目前在探索的方向是把技能库从“内置函数”扩展到“外部插件市场”。不同团队的 Agent 需要不同的技能组合与其一个人堆技能不如定义一套开放协议让其他人共享自己的技能实现。技能包的协议稳定之后插件的安装会像装手机 App 一样简单——把文件夹放到指定目录声明注册信息重启后立即可用。另一个方向是“技能自进化”让 Agent 根据任务日志自动调整技能描述中的措辞。比如模型连续多次在某个参数上传错值系统可以自动修改参数的 description将更明确的示例值加进去。这个思路本质上是在做“面向模型的 UI 优化”我认为这是后续 Agent 工程的核心竞争力之一。最后再分享一个我自己的体会做 agent-skills 这类项目最忌讳的是沉迷于技术细节而不去关注“模型到底能不能顺利用好这些工具”。代码写得再漂亮模型调用不顺畅一切都是白搭。把更多精力投入到技能描述、参数简化、错误反馈这几个“软环节”投入产出比远高于追新框架。这套方法论希望你也能在实际项目里试出好效果。