搞AI Agent开发做久了，你会发现一个特别拧巴的现象：模型本身明明越来越强，可真正落地到业务里，总是卡在"使唤不动工具"这一步。聊天、写文案、生成代码这些纯文本任务，大模型已经玩得很溜了；但让它去查数据库、调第三方API、批量处理文件、协同几个工具完成一条完整链路，就越改越乱。我最近在做的这个agent-skills项目，就是奔着这个痛点去的——它是一套给智能体配备的、可插拔、可复用的技能体系，把"模型会说什么"和"模型能做什么"彻底拆开，让每个能力点都变成独立的技能模块，可以单独开发、单独测试、单独升级。
这套思路最直接的收益，是再也不用把几十个工具的说明全部塞进系统提示词里，也不需要在Prompt里写一堆"如果用户提到天气就调用天气API、如果提到订餐就调用订餐API"这种脆弱的规则。Agent的"大脑"只管理解和决策，"双手"交给agent-skills去调度。如果你正被Agent的工具调用混乱、上下文爆炸、技能难复用这些问题折腾，这篇文章应该能给你一个可以直接上手的方案。
1. 项目概述：agent-skills究竟在解决什么问题
1.1 从"会聊天"到"会办事"，差的就是这层技能抽象
先聊聊我在做Agent时踩出来的认知。最初的时候，我给智能体接工具的方式非常朴素：把所有工具的描述写成JSON Schema，塞进Prompt，让模型自己根据用户意图挑一个来调用。听起来挺合理，工具少的时候也确实能用。但一旦工具数量超过十几个，问题就来了——Prompt被塞得越来越长，模型开始"选择困难"，要么调错工具，要么在无关工具的描述上消耗大量注意力，响应质量肉眼可见地下降。更要命的是，每加一个新工具，都要重新调一遍Prompt，因为这个工具的描述和已有描述之间的干扰是不可控的。
agent-skills的核心思路，是把这个过程从"在Prompt里写说明书"变成"注册一套可管理的技能"。每个技能就是一个独立封装的能力单元，它有自己清晰的输入输出、触发条件和执行逻辑。模型通过一套统一的接口去调用技能，而不是直接面对一堆混乱的函数签名。这样做最直接的好处：技能和模型解耦了。模型换了一家，技能不用重写；技能内部逻辑重构，模型的调用方式也不用变化。
打个比方，这就像你雇了一个助理。如果助理脑子里随时要背一百条操作手册，那他做事又慢又容易出错；但如果他把操作流程都做成了标准化的SOP卡片，接到指令直接抽卡片执行，效率和准确率就完全不同。agent-skills干的就是把SOP卡片体系建立起来。
1.2 项目定位：不只是工具调用，更是技能的全生命周期管理
市面上很多框架已经在做函数调用（function calling）了，那agent-skills和它们有什么区别？我自己实践的体会是，函数调用只是"最后一步的执行动作"，而agent-skills覆盖的是技能的完整生命周期。
来看看一个技能从出生到退役要经历什么：首先是定义，你要想清楚这个技能解决什么场景、输入是什么、输出是什么；然后是注册，把它挂到技能中心，让Agent能发现它；接着是编排，多个技能怎么组合成一条流水线；再然后是监控和反馈，技能执行失败怎么报告、怎么重试；最后是演进，一个技能被新技能替代或者废弃后，怎么平滑下线。agent-skills把这几个环节都纳入了设计范围，而不是只盯着"调用那一刻"。
这个定位带来的改变很实在。团队协作的时候，每个成员可以并行开发不同技能，互不干扰，因为技能之间的边界是清晰的。技能库可以沉淀下来，这个项目里写的搜索技能，下个项目直接复用。Agent的提示词主体保持稳定，只把技能清单动态注入，维护成本大幅降低。
2. 技能体系的设计思路与拆解
2.1 技能的本质：把"意图"翻译成"动作"
在设计技能体系之前，我先想明白了一件事：一个技能到底是什么？拆到最底层，技能就是一组"条件-动作"的映射。条件是用户输入或者系统状态满足某个特征，动作是程序执行的一段逻辑。但要让它对Agent友好，这层映射必须包装成模型能理解的形态。
所以agent-skills里，每个技能包含四个核心要素：名称、描述、参数Schema、执行函数。名称要短且语义清晰，方便模型在候选列表里快速锁定；描述要说清楚"这个技能在什么场景下用、能解决什么问题、有哪些限制"，这是模型做选择的主要依据；参数Schema定义调用时传什么参数、类型是什么、哪些必填；执行函数才是真正干活的代码。
你可能会觉得，这不就是把工具定义拆成几个字段吗？是的，但关键在于"描述"怎么写。我刚开始写技能描述时，总想着把所有细节都写进去，结果模型反而抓不住重点。后来总结出一套实用的写法：开门见山说明用途，然后给条件限制，再给一个典型示例。举个例子，搜索技能的描述我这样写："当用户需要查询最新信息、新闻、实时数据时使用，返回网页标题和摘要列表。不适合查询你的训练知识里已经存在的常识性问题。例如：'帮我查一下今天某股票的价格'。"
这样写的好处是给模型划清了决策边界，它知道什么时候该用、什么时候不该用，比笼统的"搜索工具"要好用得多。
2.2 技能的四层抽象：接口、实现、编排、反馈
agent-skills的技能体系我分成了四层，每层各司其职，层与层之间用明确的契约衔接。
第一层是接口层。这是模型和执行函数之间的协议，定义了技能的名称、描述、参数Schema和返回结构。接口层必须保持稳定，因为模型就靠这份协议来理解和调用技能。我见过有些项目把接口设计和内部实现耦合得很紧，工具列表一换，模型行为就飘了，这是要避免的。
第二层是实现层。这是技能的代码实体，负责真正执行任务。实现层的核心要求是"高内聚低耦合"，一个技能只做一件事，比如"发送邮件"、"查询订单"、"生成图表"各自独立。实现层可以依赖任何第三方库、内部服务，这些都是实现细节，对外不可见。
第三层是编排层。它解决"多个技能如何协作"的问题。编排可以是显式的——你写一段流程代码，先调A技能拿结果，再根据结果调B技能；也可以是隐式的——把技能清单全部交给模型，让模型自行决定调用顺序和参数，Agent框架负责循环执行。agent-skills两种都支持，实际操作中我更倾向于"显式流程+模型决策"的混合模式，关键路径写死，分支选择交给模型判断。
第四层是反馈层。技能执行完，结果要返回给模型，而且要以模型容易理解的格式返回。这里有个很容易被忽略的点：返回给模型的内容需要经过"精简和提炼"。一个搜索技能如果直接把几千字的网页正文抛给模型，上下文马上被撑爆；正确做法是提取标题、摘要、链接这些结构化信息，必要的时候再做一次总结提炼。反馈层做得好不好，直接决定Agent在多轮对话里能不能保持稳定表现。
2.3 为什么不用"一个大Prompt"搞定所有技能
有人会问：既然模型的理解能力这么强，为什么不把所有技能说明一次性写进系统Prompt，让模型自己看着办？这个问题我一开始也纠结过，实测下来发现这条路在技能数量少的时候没问题，一旦技能库扩大，问题就成倍放大。
首先是上下文长度竞争。模型可用的上下文窗口是有限的，你把技能说明写得越详细，留给用户对话和历史记忆的空间就越小。五十个技能、每个技能描述两百字符，一下子就吃掉一万字符，这还没算参数Schema。其次是注意力稀释，模型在处理冗长列表时，对排在后面的技能关注度显著下降，我用GPT系列和开源模型都测过，排在候选列表末尾的技能被正确选中的概率明显偏低。这种"长尾遗忘"在Agent场景里是很致命的。
agent-skills的做法是为Agent提供一个"技能发现"机制，而不是一次性把所有技能全部暴露。模型首先面对的是一个精简的技能入口，比如按领域分组：搜索类、数据处理类、内容生成类、系统操作类。Agent可以先调用"技能导航"来决定具体需要哪一类，然后动态加载该组的详细技能清单。这种方式把模型需要同时处理的信息量降了一个数量级，决策准确率自然就上来了。
3. 核心实操：手写一套可复用的Agent技能框架
3.1 技能注册表与统一接口设计
先把代码层面的设计拿出来晾晾。整个技能框架的底座是一个注册表（Registry），它是所有技能的中枢，负责登记、索引、查询技能。我用Python写了一个最小的实现，核心结构大概是这样的：
# skill_registry.py from dataclasses import dataclass, field from typing import Callable, Any, Dict, List, Optional import inspect @dataclass class Skill: name: str description: str parameters: List[Dict[str, Any]] handler: Callable[..., Any] tags: List[str] = field(default_factory=list) enabled: bool = True class SkillRegistry: def __init__(self): self._skills: Dict[str, Skill] = {} def register(self, skill: Skill): if skill.name in self._skills: raise ValueError(f"Skill '{skill.name}' already registered") self._skills[skill.name] = skill return skill def get(self, name: str) -> Optional[Skill]: return self._skills.get(name) def list_skills(self, tag: Optional[str] = None) -> List[Skill]: if tag is None: return list(self._skills.values()) return [s for s in self._skills.values() if tag in s.tags] # 为模型生成技能清单JSON def schema_for_llm(self): return [ { "name": s.name, "description": s.description, "parameters": s.parameters, "required": [p["name"] for p in s.parameters if p.get("required")] } for s in self._skills.values() if s.enabled ]注册表本身不复杂，关键在于它解决了几个实际问题。第一，技能集中管理，换模型、换框架都不影响技能注册方式；第二，支持按标签检索，方便动态加载不同领域的技能；第三，schema_for_llm方法直接生成模型需要的JSON格式，省去了手工拼装的步骤。实际部署时我会在Skill里再加几个字段，比如version（版本号）、author（负责人）、timeout（超时时间）、retry_policy（重试策略），这些在线上维护时非常有用。
注册一个技能的代码长这样：
# skills/web_search.py from skill_registry import Skill, SkillRegistry registry = SkillRegistry() def _execute_search(query: str, top_k: int = 5) -> str: # 这里是调用搜索API、抓取结果、提取摘要的逻辑 # 返回结构化文本给LLM results = [] # for item in search_api.search(query): # results.append({"title": item.title, "url": item.url, "snippet": item.snippet}) return "\n".join(f"- {r['title']} {r['url']} {r['snippet']}" for r in results[:top_k]) web_search = Skill( name="web_search", description="搜索网页获取最新信息，适合查询实时新闻、数据、事件等动态内容。", parameters=[ {"name": "query", "type": "string", "required": True, "description": "搜索关键词"}, {"name": "top_k", "type": "integer", "required": False, "description": "返回结果数量，默认5"} ], handler=_execute_search, tags=["search", "web"], ) registry.register(web_search)这里有一个细节我想提醒：参数尽量少，而且每个参数一定要写清楚description。模型在生成函数调用参数时，非常依赖参数描述来判断该填什么值。"query"我标注了"搜索关键词"，模型就会把用户原话里的关键实体提取出来填进去；如果你不写，它可能把整句用户输入塞进去，导致搜索效果稀碎。
3.2 用Function Calling把技能暴露给模型
技能注册好了，接下来要让模型能用上。目前主流模型基本都支持function calling（有些叫tool use），你只要把技能清单转成对应的格式传过去，模型在需要的时候会返回一个结构化的调用指令。以OpenAI格式为例，调用流程是这样的：
# agent_loop.py import json from openai import OpenAI client = OpenAI() def agent_run(user_input: str, skill_schemas: list): messages = [{"role": "user", "content": user_input}] response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=[ {"type": "function", "function": schema} for schema in skill_schemas ], tool_choice="auto" ) msg = response.choices[0].message if msg.tool_calls: tool_result = execute_tool_calls(msg.tool_calls) messages.append(msg) messages.append({ "role": "tool", "tool_call_id": msg.tool_calls[0].id, "content": tool_result }) # 把工具结果返回给模型，让它生成最终回答 final = client.chat.completions.create( model="gpt-4o-mini", messages=messages, ) return final.choices[0].message.content else: return msg.content def execute_tool_calls(tool_calls): results = [] for call in tool_calls: fn_name = call.function.name fn_args = json.loads(call.function.arguments) skill = registry.get(fn_name) if not skill: results.append(f"Error: skill {fn_name} not found") continue try: result = skill.handler(**fn_args) results.append(result) except Exception as e: results.append(f"Error executing {fn_name}: {str(e)}") return "\n".join(str(r) for r in results)这个循环本身不复杂，但有几个环节很容易踩坑。一个是消息历史的管理：工具调用返回之后，要把assistant的原始响应（包含tool_calls）也追加到消息列表，否则模型不知道这个工具调用是它自己发起的，处理多轮工具调用时尤其容易乱。另一个是错误捕获：工具执行期间，网络超时、API限流、数据格式异常都有可能发生，如果不做兜底，一场对话直接就中断了。我习惯在execute_tool_calls里把异常转成字符串返回给模型，至少让它有继续往下走的机会。
如果你用的是其他模型，适配思路是一样的：把工具的JSON Schema转成对应模型的格式。开源模型比如Qwen、DeepSeek也有类似能力，只是细节上有差异，封装一层的意义就在这儿。
3.3 技能编排：从单技能调用到多轮任务流
单个技能调用很好理解，但真实的Agent任务很少是"查一下就完事"。更多时候，任务需要分解成多个步骤，每个步骤调用不同技能，中间可能还要根据上一步的结果做判断。这就是编排层要处理的。
我在agent-skills里设计了一个轻量级的"任务流"概念，用Python装饰器来声明多个技能之间的依赖关系。看一个简单的例子：用户问"最新的AI新闻里有哪些重要的产品发布"，这个任务至少需要两步——搜索新闻、从结果中提炼产品发布信息。
# workflow.py from skill_registry import registry @registry.workflow("news_analysis") def news_analysis_flow(query: str): # 第一步，搜索 search_result = registry.get("web_search").handler(query=query, top_k=8) # 第二步，调用"信息提取"技能，从搜索结果中提取产品发布信息 extract_result = registry.get("extract_entities").handler( text=search_result, entity_types=["product_launch"] ) # 第三步，调用"报告生成"技能，生成结构化摘要 report = registry.get("generate_report").handler(content=extract_result, format="markdown") return report这种显式流程的好处是可控、可调试、可测试。每一步的输入输出都是确定的，出了问题直接在对应步骤上排查。缺点是需要开发人员预先编排好流程，适合场景清晰、规则明确的任务。
另一种编排方式是让模型自己决定流程。把多个技能全部暴露给模型，模型在每一轮都自主决定调用哪个技能、传什么参数，Agent循环执行直到模型认为任务完成。这种方式灵活性强，适合开放式任务，但需要严格控制循环次数，防止模型陷入死循环。我通常在Agent外层套一个max_steps限制，比如最多执行5轮工具调用，超出就强制终止并返回阶段性结果。
实际做下来，我觉得最实用的还是"混合编排"：主流程用代码固定，保证任务不会跑偏；分支决策交给模型，保留灵活性。比如"数据分析报告"这个流程，数据查询、清洗、绘图三个步骤是固定的，但每一步用什么参数、要不要额外筛选，会由模型根据中间结果动态决定。这套组合既稳又活。
4. 技能实现中的关键细节与避坑指南
4.1 技能上下文如何隔离与传递
多技能协作时，技能之间的数据传递是个容易被低估的问题。最朴素的做法是把技能A的返回值原封不动拼进技能B的输入参数里，但结果往往很尴尬。原因在于，大模型处理长文本时的注意力是有限度的，A返回了5000字的原始结果，B的参数Schema里根本没有对应字段能承接，模型只能胡编乱造地截取一段，信息失真严重。
我的解决办法是给技能的输出设计一个"摘要层"。每个技能在返回结果之前，先经过一个可选的post_process函数，把原始结果归纳成结构化的、精简的数据。比如搜索技能，原始返回可能有20条网页摘要，post_process阶段会根据相关性、时效性筛掉一半，再把每条摘要压缩成一句话，最后只保留5条给模型。这样既保留了关键信息，又不会污染上下文。
上下文在不同技能间传递的另一种形式是共享存储。我设计了一个session_context对象，可以理解成一次Agent执行任务期间的公共记事本。技能A写入中间结果，技能B可以直接读取。但这里有个纪律：写入共享上下文的必须是"干净、结构化的中间产物"，不能直接把原始输出丢进去。每次写入前问自己一个问题——这个值对后续其他技能是否有明确价值？没价值的就坚决不写。
4.2 错误处理与重试机制的实践经验
Agent运行在真实环境里，各种异常都是家常便饭：第三方API超时、返回数据格式不对、并发限流、临时网络抖动。一套健壮的错误处理机制，比多写10个技能都管用。
我在agent-skills里给每个技能配了三种错误处理策略。第一种是重试（retry）：适合瞬时故障，比如网络超时、限流，用指数退避的方式重试，最多三次，第一次等待1秒，第二次2秒，第三次4秒。第二种是降级（degrade）：当主技能不可用时，调用备选技能顶上。比如搜索服务挂了，就改用缓存检索或者调用备选搜索引擎。第三种是明确失败（fail-fast）：对于业务逻辑错误，比如参数校验不过、权限不足，不要反复重试，直接把错误信息格式化后返回给模型，让模型换个思路或者向用户说明。
有一个坑我必须专门提出来：不要在技能内部抛出太长的异常堆栈。有些技能依赖的SDK一报错就是一长串traceback，如果你原封不动传给模型，模型会被这些噪音干扰，甚至尝试去修代码。正确做法是把异常信息精简成一句话加一个错误码，比如"E1001: search service timeout after 5s"。模型看到这个信息就知道该换方案了，而不是陷入诊断代码的死胡同。
幂等性问题也值得关注。某些技能被重复执行会产生副作用，比如"发送邮件"技能，模型如果因为超时而发起重试，用户很可能收到两封相同邮件。这就是为什么技能设计时要分清楚"安全可重试"和"不可重试"两类。对于后者，在执行前先分配一个全局唯一的request_id，如果重试时发现相同request_id已处理过，就直接返回上次结果，不做实际操作。这个技巧在处理支付、通知、写入类操作时尤其重要。
4.3 实测中踩过的三个坑
第一个坑：参数Schema写得太松。我之前给某个技能定义参数时，把description写得模棱两可，结果模型把完全不合法的值传进来，技能内部也没有做校验，最后返回了一堆乱码数据，模型还一本正经地把乱码拿去用了。后来我养成了习惯：在技能函数入口处强制做参数校验，类型不对就抛异常或者返回默认值，绝不在半路才暴露问题。
第二个坑：技能输出格式不稳定。同一个技能，有时候返回纯文本，有时候返回JSON，模型的解析逻辑还得兼容两种格式，非常容易出bug。现在所有技能的返回值我都统一成一个简单的JSON对象，至少包含status（成功/失败）、data（结构化结果）、message（人类可读的简述）。模型拿到这个固定格式，解析逻辑就简单多了。
第三个坑：技能太多导致模型挑花眼。有一次我把20多个技能全部暴露给一个开源模型，模型的工具选择准确率掉到了六成以下。后来我引入了分组导航机制，模型先选技能组，再在组内选具体技能，准确率提升明显。这个现象在多个模型上都复现过，基本可以确认是模型的普遍弱项，所以技能数量超过15个的时候，一定要考虑分组或动态加载。
5. 把技能体系扩展到真实场景
5.1 场景一：代码仓库智能体
有个我实践过的场景是代码仓库智能体。传统上你要让Agent理解一个仓库，需要把大量代码文本喂给它，成本高且效果有限。用agent-skills的思路，我封装了几个专用技能：get_repo_structure（获取目录树）、search_code（代码语义搜索）、read_file（读取指定文件内容）、run_tests（运行测试）、git_log（查看提交历史）。
这组技能的巧妙之处在于，Agent并不需要把整个仓库读进来，而是按需探查。它先调用get_repo_structure了解全貌，再根据用户需求调用search_code定位相关代码，最后用read_file细看具体实现。整个过程上下文消耗极小，而且回答质量比"整库塞入"的方式高得多。这就是技能化的威力：把"理解代码库"这个大问题拆成了几个小技能的组合。
5.2 场景二：数据分析智能体
另一个典型场景是数据分析。分析任务天然适合拆解成技能链：query_database（查询数据）、validate_data（数据质量检查）、analyze_statistics（统计分析）、visualize_chart（生成图表）、generate_insight（生成解读）。
这个场景里的关键经验是"数据验证技能不能省"。模型写的查询SQL未必总是正确的，execute之前先让validate_data技能跑一遍表结构校验和语法检查，能拦截掉大部分低级错误。分析结果出来之后，visualize_chart技能会判断应该画线图还是柱状图，然后生成对应的绘图代码。最后generate_insight技能把数据和图表转成人话，用户看到的就是一份完整报告。这个链路上每个环节都可插拔，替换分析引擎或者图表库都只改对应技能内部逻辑，其他技能完全不用动。
5.3 技能扩展的边界与取舍
技能化思路好用，但也不是越细越好。技能粒度过小会带来两个问题：一是模型要做更多次决策，累计的决策失误概率更高；二是执行链路过长，单次任务的时延和成本都会上升。以我的经验，一个技能对应一次"可以独立交付的价值动作"是最合适的。查询一次数据库、发一封邮件、生成一张图表，这种粒度刚好；而"写文章"这种包含选题、大纲、初稿、润色多个阶段的任务，就应该拆成多个技能并由编排层串联，而不是做成一个大而全的"写作技能"。
扩展边界还要考虑技能的复用频率。如果一个技能只在一个项目的某个特殊流程里用到一次，那它可能不值得技能化，直接写死在流程里反而更简单。技能化的价值在于复用和组合，一个技能被两个以上场景使用，这套抽象才有意义。我给自己定的标准是：一个新能力至少要经历两次"本来想硬编码但发现多个场景要复用"的时刻，才值得正式注册成技能。
说实话，agent-skills这个项目我断断续续迭代了大半年，最深的体感是：Agent开发的复杂度根本不在模型接入，而在于怎么把真实世界里的操作变成模型能够理解并可靠执行的原子动作。技能化是我目前找到的、兼顾灵活性和稳定性的最佳解。每次要给Agent加一个新能力，我只需要写一个技能、注册进去、测试通过，剩下的事情就交给Agent自己临场发挥。这套体系真正沉淀下来之后，团队里每个人都能往技能库里贡献新技能，Agent的能力边界就被一起推着往前走，而不是某个人在Prompt里反复打补丁。如果你也在为Agent的工具接入和管理头疼，照着这个思路搭一套技能框架，应该能少走不少弯路。
