最近在整理手头几个 agent 项目的公共代码时我把所有零散的工具函数、提示词片段和流程模板统一收敛到了一套叫agent-skills的体系里。说白了agent-skills 就是给大模型驱动下的智能体做的一套技能注册与执行框架把 agent 能干的每一类事情从“写一个工具函数”升级成“一个带描述、带参数校验、带调用示例、带权限等级、可被检索和编排的技能单元”。做过就知道工具函数一多模型要么在几十个 tools 定义里选错要么干脆无视你精心封装的接口直接瞎编结果。这篇文章我会从技能体系的设计思路讲起再到最小落地系统的完整搭建最后把上线后踩过的坑和排查教训一并整理出来。如果你是正在做 LLM 应用、准备把 agent 从 demo 推向生产的开发者这套东西应该能帮你省掉至少两周的试错时间。1. 先想清楚Agent Skills 到底是什么为什么突然火起来1.1 从“工具调用”到“技能体系”的演变早在 Function Calling 刚开放时大家习惯的做法是给 API 请求里塞一个tools数组把每个函数的名称、参数 JSON Schema 告诉模型然后让模型在对话中决定调哪个。早期 demo 只有三五个工具一切都很美好。但当 agent 要处理真实业务时工具数量很快就会从 5 个涨到 50 个。于是几个问题开始暴露每个工具定义平均要占 300600 token全量塞进上下文光工具描述就把窗口吃掉一大截。工具之间相互“抢活”比如search_web和search_db描述都带“搜索”模型不知道该选哪个。工具的输入输出没有统一规范函数内部报错后模型完全不知情继续往下编。没有观测和治理手段根本不知道哪个工具被调了多少次、成功率如何。我当时被这些问题折腾得不轻最后参考了几个开源社区的实践把“工具”升级成了“技能”。一字之差背后的设计思路完全不同工具强调“我能调用什么接口”技能强调的是“我能完成什么目标”。一个技能不只是函数本身还包含模型调用它时需要的所有辅助信息触发条件、参数约束、典型用法示例、前置依赖、输出结构、失败恢复策略。这套东西的集合就是 agent-skills。1.2 一套技能体系要解决的核心问题把零散工具函数升级成技能体系不是形式主义而是为了解决生产环境里的四个核心问题。可发现性是第一个要解决的。agent 拿到用户需求时得能回答“我会什么”。这靠技能注册表完成所有技能都登记在一个结构化索引里模型或者上层的规划模块可以先去检索技能列表挑出与当前任务相关的技能而不是让模型从一段冗长的 JSON 里大海捞针。可组合性是第二个。单技能只能做单步操作真实任务往往是多步流程。技能体系要求把“搜索网页”和“提取正文”这样的小能力做成原子技能然后再编排成“调研一个主题并输出报告”这样的复合技能。复合技能内部调用原子技能时和 agent 主循环调用技能的方式是一致的这样整个体系就能递归扩展。可治理性是第三个也最容易被忽略。技能一旦多起来谁能调、谁不能调、这个技能对应哪条业务权限必须有明确定义。我会在技能元数据里增加permission_level字段分等级控制防止 agent 在无人监督时执行高风险操作比如删除文件、发邮件、调支付接口。可观测性是最后一个。每个技能执行完要记录调用方、参数摘要、耗时、token 消耗、成功还是失败。没有这套数据后续排查问题完全靠猜更别提做技能层面的持续优化。我见过很多团队技能库越用越烂根因就是不知道哪个技能是拖后腿的。1.3 技能与工具、插件、工作流的边界很多人会问技能和插件、工作流有什么区别。我自己总结了一套判断标准插件偏重系统集成工作流偏重固定流程技能偏重能力封装与模型协作。插件通常是外部系统接入的适配层比如 Slack 插件、数据库插件工作流则是预先定义好的步骤序列比如“每日定时抓取新闻→打标→入库”。技能介于两者之间它强调“能力单元可以被模型动态选择和调用”而不是被流程写死。这个边界非常重要。如果你把工作流硬塞进技能体系会发现模型经常在中间步骤上自作主张把固定流程执行得面目全非。反过来如果只依赖工作流而不做技能抽象每次新增一个类似但略有不同的任务你就得复制一条新的工作流长期维护成本很高。理解了这层边界再往下做设计时才不会跑偏。2. 技能体系设计命名、分层与注册2.1 技能粒度怎么定原子技能与复合技能体系设计里最优先的问题不是“用什么框架承载技能”而是“技能粒度切到多细”。切太粗技能变成不灵活的业务接口换个场景就没法复用切太细编排复杂度爆炸模型在决策时也容易迷路。我的经验是先把技能分成两层原子技能不可再拆的单一操作通常对应一次外部 API 调用或一次确定性计算。例如web_search调用搜索接口、fetch_page抓取网页、url_to_markdown正文提取。原子技能要求输入输出完全确定没有歧义执行时间尽量控制在秒级。复合技能由多个原子技能按固定或半固定顺序编排而成完成一个相对完整的目标。例如research_topic内部流程可能是web_search找候选链接 →fetch_page抓前 5 个页面 →extract_main_content提取正文 →summarize_text生成摘要。选择原子技能粒度时可以问自己一个问题这个步骤是否会被两个以上不同的复合技能复用答案是肯定的话就拆成原子技能答案是否定可以先做成私有子函数等出现复用需求再提升为技能。不要为了“优雅”提前拆得过细技能数量失控后描述和维护都跟不上。2.2 技能注册表让 Agent 知道“自己会什么”技能粒度和层级定完你要做一个技能注册表也就是所有技能的元数据清单。这是 agent-skills 体系和普通工具库最直接的差异点。没有注册表技能只是散落的函数有了注册表模型和上层规划器才能在运行时动态了解能力边界。我习惯用一个skills.yaml来维护注册表每个技能一个条目下面是一个最小可用示例skills: - name: web_search version: 1.2.0 type: atomic description: 通过搜索引擎检索互联网信息输入为查询词输出为带标题、链接、摘要的搜索结果列表。适合查找最新资料、验证事实、发现相关页面。 tags: [search, web, information_retrieval] permission_level: low parameters: type: object properties: query: type: string description: 搜索查询词建议使用精确、简洁的关键词组合。 top_k: type: integer description: 返回结果数量默认 5最大 10。 required: [query] returns: type: array items: type: object properties: title: { type: string } url: { type: string } snippet: { type: string } usage_examples: - input: 查找 2025 年大模型 Agent 的最新评测报告 output_summary: 返回 5 条主流媒体与博客的评测链接注意description字段它是最影响模型调用效果的地方。不要简单写“搜索函数”要写清楚触发条件、输入形式、输出结构。我建议用这样的模板“通过 XX 方式完成 XX 目标输入为 XX输出为 XX适合 XX 场景。”后面还可以加一句“不适合做什么”比如对某个技能来说“本技能不提供实时行情数据”这能明显减少模型乱用的概率。usage_examples字段也是提升技能命中率的利器。你可以不提供完整输入输出但至少要给一个“输入长什么样”的示例。模型在 few-shot 模式下对示例的依赖很强一个带具体查询词的示例比任何抽象描述都管用。2.3 技能分层架构别把楼层盖歪有了注册表还需要定义运行时的分层架构。我实际用的分层是四层接入层负责接收用户请求做意图识别或任务规划决定调用哪个复合技能。编排层运行复合技能的流程逻辑调度原子技能处理状态传递、重试、回退。执行层执行原子技能做参数校验、权限校验、调用外部 API、解析返回结果。存储层保存技能执行记录、审计日志、耗时指标供后续分析和优化。这个分层最大的好处是职责清晰。编排层只关心“流程怎么走”不关心“日志写到哪个索引”执行层只关心“这次调用怎么成功”不关心“上层为什么选这个技能”。出了问题排查路径也很清晰先看编排层的决策记录再看执行层的调用日志最后看存储层的指标。分层不是越严越好。如果你的场景只需要一个复合技能和三个原子技能完全可以把编排和执行写在一起。我在这类小项目里也这么干过毕竟过度设计可比没有设计更烦人。分层真正的收益在技能数量超过 20 个、同时有多个业务方接入后才会完全体现。3. 落地实操一个最小技能系统的完整搭建3.1 项目结构与环境准备理论说完直接上手。以下这套最小实现是我在一个调研类 agent 项目里实际用过的结构技术栈是 Python 3.11 FastAPI OpenAI SDK技能执行用简单的独立进程模型不引入额外重框架。agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py │ ├── base.py │ ├── atomic/ │ │ ├── web_search.py │ │ ├── fetch_page.py │ │ └── summarize_text.py │ └── composite/ │ └── research_topic.py ├── config/ │ └── skills.yaml ├── runtime/ │ ├── executor.py │ └── orchestrator.py ├── api/ │ └── main.py └── tests/在动手写代码前先把依赖装好pip install fastapi uvicorn openai pydantic pyyaml httpx beautifulsoup4对了技能系统对接的大模型 API 建议统一封装在runtime/llm.py里不要在技能内部各自调用否则后面做模型切换或 prompt 统一管理时会很痛苦。3.2 定义一个技能基类从函数到技能的关键一步最核心的抽象是base.py里的Skill基类。它把技能的元数据和执行逻辑绑定在一起让注册表可以直接从类定义中提取信息。# skills/base.py from abc import ABC, abstractmethod from typing import Any, Dict, Optional class Skill(ABC): 所有技能的基类。 name: str version: str 0.1.0 type: str atomic # atomic 或 composite description: str tags: list [] permission_level: str low parameters_schema: Dict[str, Any] {} usage_examples: list [] abstractmethod async def execute(self, params: Dict[str, Any], context: Optional[Dict[str, Any]] None) - Dict[str, Any]: 执行技能返回结构化结果。 def validate_params(self, params: Dict[str, Any]) - None: 参数校验使用 jsonschema 或手写逻辑。 from jsonschema import validate, ValidationError try: validate(instanceparams, schemaself.parameters_schema) except ValidationError as e: raise ValueError(f技能 {self.name} 参数校验失败: {e.message})这里有几个细节值得展开validate_params必须在执行前调用。模型填参数时的幻觉能力很强会给你填出完全不符合要求的类型不校验直接调外部接口报错信息又不会回流给模型整个调用链就废了。校验失败时抛出带明确信息的异常让上层捕获后把错误内容拼到模型的下一轮输入里。context参数用来传递会话级信息比如用户身份、当前时间、历史摘要、调用链 trace_id。不要把这类信息塞进params因为params会进入模型的工具调用参数包含太多内部字段既浪费 token又可能泄露敏感信息。3.3 注册表与动态工具定义把技能喂给大模型注册表负责从skills.yaml加载技能配置同时维护一个“技能名称 → 技能实例”的映射。初始化和工具定义生成我放在registry.py# skills/registry.py import yaml from typing import Dict, List from skills.base import Skill from skills.atomic.web_search import WebSearchSkill from skills.atomic.fetch_page import FetchPageSkill from skills.atomic.summarize_text import SummarizeTextSkill from skills.composite.research_topic import ResearchTopicSkill SKILL_CLASSES [ WebSearchSkill, FetchPageSkill, SummarizeTextSkill, ResearchTopicSkill, ] class SkillRegistry: def __init__(self, config_path: str): self._skills: Dict[str, Skill] {} with open(config_path, r, encodingutf-8) as f: self.config yaml.safe_load(f) for cls in SKILL_CLASSES: skill cls() self._skills[skill.name] skill def get(self, name: str) - Skill: return self._skills[name] def list_skills(self) - List[Skill]: return list(self._skills.values()) def to_openai_tools(self, skill_names: List[str]) - List[Dict]: 把指定技能转换成 OpenAI function calling 格式。” tools [] for name in skill_names: skill self._skills[name] tools.append({ type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters_schema, } }) return tools重点看to_openai_tools的入参是skill_names列表而不是直接把所有技能全部转成 tools 塞给 API。这里用到了“技能检索”的思路每次请求前先通过关键词匹配或向量检索从注册表里召回最相关的 top N 个技能只给模型看这些。初始版本可以先用简单的关键词交集实现比如把用户请求和每个技能的tags、description做词频匹配取分数最高的几个。后面需要更精准再换成 embedding 检索。只传召回后的技能能同时解决 token 膨胀和工具过多导致的选择困难问题实测对一个 40 技能的库调用准确率能提升十几个百分点。3.4 一个完整的原子技能网页抓取下面用一个非常常用的技能展示单个原子技能的完整实现。fetch_page的目标很简单输入 URL输出干净的文本正文。# skills/atomic/fetch_page.py import httpx from bs4 import BeautifulSoup from skills.base import Skill class FetchPageSkill(Skill): name fetch_page version 1.0.0 description ( 抓取指定网页并提取正文文本输入为 URL输出为纯文本正文。 适合用于阅读文章、获取网页详细内容。不适合登录后可访问的页面和动态渲染较多的页面。 ) tags [web, crawler, content_extraction] permission_level low parameters_schema { type: object, properties: { url: {type: string, description: 需要抓取的完整 URL}, max_chars: {type: integer, description: 返回的最大字符数默认 5000} }, required: [url] } async def execute(self, params, contextNone): self.validate_params(params) url params[url] max_chars params.get(max_chars, 5000) if not url.startswith((http://, https://)): raise ValueError(furl 必须以 http:// 或 https:// 开头收到: {url}) async with httpx.AsyncClient(timeout15, follow_redirectsTrue) as client: resp await client.get(url) resp.raise_for_status() # 根据 Content-Type 判断是否需要解析 HTML content_type resp.headers.get(content-type, ) if text/html in content_type: soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer, iframe]): tag.decompose() text soup.get_text(separator\n, stripTrue) else: text resp.text return {url: url, content: text[:max_chars], truncated: len(text) max_chars}再说一个特别容易踩的坑技能返回结构里一定要带truncated这样的标志位。抓取长文章时resposne 被 5000 字截断如果模型不知道内容被截断了它可能拿着不完整内容继续做总结最后产出一份残缺报告。显式传递“截断”信号模型才有机会决定是否要抓取下一页或只基于已有内容作答。fetch_page这类技能还应该考虑 robots 协议和请求频率限制稳妥的做法是在内部设置默认 user-agent并对同一域名做简单限速。虽然这会增加一点实现量但比起因为爬虫行为导致外部封禁 IP这点成本非常划算。3.5 复合技能编排让多个步骤稳定跑通复合技能的编写方式和原子技能不一样。它的execute里通常没有外部 API 调用而是编排多个原子技能。这里有一个关键设计决策复合技能内部是写死调用顺序还是让内部每一步也用模型决定我的建议是核心流程尽量写死分支判断才交给模型。把整个流程全交给模型自由发挥执行时间和成本都会失控。下面是一个research_topic的简化实现流程固定为“搜索→抓前几篇→提取正文→逐个总结→汇总”。# skills/composite/research_topic.py from skills.base import Skill from skills.registry import SkillRegistry class ResearchTopicSkill(Skill): name research_topic version 1.1.0 type composite description ( 对一个主题进行多源调研并输出结构化摘要输入为调研主题输出为带来源链接的要点列表。 适合技术选型调研、竞品信息收集、新闻事件梳理等需要浏览多个网页的场景。 ) tags [research, multi_step, summarization] permission_level medium parameters_schema { type: object, properties: { topic: {type: string, description: 调研主题}, num_sources: {type: integer, description: 抓取来源数量默认 3最大 5} }, required: [topic] } async def execute(self, params, contextNone): self.validate_params(params) registry: SkillRegistry context[registry] llm context[llm] topic params[topic] num_sources params.get(num_sources, 3) search registry.get(web_search) fetch registry.get(fetch_page) summarize registry.get(summarize_text) results [] search_out await search.execute({query: topic, top_k: num_sources}, context) for item in search_out[results]: try: page await fetch.execute({url: item[url], max_chars: 8000}, context) summary await summarize.execute({text: page[content], mode: bullet_points}, context) results.append({ title: item[title], url: item[url], summary: summary[summary], }) except Exception as e: # 记录部分失败但继续处理其他来源 results.append({title: item.get(title, ), url: item.get(url, ), summary: f[抓取失败] {str(e)}}) return {topic: topic, sources_reviewed: len(results), points: results}注意research_topic的execute里对单个链接的抓取失败做了降级处理不影响整体任务。这是复合技能和原子技能另一个关键差异复合技能必须包含降级策略不能因为某个子步骤失败就让整个调研任务陪葬。不过降级和“静默吞错”是两回事。这里我还是把失败信息写进了返回结果模型能看到“这个来源抓取失败了”从而在总结时知道信息的覆盖范围是打折扣的。把错误留在结果里而不是藏在日志里这个习惯能避免大量“看起来成功其实漏了关键信息”的事故。3.6 运行时编排器让 Agent 主循环与技能体系协作到这一步技能体系已经能独立跑了但还需要一个桥梁接回 Agent 主循环。编排器完成三件事技能检索、调用大模型、循环执行模型请求的工具调用。# runtime/orchestrator.py import json from skills.registry import SkillRegistry from runtime.llm import chat_completion async def run_agent(user_request: str, registry: SkillRegistry, llm_client): # 1. 技能召回只给模型看相关的技能 candidate_names retrieve_skills(user_request, registry) # 简化关键词匹配 tools registry.to_openai_tools(candidate_names) # 2. 多轮工具调用循环 messages [{role: user, content: user_request}] max_iters 8 for _ in range(max_iters): resp await chat_completion(llm_client, messagesmessages, toolstools, tool_choiceauto) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content # 3. 逐个执行模型请求的技能 for tc in msg.tool_calls: fn_name tc.function.name try: fn_params json.loads(tc.function.arguments) skill registry.get(fn_name) skill_result await skill.execute(fn_params, context{registry: registry, llm: llm_client}) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(skill_result, ensure_asciiFalse) }) except Exception as e: messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps({error: str(e)}, ensure_asciiFalse) }) return 达到最大迭代次数任务未完成这个循环有几个坑要特别提醒。第一异常必须作为 tool 消息返回给模型。我见过很多实现工具一报错直接把整个 agent 流程中断模型连解释和补救的机会都没有。把{error: ...}返回给模型模型至少能自己改写参数重试或者向用户说明失败原因。第二要设置最大循环次数防止 agent 在技能调用上“无限套娃”。max_iters 8是经验值太小的确容易误伤复杂任务但 8 轮对绝大多数任务已经足够。超限后的返回值也要明确告诉用户“任务未完成”不要伪装成成功。第三工具返回内容本身就是上下文的一部分要控制体积。网页正文一次就是 5000 字如果 8 轮全在抓网页上下文早就爆了。我一般在把工具结果追加到messages之前会额外做一次截断比如设定“单条 tool 消息不超过 6000 字符”。这个限制要写在技能层还是编排层我选择在编排层统一处理因为技能层不清楚模型窗口的剩余量。4. 技能质量、评估与治理别让技能库变成垃圾堆4.1 技能描述写得好不好用一个数据集测出来技能加多了以后最让人头疼的问题不是实现而是“模型根本不知道该在什么时候用某个技能”。这个问题的根源几乎都在描述上。描述抽象了模型不知道技能能干什么描述太具体模型又只会在完全匹配的场景下调用。怎么客观评估描述质量我的做法是建一个命中测试集专门用来测技能召回的 recallk。具体操作是挑 50100 条历史用户请求人工标注“这条请求应该触发哪些技能”。然后分别在“全量工具传入”和“检索 top 5 召回”两种模式下统计模型工具调用的命中率。如果召回阶段就漏了正确技能问题出在检索逻辑或描述里的关键词覆盖不足。如果召回了但模型不调用说明描述里的“触发条件”和“使用场景”写得含糊。跑一轮测试后把漏召回的描述拿出来改写重点参考这类句式的调整“当用户想要 XX 时使用本技能当用户只提到 YY 时不要使用本技能。”实测把“不要使用”的边界写进描述比只写正向触发条件效果更明显。4.2 运行时观测把每次技能调用变成数据技能体系上线后第一个要建的基础设施是执行日志和指标。每个技能执行结束后至少要记录以下字段字段示例说明skill_nameweb_search技能名skill_version1.2.0技能版本trace_id8f3a2c会话级链路 IDparams_summaryqueryf大模型评测, top_k5脱敏后的参数摘要statussuccess / failed执行结果latency_ms1203耗时token_cost2560本次执行消耗的 token 近似值error_messagetimeout失败时的错误信息成功时为空这些数据用来回答几个高频问题哪个技能耗时最长哪个技能失败率最高哪个技能消耗了最多 token没有这些数据你优化技能库就只能靠感觉。我见过一个团队把所有技能都接入大模型结果发现 80% 的 token 消耗来自于一个很少被真正需要的“网页全文总结”技能因为它的描述太泛导致模型频繁调用这就是观测日志救命的典型例子。trace_id还要向上与 agent 主循环的请求关联向下与外部 API 调用的日志关联。否则排查问题时前端用户说“刚才那个报告怎么漏了一块”你却不知道是哪轮对话里的哪次技能调用导致漏的只能瞎翻日志。4.3 权限与安全高风险技能必须单独管控技能体系有一个容易被忽视的隐患能力越强破坏力也越大。当你把“执行代码”“删除文件”“发送消息”“调用支付”都包装成技能后如果权限控制不做一个 prompt injection 攻击就可能让 agent 去删库。我实践中的权限分四级low只读类查询、搜索、抓取普通用户会话可调用。medium涉及写操作但影响有限比如写入草稿、创建工单。high影响外部系统状态比如发邮件、提交订单、改配置。critical不可逆操作比如删除、转账、批量执行必须二次确认。权限校验放在编排层每次执行技能前检查当前会话的权限等级是否满足skill.permission_level要求。不满足时直接返回给模型“无权限执行该技能请向用户说明”。不要把这个错误伪装成技能内部报错区别很重要技能内部报错可能是暂时的权限不足是确定的模型需要知道这一点才能给出正确应答。此外我强烈建议给技能加“参数黑名单”机制。以execute_code这样的技能为例即使权限检查通过也要对入参做内容级拦截比如禁止包含rm -rf、drop table等危险模式。多一层过滤不会完全防住攻击但能让常规误操作的概率降到最低。5. 常见问题与排查技巧实录5.1 高频问题速查表技能体系跑了一段时间后我整理了下面这张问题速查表。遇到问题先对照它能省不少时间现象可能原因排查方法解决方案模型完全不用某个技能描述太抽象或触发条件没写明白在测试集里单独看该技能的 recall 和 call 率重写描述加入“适合/不适合”边界和 usage_examples模型频繁调用错误技能技能间描述重叠、职责不清对比两个技能的描述和参数 schema明确划分职责在描述里互斥声明工具调用报错但 agent 不重试异常没有返回给模型看编排器是否把异常写进 tool 消息捕获异常并作为 tool 结果返回内容包含错误原因上下文很快被打满工具结果太大或召回了过多技能查看上下文明细统计每条 tool 消息大小工具结果截断技能召回 top N 设为 35复合技能一步失败整体中断降级策略缺失查看复合技能代码是否有 try-except对非关键子步骤做降级处理结果里保留失败说明模型传参经常缺失必填字段parameters_schema 不完整或描述不足查看失败参数记录强化 properties 里的 description必要时在描述里给参数示例同一技能多轮调用互相干扰状态被错误埋进了 skill 实例检查技能类是否保存了实例级状态技能保持无状态临时数据通过 context 传递5.2 我踩过的三个坑坑一高级技能偷偷泄漏到普通会话。我们早期把注册表里所有技能一次性注册没有按权限过滤结果一个只读调研 agent 在极少数情况下会调用send_email虽然没真发出去目标 API 配置错误但日志分析发现后出了一身冷汗。从那以后我从两个层面强制权限注册表加载时标记权限编排器执行前校验会话权限缺一层都不行。坑二复合技能里 catch 所有异常然后假装成功。第一版research_topic我把子步骤异常全部吞掉只返回正常结构的空列表。模型拿到空列表后一本正经地总结说“该主题目前没有足够的公开资料”——实际是搜索接口超时了。用户差点被误导最后靠 trace 日志才发现。现在所有降级路径都必须在返回里显式标注[失败]前缀让信息缺口透明可见。坑三技能库“毕业即过时”。技能上线后接口的外部服务方改了参数格式我们没第一时间更新技能 schema模型开始疯狂报参数错误。后来我加了一个简单的健康检查每周自动跑一轮所有原子技能的冒烟测试发送最小合法入参检查返回码和响应结构。一旦失败立刻告警并定位是外部 API 变更还是技能本身 bug。这个小投入让技能库的可用性从“随缘”变成了“有保障”。6. 从技能库到技能生态再往前走一步把单个项目的 agent-skills 体系跑顺之后我开始考虑跨项目和跨团队的复用。几个思路仅供参考属于我已经验证过可行但还在持续迭代的方向。技能包标准化与共享。现在的skills.yaml可以演变成一个技能的 manifest 文件除了名称、描述、权限还加上依赖声明、运行环境要求、作者和维护者信息。这样不同项目可以通过简单声明依赖来安装技能包也可以用内部仓库管理技能包的版本和分发。这件事的意义在于同一个公司内不同业务线的 agent可以共享底层的通用技能搜索、抓取、文本处理同时各自维护领域专属技能互不干扰。技能版本化与 A/B 测试。当技能从一个函数变成一个被多个 agent 依赖的组件时版本管理就不能只靠 git 注释了。我用语义化版本号管理每个技能当技能描述或执行逻辑发生变化时版本号递增。运行时可以让一部分请求走新版本技能另一部分走旧版本用上一节提到的观测数据做对比。不要小看这个简单机制它让你敢于快速迭代“哪些描述更能提高模型调用准确率”这类实验而不用担心改崩线上流程。让 agent 自己沉淀新技能。这是目前比较前沿的方向。我在实验把“新技能自动生成”也做成一个技能先截取一段 agent 反复操作但尚未形成固定技能的过程让模型把过程拆解成步骤和工具调用序列再生成代码骨架和描述草案最后由人审核后合入技能库。效果还不稳定但趋势很明显未来 skill 不再只是人写给人读的文档而是模型辅助人共同维护的动态资产。另外技能体系做大了以后技能之间的依赖和冲突会成为一个新的维护难点。比如复合技能 A 依赖的web_search是 1.0 版复合技能 B 已经在用 2.0 版如果 2.0 改了返回结构A 可能会出问题。这个问题的解法我还在摸索中目前的临时方案是在复合技能内部固定锁原子技能版本升级时显式回归相关复合技能。最后再分享一条比较务实的经验技能体系的价值不在于代码写得多精致而在于你舍得花时间持续调描述、看日志、补测试集。我第一次搭好框架时很兴奋但真正让 agent 表现变稳定的是不厌其烦地根据线上日志把每个技能的描述打磨了三五遍。技能库会随着业务一起进化别指望一蹴而就也别因为前期效果不明显就放弃——等你上手调过一轮命中率之后就会明白这套体系对 agent 生产级落地意味着什么了。
Agent技能体系设计：从工具调用到智能体生产级落地
最近在整理手头几个 agent 项目的公共代码时我把所有零散的工具函数、提示词片段和流程模板统一收敛到了一套叫agent-skills的体系里。说白了agent-skills 就是给大模型驱动下的智能体做的一套技能注册与执行框架把 agent 能干的每一类事情从“写一个工具函数”升级成“一个带描述、带参数校验、带调用示例、带权限等级、可被检索和编排的技能单元”。做过就知道工具函数一多模型要么在几十个 tools 定义里选错要么干脆无视你精心封装的接口直接瞎编结果。这篇文章我会从技能体系的设计思路讲起再到最小落地系统的完整搭建最后把上线后踩过的坑和排查教训一并整理出来。如果你是正在做 LLM 应用、准备把 agent 从 demo 推向生产的开发者这套东西应该能帮你省掉至少两周的试错时间。1. 先想清楚Agent Skills 到底是什么为什么突然火起来1.1 从“工具调用”到“技能体系”的演变早在 Function Calling 刚开放时大家习惯的做法是给 API 请求里塞一个tools数组把每个函数的名称、参数 JSON Schema 告诉模型然后让模型在对话中决定调哪个。早期 demo 只有三五个工具一切都很美好。但当 agent 要处理真实业务时工具数量很快就会从 5 个涨到 50 个。于是几个问题开始暴露每个工具定义平均要占 300600 token全量塞进上下文光工具描述就把窗口吃掉一大截。工具之间相互“抢活”比如search_web和search_db描述都带“搜索”模型不知道该选哪个。工具的输入输出没有统一规范函数内部报错后模型完全不知情继续往下编。没有观测和治理手段根本不知道哪个工具被调了多少次、成功率如何。我当时被这些问题折腾得不轻最后参考了几个开源社区的实践把“工具”升级成了“技能”。一字之差背后的设计思路完全不同工具强调“我能调用什么接口”技能强调的是“我能完成什么目标”。一个技能不只是函数本身还包含模型调用它时需要的所有辅助信息触发条件、参数约束、典型用法示例、前置依赖、输出结构、失败恢复策略。这套东西的集合就是 agent-skills。1.2 一套技能体系要解决的核心问题把零散工具函数升级成技能体系不是形式主义而是为了解决生产环境里的四个核心问题。可发现性是第一个要解决的。agent 拿到用户需求时得能回答“我会什么”。这靠技能注册表完成所有技能都登记在一个结构化索引里模型或者上层的规划模块可以先去检索技能列表挑出与当前任务相关的技能而不是让模型从一段冗长的 JSON 里大海捞针。可组合性是第二个。单技能只能做单步操作真实任务往往是多步流程。技能体系要求把“搜索网页”和“提取正文”这样的小能力做成原子技能然后再编排成“调研一个主题并输出报告”这样的复合技能。复合技能内部调用原子技能时和 agent 主循环调用技能的方式是一致的这样整个体系就能递归扩展。可治理性是第三个也最容易被忽略。技能一旦多起来谁能调、谁不能调、这个技能对应哪条业务权限必须有明确定义。我会在技能元数据里增加permission_level字段分等级控制防止 agent 在无人监督时执行高风险操作比如删除文件、发邮件、调支付接口。可观测性是最后一个。每个技能执行完要记录调用方、参数摘要、耗时、token 消耗、成功还是失败。没有这套数据后续排查问题完全靠猜更别提做技能层面的持续优化。我见过很多团队技能库越用越烂根因就是不知道哪个技能是拖后腿的。1.3 技能与工具、插件、工作流的边界很多人会问技能和插件、工作流有什么区别。我自己总结了一套判断标准插件偏重系统集成工作流偏重固定流程技能偏重能力封装与模型协作。插件通常是外部系统接入的适配层比如 Slack 插件、数据库插件工作流则是预先定义好的步骤序列比如“每日定时抓取新闻→打标→入库”。技能介于两者之间它强调“能力单元可以被模型动态选择和调用”而不是被流程写死。这个边界非常重要。如果你把工作流硬塞进技能体系会发现模型经常在中间步骤上自作主张把固定流程执行得面目全非。反过来如果只依赖工作流而不做技能抽象每次新增一个类似但略有不同的任务你就得复制一条新的工作流长期维护成本很高。理解了这层边界再往下做设计时才不会跑偏。2. 技能体系设计命名、分层与注册2.1 技能粒度怎么定原子技能与复合技能体系设计里最优先的问题不是“用什么框架承载技能”而是“技能粒度切到多细”。切太粗技能变成不灵活的业务接口换个场景就没法复用切太细编排复杂度爆炸模型在决策时也容易迷路。我的经验是先把技能分成两层原子技能不可再拆的单一操作通常对应一次外部 API 调用或一次确定性计算。例如web_search调用搜索接口、fetch_page抓取网页、url_to_markdown正文提取。原子技能要求输入输出完全确定没有歧义执行时间尽量控制在秒级。复合技能由多个原子技能按固定或半固定顺序编排而成完成一个相对完整的目标。例如research_topic内部流程可能是web_search找候选链接 →fetch_page抓前 5 个页面 →extract_main_content提取正文 →summarize_text生成摘要。选择原子技能粒度时可以问自己一个问题这个步骤是否会被两个以上不同的复合技能复用答案是肯定的话就拆成原子技能答案是否定可以先做成私有子函数等出现复用需求再提升为技能。不要为了“优雅”提前拆得过细技能数量失控后描述和维护都跟不上。2.2 技能注册表让 Agent 知道“自己会什么”技能粒度和层级定完你要做一个技能注册表也就是所有技能的元数据清单。这是 agent-skills 体系和普通工具库最直接的差异点。没有注册表技能只是散落的函数有了注册表模型和上层规划器才能在运行时动态了解能力边界。我习惯用一个skills.yaml来维护注册表每个技能一个条目下面是一个最小可用示例skills: - name: web_search version: 1.2.0 type: atomic description: 通过搜索引擎检索互联网信息输入为查询词输出为带标题、链接、摘要的搜索结果列表。适合查找最新资料、验证事实、发现相关页面。 tags: [search, web, information_retrieval] permission_level: low parameters: type: object properties: query: type: string description: 搜索查询词建议使用精确、简洁的关键词组合。 top_k: type: integer description: 返回结果数量默认 5最大 10。 required: [query] returns: type: array items: type: object properties: title: { type: string } url: { type: string } snippet: { type: string } usage_examples: - input: 查找 2025 年大模型 Agent 的最新评测报告 output_summary: 返回 5 条主流媒体与博客的评测链接注意description字段它是最影响模型调用效果的地方。不要简单写“搜索函数”要写清楚触发条件、输入形式、输出结构。我建议用这样的模板“通过 XX 方式完成 XX 目标输入为 XX输出为 XX适合 XX 场景。”后面还可以加一句“不适合做什么”比如对某个技能来说“本技能不提供实时行情数据”这能明显减少模型乱用的概率。usage_examples字段也是提升技能命中率的利器。你可以不提供完整输入输出但至少要给一个“输入长什么样”的示例。模型在 few-shot 模式下对示例的依赖很强一个带具体查询词的示例比任何抽象描述都管用。2.3 技能分层架构别把楼层盖歪有了注册表还需要定义运行时的分层架构。我实际用的分层是四层接入层负责接收用户请求做意图识别或任务规划决定调用哪个复合技能。编排层运行复合技能的流程逻辑调度原子技能处理状态传递、重试、回退。执行层执行原子技能做参数校验、权限校验、调用外部 API、解析返回结果。存储层保存技能执行记录、审计日志、耗时指标供后续分析和优化。这个分层最大的好处是职责清晰。编排层只关心“流程怎么走”不关心“日志写到哪个索引”执行层只关心“这次调用怎么成功”不关心“上层为什么选这个技能”。出了问题排查路径也很清晰先看编排层的决策记录再看执行层的调用日志最后看存储层的指标。分层不是越严越好。如果你的场景只需要一个复合技能和三个原子技能完全可以把编排和执行写在一起。我在这类小项目里也这么干过毕竟过度设计可比没有设计更烦人。分层真正的收益在技能数量超过 20 个、同时有多个业务方接入后才会完全体现。3. 落地实操一个最小技能系统的完整搭建3.1 项目结构与环境准备理论说完直接上手。以下这套最小实现是我在一个调研类 agent 项目里实际用过的结构技术栈是 Python 3.11 FastAPI OpenAI SDK技能执行用简单的独立进程模型不引入额外重框架。agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py │ ├── base.py │ ├── atomic/ │ │ ├── web_search.py │ │ ├── fetch_page.py │ │ └── summarize_text.py │ └── composite/ │ └── research_topic.py ├── config/ │ └── skills.yaml ├── runtime/ │ ├── executor.py │ └── orchestrator.py ├── api/ │ └── main.py └── tests/在动手写代码前先把依赖装好pip install fastapi uvicorn openai pydantic pyyaml httpx beautifulsoup4对了技能系统对接的大模型 API 建议统一封装在runtime/llm.py里不要在技能内部各自调用否则后面做模型切换或 prompt 统一管理时会很痛苦。3.2 定义一个技能基类从函数到技能的关键一步最核心的抽象是base.py里的Skill基类。它把技能的元数据和执行逻辑绑定在一起让注册表可以直接从类定义中提取信息。# skills/base.py from abc import ABC, abstractmethod from typing import Any, Dict, Optional class Skill(ABC): 所有技能的基类。 name: str version: str 0.1.0 type: str atomic # atomic 或 composite description: str tags: list [] permission_level: str low parameters_schema: Dict[str, Any] {} usage_examples: list [] abstractmethod async def execute(self, params: Dict[str, Any], context: Optional[Dict[str, Any]] None) - Dict[str, Any]: 执行技能返回结构化结果。 def validate_params(self, params: Dict[str, Any]) - None: 参数校验使用 jsonschema 或手写逻辑。 from jsonschema import validate, ValidationError try: validate(instanceparams, schemaself.parameters_schema) except ValidationError as e: raise ValueError(f技能 {self.name} 参数校验失败: {e.message})这里有几个细节值得展开validate_params必须在执行前调用。模型填参数时的幻觉能力很强会给你填出完全不符合要求的类型不校验直接调外部接口报错信息又不会回流给模型整个调用链就废了。校验失败时抛出带明确信息的异常让上层捕获后把错误内容拼到模型的下一轮输入里。context参数用来传递会话级信息比如用户身份、当前时间、历史摘要、调用链 trace_id。不要把这类信息塞进params因为params会进入模型的工具调用参数包含太多内部字段既浪费 token又可能泄露敏感信息。3.3 注册表与动态工具定义把技能喂给大模型注册表负责从skills.yaml加载技能配置同时维护一个“技能名称 → 技能实例”的映射。初始化和工具定义生成我放在registry.py# skills/registry.py import yaml from typing import Dict, List from skills.base import Skill from skills.atomic.web_search import WebSearchSkill from skills.atomic.fetch_page import FetchPageSkill from skills.atomic.summarize_text import SummarizeTextSkill from skills.composite.research_topic import ResearchTopicSkill SKILL_CLASSES [ WebSearchSkill, FetchPageSkill, SummarizeTextSkill, ResearchTopicSkill, ] class SkillRegistry: def __init__(self, config_path: str): self._skills: Dict[str, Skill] {} with open(config_path, r, encodingutf-8) as f: self.config yaml.safe_load(f) for cls in SKILL_CLASSES: skill cls() self._skills[skill.name] skill def get(self, name: str) - Skill: return self._skills[name] def list_skills(self) - List[Skill]: return list(self._skills.values()) def to_openai_tools(self, skill_names: List[str]) - List[Dict]: 把指定技能转换成 OpenAI function calling 格式。” tools [] for name in skill_names: skill self._skills[name] tools.append({ type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters_schema, } }) return tools重点看to_openai_tools的入参是skill_names列表而不是直接把所有技能全部转成 tools 塞给 API。这里用到了“技能检索”的思路每次请求前先通过关键词匹配或向量检索从注册表里召回最相关的 top N 个技能只给模型看这些。初始版本可以先用简单的关键词交集实现比如把用户请求和每个技能的tags、description做词频匹配取分数最高的几个。后面需要更精准再换成 embedding 检索。只传召回后的技能能同时解决 token 膨胀和工具过多导致的选择困难问题实测对一个 40 技能的库调用准确率能提升十几个百分点。3.4 一个完整的原子技能网页抓取下面用一个非常常用的技能展示单个原子技能的完整实现。fetch_page的目标很简单输入 URL输出干净的文本正文。# skills/atomic/fetch_page.py import httpx from bs4 import BeautifulSoup from skills.base import Skill class FetchPageSkill(Skill): name fetch_page version 1.0.0 description ( 抓取指定网页并提取正文文本输入为 URL输出为纯文本正文。 适合用于阅读文章、获取网页详细内容。不适合登录后可访问的页面和动态渲染较多的页面。 ) tags [web, crawler, content_extraction] permission_level low parameters_schema { type: object, properties: { url: {type: string, description: 需要抓取的完整 URL}, max_chars: {type: integer, description: 返回的最大字符数默认 5000} }, required: [url] } async def execute(self, params, contextNone): self.validate_params(params) url params[url] max_chars params.get(max_chars, 5000) if not url.startswith((http://, https://)): raise ValueError(furl 必须以 http:// 或 https:// 开头收到: {url}) async with httpx.AsyncClient(timeout15, follow_redirectsTrue) as client: resp await client.get(url) resp.raise_for_status() # 根据 Content-Type 判断是否需要解析 HTML content_type resp.headers.get(content-type, ) if text/html in content_type: soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer, iframe]): tag.decompose() text soup.get_text(separator\n, stripTrue) else: text resp.text return {url: url, content: text[:max_chars], truncated: len(text) max_chars}再说一个特别容易踩的坑技能返回结构里一定要带truncated这样的标志位。抓取长文章时resposne 被 5000 字截断如果模型不知道内容被截断了它可能拿着不完整内容继续做总结最后产出一份残缺报告。显式传递“截断”信号模型才有机会决定是否要抓取下一页或只基于已有内容作答。fetch_page这类技能还应该考虑 robots 协议和请求频率限制稳妥的做法是在内部设置默认 user-agent并对同一域名做简单限速。虽然这会增加一点实现量但比起因为爬虫行为导致外部封禁 IP这点成本非常划算。3.5 复合技能编排让多个步骤稳定跑通复合技能的编写方式和原子技能不一样。它的execute里通常没有外部 API 调用而是编排多个原子技能。这里有一个关键设计决策复合技能内部是写死调用顺序还是让内部每一步也用模型决定我的建议是核心流程尽量写死分支判断才交给模型。把整个流程全交给模型自由发挥执行时间和成本都会失控。下面是一个research_topic的简化实现流程固定为“搜索→抓前几篇→提取正文→逐个总结→汇总”。# skills/composite/research_topic.py from skills.base import Skill from skills.registry import SkillRegistry class ResearchTopicSkill(Skill): name research_topic version 1.1.0 type composite description ( 对一个主题进行多源调研并输出结构化摘要输入为调研主题输出为带来源链接的要点列表。 适合技术选型调研、竞品信息收集、新闻事件梳理等需要浏览多个网页的场景。 ) tags [research, multi_step, summarization] permission_level medium parameters_schema { type: object, properties: { topic: {type: string, description: 调研主题}, num_sources: {type: integer, description: 抓取来源数量默认 3最大 5} }, required: [topic] } async def execute(self, params, contextNone): self.validate_params(params) registry: SkillRegistry context[registry] llm context[llm] topic params[topic] num_sources params.get(num_sources, 3) search registry.get(web_search) fetch registry.get(fetch_page) summarize registry.get(summarize_text) results [] search_out await search.execute({query: topic, top_k: num_sources}, context) for item in search_out[results]: try: page await fetch.execute({url: item[url], max_chars: 8000}, context) summary await summarize.execute({text: page[content], mode: bullet_points}, context) results.append({ title: item[title], url: item[url], summary: summary[summary], }) except Exception as e: # 记录部分失败但继续处理其他来源 results.append({title: item.get(title, ), url: item.get(url, ), summary: f[抓取失败] {str(e)}}) return {topic: topic, sources_reviewed: len(results), points: results}注意research_topic的execute里对单个链接的抓取失败做了降级处理不影响整体任务。这是复合技能和原子技能另一个关键差异复合技能必须包含降级策略不能因为某个子步骤失败就让整个调研任务陪葬。不过降级和“静默吞错”是两回事。这里我还是把失败信息写进了返回结果模型能看到“这个来源抓取失败了”从而在总结时知道信息的覆盖范围是打折扣的。把错误留在结果里而不是藏在日志里这个习惯能避免大量“看起来成功其实漏了关键信息”的事故。3.6 运行时编排器让 Agent 主循环与技能体系协作到这一步技能体系已经能独立跑了但还需要一个桥梁接回 Agent 主循环。编排器完成三件事技能检索、调用大模型、循环执行模型请求的工具调用。# runtime/orchestrator.py import json from skills.registry import SkillRegistry from runtime.llm import chat_completion async def run_agent(user_request: str, registry: SkillRegistry, llm_client): # 1. 技能召回只给模型看相关的技能 candidate_names retrieve_skills(user_request, registry) # 简化关键词匹配 tools registry.to_openai_tools(candidate_names) # 2. 多轮工具调用循环 messages [{role: user, content: user_request}] max_iters 8 for _ in range(max_iters): resp await chat_completion(llm_client, messagesmessages, toolstools, tool_choiceauto) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content # 3. 逐个执行模型请求的技能 for tc in msg.tool_calls: fn_name tc.function.name try: fn_params json.loads(tc.function.arguments) skill registry.get(fn_name) skill_result await skill.execute(fn_params, context{registry: registry, llm: llm_client}) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(skill_result, ensure_asciiFalse) }) except Exception as e: messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps({error: str(e)}, ensure_asciiFalse) }) return 达到最大迭代次数任务未完成这个循环有几个坑要特别提醒。第一异常必须作为 tool 消息返回给模型。我见过很多实现工具一报错直接把整个 agent 流程中断模型连解释和补救的机会都没有。把{error: ...}返回给模型模型至少能自己改写参数重试或者向用户说明失败原因。第二要设置最大循环次数防止 agent 在技能调用上“无限套娃”。max_iters 8是经验值太小的确容易误伤复杂任务但 8 轮对绝大多数任务已经足够。超限后的返回值也要明确告诉用户“任务未完成”不要伪装成成功。第三工具返回内容本身就是上下文的一部分要控制体积。网页正文一次就是 5000 字如果 8 轮全在抓网页上下文早就爆了。我一般在把工具结果追加到messages之前会额外做一次截断比如设定“单条 tool 消息不超过 6000 字符”。这个限制要写在技能层还是编排层我选择在编排层统一处理因为技能层不清楚模型窗口的剩余量。4. 技能质量、评估与治理别让技能库变成垃圾堆4.1 技能描述写得好不好用一个数据集测出来技能加多了以后最让人头疼的问题不是实现而是“模型根本不知道该在什么时候用某个技能”。这个问题的根源几乎都在描述上。描述抽象了模型不知道技能能干什么描述太具体模型又只会在完全匹配的场景下调用。怎么客观评估描述质量我的做法是建一个命中测试集专门用来测技能召回的 recallk。具体操作是挑 50100 条历史用户请求人工标注“这条请求应该触发哪些技能”。然后分别在“全量工具传入”和“检索 top 5 召回”两种模式下统计模型工具调用的命中率。如果召回阶段就漏了正确技能问题出在检索逻辑或描述里的关键词覆盖不足。如果召回了但模型不调用说明描述里的“触发条件”和“使用场景”写得含糊。跑一轮测试后把漏召回的描述拿出来改写重点参考这类句式的调整“当用户想要 XX 时使用本技能当用户只提到 YY 时不要使用本技能。”实测把“不要使用”的边界写进描述比只写正向触发条件效果更明显。4.2 运行时观测把每次技能调用变成数据技能体系上线后第一个要建的基础设施是执行日志和指标。每个技能执行结束后至少要记录以下字段字段示例说明skill_nameweb_search技能名skill_version1.2.0技能版本trace_id8f3a2c会话级链路 IDparams_summaryqueryf大模型评测, top_k5脱敏后的参数摘要statussuccess / failed执行结果latency_ms1203耗时token_cost2560本次执行消耗的 token 近似值error_messagetimeout失败时的错误信息成功时为空这些数据用来回答几个高频问题哪个技能耗时最长哪个技能失败率最高哪个技能消耗了最多 token没有这些数据你优化技能库就只能靠感觉。我见过一个团队把所有技能都接入大模型结果发现 80% 的 token 消耗来自于一个很少被真正需要的“网页全文总结”技能因为它的描述太泛导致模型频繁调用这就是观测日志救命的典型例子。trace_id还要向上与 agent 主循环的请求关联向下与外部 API 调用的日志关联。否则排查问题时前端用户说“刚才那个报告怎么漏了一块”你却不知道是哪轮对话里的哪次技能调用导致漏的只能瞎翻日志。4.3 权限与安全高风险技能必须单独管控技能体系有一个容易被忽视的隐患能力越强破坏力也越大。当你把“执行代码”“删除文件”“发送消息”“调用支付”都包装成技能后如果权限控制不做一个 prompt injection 攻击就可能让 agent 去删库。我实践中的权限分四级low只读类查询、搜索、抓取普通用户会话可调用。medium涉及写操作但影响有限比如写入草稿、创建工单。high影响外部系统状态比如发邮件、提交订单、改配置。critical不可逆操作比如删除、转账、批量执行必须二次确认。权限校验放在编排层每次执行技能前检查当前会话的权限等级是否满足skill.permission_level要求。不满足时直接返回给模型“无权限执行该技能请向用户说明”。不要把这个错误伪装成技能内部报错区别很重要技能内部报错可能是暂时的权限不足是确定的模型需要知道这一点才能给出正确应答。此外我强烈建议给技能加“参数黑名单”机制。以execute_code这样的技能为例即使权限检查通过也要对入参做内容级拦截比如禁止包含rm -rf、drop table等危险模式。多一层过滤不会完全防住攻击但能让常规误操作的概率降到最低。5. 常见问题与排查技巧实录5.1 高频问题速查表技能体系跑了一段时间后我整理了下面这张问题速查表。遇到问题先对照它能省不少时间现象可能原因排查方法解决方案模型完全不用某个技能描述太抽象或触发条件没写明白在测试集里单独看该技能的 recall 和 call 率重写描述加入“适合/不适合”边界和 usage_examples模型频繁调用错误技能技能间描述重叠、职责不清对比两个技能的描述和参数 schema明确划分职责在描述里互斥声明工具调用报错但 agent 不重试异常没有返回给模型看编排器是否把异常写进 tool 消息捕获异常并作为 tool 结果返回内容包含错误原因上下文很快被打满工具结果太大或召回了过多技能查看上下文明细统计每条 tool 消息大小工具结果截断技能召回 top N 设为 35复合技能一步失败整体中断降级策略缺失查看复合技能代码是否有 try-except对非关键子步骤做降级处理结果里保留失败说明模型传参经常缺失必填字段parameters_schema 不完整或描述不足查看失败参数记录强化 properties 里的 description必要时在描述里给参数示例同一技能多轮调用互相干扰状态被错误埋进了 skill 实例检查技能类是否保存了实例级状态技能保持无状态临时数据通过 context 传递5.2 我踩过的三个坑坑一高级技能偷偷泄漏到普通会话。我们早期把注册表里所有技能一次性注册没有按权限过滤结果一个只读调研 agent 在极少数情况下会调用send_email虽然没真发出去目标 API 配置错误但日志分析发现后出了一身冷汗。从那以后我从两个层面强制权限注册表加载时标记权限编排器执行前校验会话权限缺一层都不行。坑二复合技能里 catch 所有异常然后假装成功。第一版research_topic我把子步骤异常全部吞掉只返回正常结构的空列表。模型拿到空列表后一本正经地总结说“该主题目前没有足够的公开资料”——实际是搜索接口超时了。用户差点被误导最后靠 trace 日志才发现。现在所有降级路径都必须在返回里显式标注[失败]前缀让信息缺口透明可见。坑三技能库“毕业即过时”。技能上线后接口的外部服务方改了参数格式我们没第一时间更新技能 schema模型开始疯狂报参数错误。后来我加了一个简单的健康检查每周自动跑一轮所有原子技能的冒烟测试发送最小合法入参检查返回码和响应结构。一旦失败立刻告警并定位是外部 API 变更还是技能本身 bug。这个小投入让技能库的可用性从“随缘”变成了“有保障”。6. 从技能库到技能生态再往前走一步把单个项目的 agent-skills 体系跑顺之后我开始考虑跨项目和跨团队的复用。几个思路仅供参考属于我已经验证过可行但还在持续迭代的方向。技能包标准化与共享。现在的skills.yaml可以演变成一个技能的 manifest 文件除了名称、描述、权限还加上依赖声明、运行环境要求、作者和维护者信息。这样不同项目可以通过简单声明依赖来安装技能包也可以用内部仓库管理技能包的版本和分发。这件事的意义在于同一个公司内不同业务线的 agent可以共享底层的通用技能搜索、抓取、文本处理同时各自维护领域专属技能互不干扰。技能版本化与 A/B 测试。当技能从一个函数变成一个被多个 agent 依赖的组件时版本管理就不能只靠 git 注释了。我用语义化版本号管理每个技能当技能描述或执行逻辑发生变化时版本号递增。运行时可以让一部分请求走新版本技能另一部分走旧版本用上一节提到的观测数据做对比。不要小看这个简单机制它让你敢于快速迭代“哪些描述更能提高模型调用准确率”这类实验而不用担心改崩线上流程。让 agent 自己沉淀新技能。这是目前比较前沿的方向。我在实验把“新技能自动生成”也做成一个技能先截取一段 agent 反复操作但尚未形成固定技能的过程让模型把过程拆解成步骤和工具调用序列再生成代码骨架和描述草案最后由人审核后合入技能库。效果还不稳定但趋势很明显未来 skill 不再只是人写给人读的文档而是模型辅助人共同维护的动态资产。另外技能体系做大了以后技能之间的依赖和冲突会成为一个新的维护难点。比如复合技能 A 依赖的web_search是 1.0 版复合技能 B 已经在用 2.0 版如果 2.0 改了返回结构A 可能会出问题。这个问题的解法我还在摸索中目前的临时方案是在复合技能内部固定锁原子技能版本升级时显式回归相关复合技能。最后再分享一条比较务实的经验技能体系的价值不在于代码写得多精致而在于你舍得花时间持续调描述、看日志、补测试集。我第一次搭好框架时很兴奋但真正让 agent 表现变稳定的是不厌其烦地根据线上日志把每个技能的描述打磨了三五遍。技能库会随着业务一起进化别指望一蹴而就也别因为前期效果不明显就放弃——等你上手调过一轮命中率之后就会明白这套体系对 agent 生产级落地意味着什么了。