让 Agent 真正“会干活”光有模型不够还得有一套能管好技能、能调度技能、能避开坑的基础设施。这篇就是我从项目里沉淀下来的 agent-skills 实践经验从技能设计到注册调度再到排查实录一次性讲透。在 Agent 项目里泡久了你会慢慢意识到一个事实模型决定 Agent 的“智商”技能体系决定 Agent 的“手脚”。把模型比作一个刚毕业的高材生脑子再好没有趁手的工具、不知道工具有什么用、不知道怎么按流程干活一样做不了实事。做完 agent-skills 这套技能编排与调度方案后我对这一点体会特别深。项目本身解决的核心问题就是让 Agent 能够按需发现技能、准确调用技能、稳定执行技能并且在技能数量膨胀之后还能保持可控、可观测、可排查。这套思路适合正在做 Agent 应用、搞 AI 工作流编排、或者即将面对技能管理难题的开发者参考。今天就把整个拆解思路、落地实现和踩坑记录整理出来希望能帮到正在这条路上摸索的人。1. 整体设计与思路拆解1.1 为什么单独搞一套技能体系而不是直接写一堆函数先从一个最原始的场景说起。早期我写 Agent 的时候处理任务的方式非常简单粗暴把几个工具函数全部塞进系统提示词里让模型自己读、自己选、自己调用。当时只有三五个函数效果还不错模型基本不会选错。但随着业务场景扩展技能数量从五个涨到五十个问题就来了上下文窗口撑不住工具描述互相干扰模型开始频繁选错工具甚至出现幻觉式的工具调用——它调了一个根本不存在的函数。这个阶段给我的教训是让模型直接面对零散工具本质上是把“工具管理”的复杂度全部甩给了模型。模型既要理解每个工具的语义又要做路由决策还要处理工具之间的依赖关系这对当前的大模型来说负担还是太重了。于是我开始思考能不能在模型和工具之间加一层“技能管理层”把工具变成有名字、有描述、有入参规范、有返回值约定、有版本记录的技能再让 Agent 通过一套机制去发现和调用它们。agent-skills 的雏形就这样出来了。这套方案的核心价值可以归纳成三点一是降低模型的决策负担模型不需要理解所有技能的细节只需要通过技能描述和指标找到合适的技能二是让技能可以统一治理比如版本更新、权限控制、运行隔离、调用审计都能在技能管理层统一做掉三是提升整个系统的可解释性和可排查性每个技能调用都有规范化的记录出了问题能快速定位是选型错了、参数错了、还是技能本身执行失败了。1.2 方案选型背后的取舍声明式优于命令式在设计技能体系时我碰到一个关键选择技能定义应该用声明式描述技能是什么、输入输出是什么、约束是什么还是命令式直接写调用逻辑两条路我都试过最终选了声明式优先。命令式的实现很快写一个函数注册一下就行但问题在于函数签名本身承载的信息太少。比如一个函数叫search_products(keyword, page, page_size)模型看到这个名字和参数名其实很难准确理解这个技能到底适合什么场景、返回什么结构、有没有副作用。它需要从函数名和参数名去“猜”猜错的概率在技能多了以后会急剧上升。声明式则要求每条技能都附带一份结构化的描述信息包括技能名称、适用场景、依赖条件、入参说明、返回结构、错误码、权限要求、超时控制。模型拿到的是经过整理后的技能画像而不是光秃秃的函数签名。从实测效果看把工具描述从原来的“一句话函数名参数列表”换成“场景化、结构化、带示例”的技能描述后模型选错工具的比例明显下降。另一个重要取舍是技能注册表要不要完全自研。我也认真考虑过要不要直接上 MCPModel Context Protocol这类现成协议。MCP 的好处是有标准、有生态、很多工具已经支持但问题在于现成协议偏“连接层”只解决了工具暴露和传输格式的问题对技能的编排、依赖、路由、权限处理、以及和 Agent 内部状态交互这部分留白还是太多。所以我的做法是底层借鉴 MCP 的标准化思路上层自己做一套轻量级的技能管理服务把技能注册、调度、观测这些都接进来。这样既有标准协议的灵活性又不至于被协议边界限制住。2. 核心细节解析与实操要点2.1 技能 Schema 设计每个字段都不是摆设技能定义是整个体系的基石Schema 设计得不好后面所有环节都会出问题。我在实践里反复调整过的技能 Schema 字段如下每条都踩过真实的坑。技能名称name看起来最简单其实最容易出问题。一定要用“动词名词”的清晰结构比如send_email_to_user而不是email_sender。因为模型在选择技能时名称权重很高动词开头的名称比名词开头更容易被模型理解。另外要确保全系统唯一同类技能不要出现多个语义重叠的名字。技能描述description这是最重要的一个字段。模型决定调不调这个技能主要就看描述。描述不能只写“这个技能做什么”还要写“这个技能适合什么场景”“什么情况下不应该用”。我在最早的版本里吃过亏有个get_weather技能描述只写了“获取天气信息”结果模型在需要“根据天气建议穿搭”时也会去调这个技能因为它不知道这个技能只返回天气数据不负责建议。给描述加上场景和边界后这种误用少了很多。入参定义parameters建议用 JSON Schema 风格定义尽量细化参数的类型、格式、默认值、是否必填、取值范围。有一点要特别提醒不要信任模型传入的参数。模型生成参数时很可能漏字段、填错格式所以技能执行前的参数校验和兜底赋值非常重要。我在代码里会给每个参数设置容错处理比如某个参数允许None值时就按业务默认值走。返回结构returns明确返回体的格式最好是统一包装一层比如{status: success, data: ...}或{status: error, code: ..., message: ...}。统一结构的好处是Agent 主流程处理返回结果时可以写一套通用逻辑而不需要针对每个技能单独适配。另外返回值建议尽量精简只返回模型判断下一步所需要的必要信息不要返回来龙去脉的完整大对象否则上下文很快就会被撑爆。权限要求permissions与超时控制timeout这两个字段是后来补上去的。技能不是都能被任意调用的有些技能涉及数据修改、发送消息这类敏感操作需要设置权限标记Agent 侧路由时对应做拦截或二次确认。超时控制则是为了防止技能卡死拖垮整个流程比如某个外部 API 调用没有限制时间一旦挂了整个 Agent 任务都会卡住。给每条技能配一个合理的默认超时值并在执行层强制拦截是必须做的事。2.2 技能描述写作的实操方法论技能描述写得好不好直接决定了模型能不能正确选路。写过几十条技能描述之后我总结出一个三段式结构非常管用一句话功能定义、适用及不适用场景、典型使用示例。一句话功能定义要让模型在 0.5 秒内看懂比如“根据用户查询关键词搜索商品并返回分页列表”。适用及不适用场景要写清楚边界比如“适用于按关键词找商品的场景不适用于传入商品 ID 查询详情这种情况请使用 get_product_detail”。典型使用示例可以放一个极简的入参样例和返回样例模型在看到示例后对怎么调用这个技能会更有把握。一个反面教材是我早期写的某条技能描述只有“查询订单”没有任何场景说明和边界提示。结果模型拿到一个“我要催发货”的任务时调了这个“查询订单”技能其实当时的技能只支持按订单号查状态根本支撑不了“催发货”背后的完整链路。后来我把描述改成了“根据订单号查询订单当前状态、物流进度等基础信息适用于查询类场景如果用户要求催发货或发起投诉请使用 after_sales_service 技能”。这样改完后模型的选型准确率确实上了一个台阶。2.3 技能注册表版本、归属与灰度技能管理不能让技能处于“散装”状态需要有统一的注册中心。我在项目里维护了一张技能注册表核心字段包括技能ID、名称、版本号、所属模块、状态、标签、负责人、更新时间。为什么单独强调版本号因为技能逻辑不是总不变的你今天写的技能过两周可能就要改参数、调整返回结构。如果没有版本管理技能一更新就全量生效线上的 Agent 可能瞬间开始用新逻辑出了问题只能回滚如果还来得及的话。给技能加上版本号并且支持按版本灰度发布能非常有效地控制变更风险。我采用的技能注册表本质上是一个技能元信息库它不存技能实现代码只存技能的定义、来源、依赖、权限等描述信息。当 Agent 启动时注册表会把当前环境可用的技能列表加载到内存中Agent 每次做技能选择前都会在内存中检索技能元数据而不是直接扫描一堆散落的函数。这样可以做到技能的新增、下线、变更都走注册流程避免“烂代码”悄悄进入生产环境。3. 技能调度与执行Agent 怎么选路、怎么落地3.1 技能路由策略纯模型选路并不够技能体系建好之后真正核心的问题来了Agent 面对一堆技能怎么决定调哪个最常见的做法是让模型自己选把技能列表丢给模型让模型输出技能调用意图。这种“LLM 自主选路”在技能数量少、语义边界清晰时表现非常好。但技能数量超过一定阈值或者技能之间的语义相似度比较高时纯模型选路会出现犹疑、误选、跳变的问题。我在实践中的方案是混合路由先做规则预筛再做模型排序。规则预筛的核心思路是利用标签系统和关键词系统先把候选技能集从几十个缩小到三五个。比如说用户的任务含有“天气”那就把带有“天气”标签的技能挑出来然后通过语义相似度算一下把不太可能被用到的技能过滤掉。预筛完成后把缩小后的候选技能列表丢给模型做决策这样模型面临的选择范围大幅缩小决策稳定性明显提高。还有一种情况需要特别注意多个技能都能完成类似的活儿。比如“发送短信”和“发送站内信”语义都是发消息。这时候光靠模型看描述选很容易选错。我采用的方法是在技能标签里增加“渠道偏好”维度让预筛选阶段就根据上下文推断出用户意图更偏哪个渠道比如用户提到“手机收不到”那大概率是短信没有上下文时默认走站内信。模型的决策压力会小很多。3.2 技能执行的生命周期管理一条技能被选中之后执行过程我做了六个环节的管理参数校验、鉴权、执行、结果校验、返回归一化、观测记录。每一步都有明确的处理逻辑。参数校验这一步前面已经说过绝对不能省。除了格式校验我还会做“必填参数补齐”某些参数缺失时能从会话上下文里提取的就自动补上比如用户 ID、当前时间这种常见上下文。鉴权环节则是检查这条技能是否允许当前会话使用比如涉及扣款、涉及敏感数据读取的技能必须有权限标记才能放行。执行环节要注意的地方是技能内部不能假设自己独占资源。我在执行层统一做了超时控制和并发限制任何技能都不能无限跑也不能同时开启太多实例。结果校验是检查技能返回的数据是否符合预期格式防止脏数据直接回流到模型上下文。返回归一化就是把各种技能的不同返回风格统一转成上一步约定的标准结构。观测记录则是把每次技能调用的输入、输出、耗时、错误码、调用链 route 全部记录下来方便后面的问题排查和性能优化。3.3 技能太多塞不进上下文怎么办技能数量一旦过百直接把全部技能描述塞给模型是不现实的即使塞得下模型的注意力也可能被无关噪声干扰。我的解决思路是两级技能目录。第一级是总目录只放每个技能的名称、一句话简介、标签。总目录的目的是让模型知道系统里“有哪些能力”但不用理解细节。第二级是技能详情只有当模型决定某个技能可能被调用时系统才把对应技能的完整描述、入参定义、使用示例注入到对话上下文里。这个机制类似我们查字典先看目录找到页码再翻到那一页查细节而不是把整本字典背下来。实测下来这种做法的收益非常明显。技能总数从六十涨到一百五十上下文中的技能相关 token 占用不升反降模型的选择准确率也稳定住了。实现这个机制的背后需要一套技能检索服务能根据用户当前意图快速召回候选技能并把候选技能的详情动态拼装到提示词里。这也是我后续认为 agent-skills 最值得继续深挖的方向之一。4. 实操过程与核心环节实现4.1 技能注册与加载的最小实现先分享一段技能注册的核心代码这是我项目里的一个简化版本但逻辑完整可跑。我用的语言是 Python主要通过装饰器来完成技能注册。# skill_registry.py import inspect import json from typing import Callable, Dict, Any, List class SkillRegistry: def __init__(self): self._skills: Dict[str, Dict[str, Any]] {} def register(self, name: str, description: str, parameters: dict, version: str 1.0.0, tags: List[str] None, timeout: float 10.0): def decorator(func: Callable): self._skills[name] { name: name, description: description, parameters: parameters, version: version, tags: tags or [], timeout: timeout, func: func, enabled: True, } return func return decorator def get_skill(self, name: str) - Dict[str, Any]: return self._skills.get(name) def list_skills(self) - List[Dict[str, Any]]: 返回技能元信息列表供 Agent 检索 return [{ name: s[name], description: s[description], parameters: s[parameters], version: s[version], tags: s[tags], enabled: s[enabled], } for s in self._skills.values()] def call(self, name: str, **kwargs): skill self.get_skill(name) if not skill: return {status: error, code: SKILL_NOT_FOUND, message: f技能 {name} 不存在} if not skill[enabled]: return {status: error, code: SKILL_DISABLED, message: f技能 {name} 已禁用} # 参数校验与兜底 validated_kwargs self._validate_params(skill[parameters], kwargs) # 执行简化版未加超时线程 try: result skill[func](**validated_kwargs) return {status: success, data: result} except Exception as e: return {status: error, code: SKILL_EXEC_ERROR, message: str(e)}这里我特别想说的是list_skills方法的设计。它只返回元信息不返回函数对象本身。这个细节决定了 Agent 侧永远不需要接触真实执行函数只需要通过技能名字符串去调用这样既方便做权限拦截也为后续把技能执行迁到独立进程或远程服务预留了空间。4.2 技能描述与注册示例现在假设我们要注册一个查询订单状态的技能实际代码如下registry SkillRegistry() registry.register( namequery_order_status, description根据订单号查询订单当前状态、物流进度、预计送达时间等基础信息。 适用于用户查询订单进度、物流位置的场景。 不适用于催发货、退换货、投诉等售后处理场景这些场景请使用 after_sales_service。, parameters{ order_id: {type: string, description: 订单号必填, required: True}, user_id: {type: string, description: 用户ID从上下文补充, required: False}, }, version1.2.0, tags[order, query, logistics], timeout5.0, ) def query_order_status(order_id: str, user_id: str None): # 实际业务逻辑伪代码 # 1. 根据 order_id 查订单库 # 2. 获取订单状态、物流信息 return { order_id: order_id, status: shipped, logistics: 包裹已到达上海分拨中心预计明天送达, }这段代码里你可能会注意到我把user_id设成了非必填但真实业务里查询订单往往需要校验用户权限。这里我故意留了一个口子如果参数校验发现 user_id 缺失但在外部上下文中能拿到会话的用户 ID就会自动补齐。如果补不上则返回权限错误。这种“上下文补充参数”的模式在 Agent 场景里特别实用因为模型通常不会主动把所有隐式参数都传全需要系统在调用链路上做价值补全。4.3 技能的上下文注入与路由执行技能不能光注册完就不管了还要打通 Agent 主流程。下面这段代码展示的是如何从注册表中获取技能元信息、按标签和描述进行候选过滤并按两级目录方式注入上下文。# agent_skill_router.py class SkillRouter: def __init__(self, registry: SkillRegistry): self.registry registry def propose_candidates(self, user_intent: str, top_k: int 5) - List[Dict[str, Any]]: 规则预筛基于关键词与标签粗召回候选技能 all_skills self.registry.list_skills() # 简单打分标签命中 1描述关键词命中 1 scored [] for skill in all_skills: score 0 if any(tag in user_intent for tag in skill[tags]): score 1 desc skill[description].lower() # 提取用户意图关键词简化写法 for kw in user_intent.lower().split(): if kw in desc: score 1 if score 0: scored.append((score, skill)) scored.sort(keylambda x: x[0], reverseTrue) return [s for _, s in scored[:top_k]] def build_prompt_blocks(self, candidates: List[Dict[str, Any]]) - str: 把候选技能拼装成两级目录提示块 # 第一级目录 catalog_lines [可用技能目录] for skill in candidates: catalog_lines.append(f- {skill[name]}: {skill[description][:30]}) # 第二级完整描述只注入候选技能 detail_lines [技能详情] for skill in candidates: detail_lines.append(json.dumps({ name: skill[name], parameters: skill[parameters], description: skill[description], }, ensure_asciiFalse)) return \n.join(catalog_lines detail_lines)你可以看到我把候选召回的逻辑做得很简单就是标签加关键词的轻量匹配。真实项目里这一步可以换成向量检索或更复杂的排序模型但思想一样先粗筛再精排最后用 LLM 决策。粗到细再到模型的链路可以在保证效果的同时大幅降低模型需要处理的 token 数和决策噪声。4.4 接入 LLM 后的实测表现与参数选择技能调度链路搭好后我需要验证效果所以做了一组对比测试。测试集里有一百条用户需求覆盖查询、售后、推荐、退款等八个业务场景目标是把每个需求路由到正确的技能。对比组分别是纯 LLM 直接从全量技能列表选路规则预筛候选注入LLM 选路。实测结果如下方案选路准确率平均响应时间上下文技能相关 token纯 LLM 全量选路60个技能78%1.8s4200规则预筛候选注入LLM 选路91%1.1s1200这个数据更能说明问题规则预筛不只是为了省 token更重要的是把模型的注意力聚焦到最有可能的几个技能上准确率直接从 78% 拉到 91%。上下文相关的 token 消耗也降了 70% 左右对于高并发、高频调用的线上场景来说这既能省钱又能降低响应延迟。另一个更微妙的参数是温度temperature。在做技能选路时我把模型的温度调到了 0.1几乎是最高确定性模式。因为技能选路本质上是一项“判断题”不是“创作题”温度太高会导致模型发挥不稳定同一个问题隔几次调用选不同的技能这在线上的体验是非常致命的。技能执行参数生成比如生成 JSON 参数时也建议用低温度但如果你让模型基于结果做下一步规划的开放式回答不同温度的选择就另说了。5. 常见问题与排查技巧实录5.1 技能完全没被调用这个问题是最常见的也是最折磨人的。模型明明看到了技能描述但就是不用宁愿自己瞎编答案。排查路径我按优先级整理如下第一检查技能的 description 是否有明确的“适用场景”引导如果描述太泛比如只有一句话“提供订单信息”模型很难把它和当前问题关联起来。第二检查技能是否被注册表正确加载有没有被 enabled 标记禁用。真实项目中我踩过这种坑技能逻辑在本地调得好好的上了测试环境才发现注册表没更新技能根本没出现在列表里。第三检查候选预筛逻辑是否误杀有些技能本身没问题但预筛阶段的关键词匹配没命中导致它压根没进候选列表模型当然看不到它。排查时最好在观测日志里加上“候选技能列表”这一环这样能区分到底是预筛阶段漏掉了还是模型在候选里看到了却没用。这条数据对定位问题非常关键。5.2 模型生成了乱参数模型选对了技能但传的参数完全不按 Schema 要求来比如把order_id传成了空字符串或者把数字字段传成了字符串。这个问题在高版本模型上有所缓解但要彻底控制必须靠执行前的参数校验加兜底修正。我的处理方法分三步第一在技能 Schema 中把参数约束写得更严格比如format: string, minLength: 4让模型有更明确的生成依据。第二在参数校验环节做强制类型转换和默认值填充比如接收order_id时如果是None或空字符串尝试从最近对话上下文中提取一个合法的订单号提取不到就直接返回参数错误。第三如果技能反复出现参数错误那么我会在技能描述里加一个“参数示例”用具体的 JSON 示例引导模型输出规范参数。这一步的收益往往比修改 Schema 本身还大因为模型是示例驱动型选手。5.3 技能返回数据太长撑爆上下文有些技能天然会返回大量数据比如搜索接口返回几十条结果每条的字段还老长。如果不做裁剪技能调用两次对话上下文就废了。这个问题在“搜索类”“列表类”技能中尤其突出。解决方案我在实践里把它分为两层一层是技能侧裁剪限制返回条数和字段数比如搜索接口默认只返回 top 10 条每条只保留核心字段标题、价格、缩略图其他全部丢弃另一层是 Agent 主流程侧兜底加一个“返回体大小检查器”一旦发现某次技能返回超过预定的 token 预算就自动做截断或摘要。这种兜底机制能让整个系统在极端数据情况下不至于崩溃大概属于 Agent 开发里“护城河”级别的保护手段。5.4 技能并发与超时问题Agent 在同一轮对话里可能并行调用多个技能比如用户问“比较一下这两个商品的物流速度”Agent 可能同时调用商品查询和物流查询。技能执行时需要做并发控制否则几十个技能同时运行数据库连接池先被压死。我的做法是给技能执行层加一个全局并发限制器使用信号量控制同时执行的技能数量默认设为 8。同时每个技能单独设置超时时间超时直接中断执行并在返回体里带上超时错误码。这样即使某一个技能挂了整个 Agent 流程还能继续运转而不是卡死在那个技能上。这个设计在 Agent 生产化时几乎是刚需你在 demo 阶段感受不到一上真实业务流量就明白它的价值了。5.5 问题速查表症状可能原因排查路径推荐解法技能被识别但未被调用描述缺少场景引导检查描述中的适用与不适用场景按三段式方法重写描述技能未被预筛命中标签缺失或关键词不匹配检查候选列表日志补充技能标签与关键词参数格式错误Schema 约束过弱查看原始入参和校验日志强化 Schema 约束与示例注入返回撑爆上下文技能未裁剪返回体查看返回体 token 统计限制返回条数与字段同时点同意报错并发过高查看执行层并发日志引入信号量并发控制上线后技能不可用注册表未更新检查注册表状态部署时强制同步注册表6. 技能体系的运维与安全加固6.1 技能权限边界最小授权原则技能一旦被 Agent 用起来就不能再像 demo 那样随意。我在技能注册表里增加了权限标记类似permission: read_only或permission: write然后在路由层做拦截。对于只读技能任何会话都可以调用对于涉及修改数据的技能必须要求会话具备特定角色或者在调用前向用户确认。有个真实的教训某次我放开了一个“批量修改订单备注”的技能给测试 Agent 使用没有做权限校验结果 Agent 基于一个语义模糊的需求把一批订单的备注全部改成了同一个模板文本。数据恢复花了两天。从那以后所有写操作技能一律默认关闭接到明确指令并且通过用户授权后才开放。6.2 技能灰度发布与监控技能更新不能拍脑袋直接全量上线。我在注册表里引入了“状态机”的概念技能状态分为开发中、测试中、灰度中、全量、已下线。新技能或大版本更新的技能先在测试环境跑一轮然后灰度到 10% 的线上流量观察一段时间稳定了再全量放开。灰度期间重点监控的指标包括调用成功率、平均耗时、参数非法率、以及模型选路是否出现偏移。这里特别要盯的是“模型选路偏移”。技能灰度更新后描述变了、参数变了、返回结构变了模型的选路行为可能跟着变。比如之前 A 技能能接住的请求更新后模型更倾向于选 B 技能。这种偏移有时候是预期的因为更新就是为了把语义边界划得更清楚但有时候是非预期的可能只是描述里某个词变了导致召回逻辑全变了。所以每次技能变更我都会跑一遍回流测试集用固定的测试需求对比更新前后的选路结果分布变化过大就要审视更新是否合理。6.3 技能健康度评分这是后期加上去的一个运维手段。我针对每条技能周期性统计四个指标调用频次、成功率、平均耗时的波动、参数校验通过率。然后把这些指标综合成技能健康度评分低于阈值的技能自动进入“观察名单”。这个机制帮助我在没有专职运维的情况下仍然能第一时间发现技能质量下降的问题。印象最深的一次某个第三方物流查询接口被服务商悄悄升级返回字段名变了导致我的技能解析逻辑拿到一堆空值成功率从 95% 跌到 55%。如果没有健康度评分这个 bug 可能要在线上跑很久才会被发现。Agent 技能的稳定程度直接决定上层应用的口碑把技能当成有生命周期的服务来运维而不是写完就一劳永逸的脚本是这条路走到后面必然会遇到的问题。7. 一点实战收尾的话坦白说agent-skills 这个方向没有“银弹”不同的业务场景、不同的模型底座、不同的技能数量适合的方案都会有差异。但有一点是通用的技能体系的核心理念是把“能力”变成“可管理、可描述、可调度、可观测”的标准化资产。我最早的做法只是给模型一堆函数签名后来慢慢演进成完整的技能注册、路由、执行、运维体系每一次改进的动机都是被线上真实问题逼出来的。最后分享一个小技巧在你开始为 Agent 注册第 21 条技能的时候强制自己回答三个问题——这条技能和已有技能的功能边界在哪里什么场景下模型不应该选它它失败时的兜底方案是什么回答完这三个问题再注册你会发现技能质量肉眼可见地提升。如果你也正在做 Agent 技能编排在工具选型、调度策略或者排查流程上有新的想法随时值得动手试一试这条路还远没到定型的时候。