前阵子做AI Agent落地项目，又遇到了一个典型问题：底层模型已经换到目前能用的最强版本，还是频繁在处理多步任务时"断片"。一会儿把昨天的日期算错，一会儿对着一个需要登录的后台页面反复尝试无效操作。团队成员都开始怀疑模型能力不够。后来我把这几个月反复试错的经验总结了一下，问题根源不在模型的"智力"，而在我们根本没给Agent一套可复用的agent-skills体系。模型再聪明，没有一个结构化的技能库，它也只能靠"现场编"去应对真实任务，出错是必然的。
这篇文章想把我在技能定义、路由调度、执行链路、失败恢复这几个方向上的实战经验完整摊开来聊。适合正在做Agent应用、被多步任务稳定性搞得头疼的开发者，也适合想从单点Demo走向真实业务的团队参考。
1. 为什么"提示词堆叠"撑不起Agent的能力天花板
1.1 一个真实任务让System Prompt全面失控
团队原来接需求的方式很原始：把业务流程描述直接塞进System Prompt。比如客户提了个需求"每天定时检查所有未完结工单，超过48小时没有新进展的，给相关负责人发一封催促邮件，同时更新到项目看板里"。
看起来不难，Prompt也是这么写的。真跑起来全乱套：Agent把所有工单一次性捞了出来，几十个请求打到接口导致超时；邮件的措辞像是一个模板套出来的，每个客户收到的内容几乎一样；更新看板这个动作时，Agent又在犹豫该用哪个字段，把状态值改错了。后来统计了一下，单次任务里光"理解业务规则"就消耗了将近一半的上下文窗口，留给真正判断和决策的空间所剩无几。
加大模型上下文没用。问题在于：Prompt是描述性的，不是可执行的结构。它的值是提供一个总体方向，但没法约束每一步动作的边界、参数和行为规范。Agent面对开放性指令时，每次都会重新"即兴发挥"，同样的任务跑十次，过程十次不同，结果自然时好时坏。
1.2 技能的本质：策略与工具之间的中间层
我最后的落地方案，借鉴了PC操作系统里"快捷键"和现代IDE里的"代码片段"思路：把高频、可复用的原子动作，固化成一个个命名清晰、边界明确的技能（Skill）。每个技能自带一份完整说明——什么时候该用、输入什么、输出什么、内部走什么流程、哪些情况要拒绝执行。
这样一改，Agent的职责从"从头到尾编流程"变成了"从技能库里选技能、排顺序、填参数"。我常跟同事用一个比喻解释这个变化：把Agent当成一个乐手，底层模型是指法和视奏能力，技能库则是提前练好的乐谱片段。临场发挥偶尔能出一两个华彩，但稳定撑起整场演出的一定是反复排练过的乐段。
周围常见的做法是把这些逻辑做成"工具函数"或者"工作流节点"，各有各的问题。裸工具函数只暴露一个个接口，没有使用场景的语义约束；重工作流把执行顺序写死，等于把判断权全部收回，Agent灵活度尽失。Skill取向刚好在两者之间：保有判断空间，同时用结构化的说明把自由度框在安全边界里。
1.3 技能、function calling和MCP的边界如何划分
再往细了说，工程上还有个绕不开的问题：Agent技能和OpenAI的function calling、Anthropic的tool use、以及现在很火的MCP（Model Context Protocol）到底什么关系。
以我在实际项目里的感受，这些不是同一个层次的东西，可以共存，但分工不一样。MCP解决的是"Agent怎么连接到外部数据源和系统"，类似于给Agent接上了USB-C接口，什么设备插上都能通讯；function calling解决的是"模型怎么按结构输出参数调用本地函数"，属于一次对话内的短链路交互。而Skill是更高层的"编排单元"——一个Skill内部可能调用多个MCP连接的资源，也可能组合若干次function calling，甚至嵌套其他Skill。
打个比方：MCP是水管网，function calling是阀门，Agent Skills才是整套供水方案。只通水管不设计方案，水压再大也浇不对地方。这个理解直接影响了我们后面的技术选型：在技能内部我们保留了function calling的GPU级效率，在外部连接数据源才走MCP，中间层则完全由Skills接管。把这三者的边界划清了，架构才不会越用越乱。
2. 技能仓库的目录结构与Schema设计：动手之前先把边界想清楚
2.1 一套可用的技能目录长什么样
Skill的大致实现形式，业内已有一些共识：每个技能就是一个独立的目录，里面包含说明文件和可执行文件。我的目录结构是基于实践反复调整过的，现在基本稳定成这样：
agent-skills/ registry/ calendar/ SKILL.md dependencies/ requirements.txt scripts/ get_datetime.py get_weekday.py web_search/ SKILL.md dependencies/ scripts/ search_and_extract.py customer_followup/ SKILL.md dependencies/ scripts/ list_overdue_tickets.py send_reminder_email.py update_kanban.py shared/ logger.py http_client.py validators.py这里有个容易忽略的关键设计：每个技能目录里必须有一个统一格式的SKILL.md，它会成为Agent决定"要不要调用这个技能"的主要依据。不要把说明散落在代码注释里，Agent读注释成本太高，还容易漏。
SKILL.md我一般固定为这几个段落：技能目标、触发条件、输入参数、输出格式、使用边界、失败处理、示例。触发条件和使用边界这两段通常是团队最不爱写的，却是排错时的救命稻草。
2.2 技能描述里的"触发条件"是路由成败的关键
我在实际踩坑中发现，Agent选错技能，八成是触发条件写得不够"可判定"。
一开始我们写触发条件喜欢用自然语言，比如"当用户想了解某个领域的信息时"，这种描述等于没写。模型怎么理解"想了解"？边界太模糊，于是它经常在"应该调搜索技能"的时候调了"网页解析技能"，或者在需要做"定时提醒"的时候调了"日历查询"。
后来我把触发条件改成"可枚举、可判定"的清单形式：
- 明确动词列表：查询、获取、设置、创建、删除、提醒、汇总……技能只对明确动词响应。
- 实体/对象约束：涉及哪些类型的对象（工单、邮件、日历、网页URL），与对象无关绝不响应。
- 否定条件：哪些情况明确不处理，比如"仅查询不修改""不涉及发送邮件""仅处理当前登录账号的数据"。
- 示例语句：放2到3个真实用户输入示例，帮助模型做类比判断。
这样改动之后，技能选型准确率肉眼可见地上升。因为模型做意图判断时，本质是在有限选项里做"匹配"而不是开放式"理解"，你给的匹配条件越具体，它匹配得就越准。
2.3 技能命名与粒度：从"日期查询"到"营销流程"的拆解
技能粒度是个要反复拿捏的事情。粒度太粗，一个技能内部什么都要做，出错时你根本不知道是哪个环节的问题；粒度太细，技能数量爆炸，Agent选技能的时间比干活时间还长。
我们内部有一个不成文的判断标准：一个技能应该只完成"一个不可再拆的业务目标"，它的内部步骤确实可以多，但对外的目标必须单一。
拿邮件相关功能举例，我把它拆成了三个独立的技能：
| 技能名称 | 职责范围 | 不做什么 |
|---|---|---|
| 工单逾期检测 | 从系统拉取所有未完结工单，计算停滞时长，返回逾期列表 | 不发邮件、不改工单状态 |
| 邮件内容生成 | 基于工单信息和沟通记录，生成个性化催办邮件正文 | 不调用邮箱API发送 |
| 邮件发送与状态回写 | 把生成的邮件发出，并把发送状态和日期回写到工单记录 | 不负责内容创作 |
而"完整催办流程"这个粗粒度目标，我放在上层编排层去串联这三个技能，而不是把它们揉成一个"营销流程"大技能。一个技能一个目标，一个目标一个入口，这是技能库不失控的基础。
3. 把技能组装进Agent：路由、注册与执行链路
3.1 注册表决定了Agent能看到哪些技能
技能定义好了，下一步是让Agent在运行时"看得到"它们。这里不是简单地给模型塞一堆文档，而是要建一个注册表（Registry），把技能元数据集中管理。
注册表我设计成了这样的数据结构：
{ "skills": [ { "name": "工单逾期检测", "version": "1.2.0", "description": "扫描未完结工单并计算停滞时长", "triggers": ["扫描工单", "检查逾期", "停滞"), "input_schema": { "type": "object", "properties": { "max_days": {"type": "integer", "minimum": 1}, "assignee": {"type": "string", "description": "按负责人过滤，可选"} }, "required": ["max_days"] }, "output_schema": { "type": "array", "items": {"$ref": "#/definitions/ticket"} }, "entrypoint": "skill://工单逾期检测", "dependencies": ["shared:http_client", "shared:logger"], "tags": ["工单", "通知", "业务"] } ] }把schema直接暴露给模型，比自己写一段描述有效得多。模型对输入输出的结构理解是"强类型"的，有清晰定义时，它填参数很少再出现类型错乱。注册表还负责版本管理和依赖解析，这个后面4.4会细讲。
3.2 意图路由：不能只靠大模型的"感觉"
路由层的设计我踩过两次坑：第一次想完全靠大模型做意图判断，结果技能库超过30个之后，模型开始频繁在相似技能之间犹豫，响应延迟变高，触发选择也开始左摇右摆；第二次想走极端，把所有路由逻辑写成硬判断，效果倒是稳定了，但新场景一来，代码就要跟着改，维护成本直线上升。
现在采用的是**"规则预筛 + 模型精排"的双层路由**：
- 规则预筛（第一层）：用关键词、正则和实体识别先把匹配范围收窄到3到5个候选技能。这一步不花LLM的token，开销极小，响应快。
- 模型精排（第二层）：把候选技能的SKILL.md精简版（目标、触发条件、输入输出）交给模型，让它从中选出最合适的，或者给出"无可匹配"。
这套双层的核心逻辑很简单：让规则做它擅长的事（快速收窄），让模型做模型擅长的事（在模糊语境下做语义判断）。目前我们的生产环境里，第一层能杀掉70%的错误匹配，第二层的准确率在90%以上，整体路由准确率比纯模型方案高出不少，调用成本也下了几个点。
3.3 执行链路：预检、执行、验证与回滚
技能被选中后，不能直接开跑。我在执行环节加了三道关卡，每一道都拦过实际事故：
预检（Pre-check）：在技能真的动手之前，先校验参数是否完整、依赖的第三方服务是否可达、当前账号有没有权限。比如"发送邮件"技能，预检阶段就会检查SMTP服务是否健康、发件人邮箱是否认证通过。预检没过，直接返回错误说明，不要等到邮件发一半才发现认证过期。
执行与验证（Execute & Verify）：技能执行完毕后，不是立刻告诉Agent"成功了"，而是按SKILL.md里的验证规则做一致性检查。比如更新工单状态后，重新查一遍这个工单，确认status和owner字段确实变了。验证规则要和业务强相关，宁可多查一次接口，也不要带着错误结果继续往下走。
回滚事务性操作（Rollback）：如果技能链中间某一步失败，而之前几步已经产生了写操作（比如邮件已发出、状态已改），必须有对应的补偿机制。我们在每个技能描述里都加了一个"undo_mode"字段，标明这项操作可不可逆、能不能补偿。可补偿的自动做逆向操作，不可补偿的至少要在日志里明确标记出来，避免后面流程做出错误假设。
执行链路完整下来，一个技能调用大致是这个状态机：
技能被选中 -> 参数校验 -> 预检通过 -> 执行 -> 内部验证 |-> 验证通过 -> 完成 |-> 验证失败 -> 补偿/回滚 -> 标记错误 -> 预检失败 -> 返回错误+修复建议4. 三个典型技能的完整落地过程
这里挑三个我在项目中实际落地过的技能走完整流程，覆盖了三种典型类型：纯计算型、外部数据获取型、多步骤操作型。
4.1 技能一：日期时间计算
典型的需求场景：用户问"下周三下午三点是哪一天"或者"这个月最后一天是几号"，看似简单，但直接让模型心算极容易出错。
SKILL.md关键部分：
## skill: 日期时间计算 ### 目标 把自然语言里的日期时间表达，解析并转换成具体的日期/时间对象。 ### 触发条件 - 用户输入包含"下周三""本周五""月底""三天后"等相对时间表达 - 用户输入包含"几号""周几""什么时间"等查询词 ### 输入参数 - text: 用户的原始自然语言表达 ### 输出 - iso_datetime: 标准ISO格式的时间戳 - weekday: 星期几 - timezone: 时区 ### 使用边界 - 仅负责时间计算，不负责设置提醒 - 遇到"去年某月"等需要额外上下文的情况，返回错误并说明需要哪个基准日期 ### 失败处理 - 解析失败时，返回已知的时间参照点（当天零点）和未能解析的片段，便于上层追问核心脚本片段（Python）：
import datetime from dateutil import parser import re def parse_relative_time(text: str, reference: datetime.datetime = None): if reference is None: reference = datetime.datetime.now() # 先处理绝对时间 try: return parser.parse(text, fuzzy=True) except: pass # 处理"下周三""本周五"这类相对表达 weekdays = {"周一": 0, "周二": 1, "周三": 2, "周四": 3, "周五": 4, "周六": 5, "周日": 6} m = re.search(r"([下上这])(周|星期|礼拜)([一二三四五六日天])", text) if m: direction = m.group(1) weekday = weekdays[m.group(3)] days_ahead = (weekday - reference.weekday()) % 7 if direction == "这": date = reference + datetime.timedelta(days=days_ahead) elif direction == "下": date = reference + datetime.timedelta(days=days_ahead + 7) elif direction == "上": date = reference - datetime.timedelta(days=7 - days_ahead) return date.replace(hour=0, minute=0, second=0, microsecond=0) raise ValueError(f"无法解析的时间表达: {text}")这个技能的踩坑点出现在时区和基准时间上。一开始我没强制要求外部传入reference时间，结果Agent在运行时会用"当前时间"的语义去猜，部署到不同时区的服务器后出现了几小时的偏差。后来改成：基准时间必须由调用方显式传入，并且统一转成UTC+8，才算彻底稳定。
4.2 技能二：搜索结果结构化提取
这个技能解决的是"上网查资料但结果杂乱"的问题。Agent不能自己去翻几十个网页，它需要一个技能能搜索、抓取指定网页内容，并按Schema返回结构化结果。
设计思路：
- 输入：查询关键词或URL列表、提取规则（要哪些字段）
- 输出：JSON数组，每项包含来源URL、标题、正文摘要、字段值
- 边界：不访问需要登录的站点；对疑似敏感内容直接报"无法访问"
实际代码里，我用了异步HTTP客户端并发抓取多个URL，超时控制在5秒，提取规则用XPath + CSS选择器混合。这块有一个很实用的经验：不要指望通用爬虫拿到什么有用内容。真实输入是五花八门的页面结构，所以我在技能内部做了一个"通用提取 + 规则覆盖"机制——先用通用算法抽取正文，如果调用方提供了具体字段规则，就按规则重新抽取并覆盖。
一个具体的调用示例，比如要求"整理这三家公司的创始人、成立年份、总部所在城市"，输出会是：
[ { "company": "示例科技", "url": "https://example.com/about", "extracted": { "founder": "王某", "founded_year": "2018", "headquarters": "杭州" }, "confidence": 0.92 } ]每个字段带置信度是个隐藏的好设计。后续决策可以优先采用高置信度的数据，低置信度的让Agent给人看原始片段，而不是直接当作事实用。
4.3 技能三：工单逾期检测与催办执行
这个技能串起了前面的拆分思想，再说说它内部的完整执行流程。它被设计为三个独立技能的"上层调用链"，但实际SKILL.md里只暴露一个聚合入口，方便Agent看到的是"一件事"。
执行链路：
工单逾期检测技能扫描所有未完结工单：
- 查询条件：status != completed且updated_at早于当前时间-48小时
- 每个工单计算停滞时长，按剩余响应时间排序
- 返回逾期列表（工单ID、客户、负责人、停滞时长、最后动态）
邮件内容生成技能逐个工单生成催办正文：
- 获取工单的最近3条沟通记录
- 按不同停滞时长匹配语气模板（24小时/48小时/超过5天）
- 生成结果同时包含人类可读的HTML正文和纯文本备选
邮件发送与状态回写技能负责发送并把结果登记回工单：
- 发送前再次检查收件人邮箱格式，避免无效地址
- 发送成功后在工单的
last_followup_at字段写入时间戳 - 如果发送失败，把失败原因和工单ID写到一个专门的失败队列
整个链路的成功关键在于第二和第三技能的彻底解耦：内容生成不管发不发得出去，发送技能也不管内容怎么写的。这样出错定位清晰——第三技能报错，必然是发送环节的问题，绝不可能因为邮件文案写得不好而怪到发送技能头上。
5. 实测踩坑：技能切割粒度、描述歧义与失败路径调试
5.1 "什么都能干"的技能最容易翻车
我们最早也图省事，把日期、日历、提醒、日程安排全做进一个"time_manager"技能。结果Agent只要一提时间相关字眼，就全往这个技能上靠。它内部有十几个不同的入口函数，每天的分发逻辑越来越复杂，更新一个入口就要动整个技能，测试用例翻了倍，最后还是出问题。
拆完之后我的体会是：技能粒度宁小勿大，拆错了可以合并，做成大杂烩再拆分则伤筋动骨。判据还是那个：你能否用一句话说清楚这个技能"不可再拆的唯一目标"？能说清楚就继续看，说不清楚就是该拆的信号。
5.2 描述里的模糊动词让Agent在边缘反复试探
前面提到触发条件要可判定，这里展开说一个具体例子。我们在"网页内容提取"技能描述里写过"分析"这个词，Agent就会把"总结这篇文章""提取文中的观点"这类语义模糊的任务也路由过来。实际技能只能做HTML抽取，根本做不了语义总结，于是返回一堆原样HTML，用户体验极差。
修复办法是把描述动词全部收敛成操作性的词：抓取、解析、校验、格式化、提取、生成、发送、更新。描述里出现任何"分析、理解、判断、评估"这类认知动词，先反思是不是把不该封装的能力封装进来了。这背后的原因很直接：技能系统不是给Agent发展思维能力用的，而是给确定性任务提供确定性的执行路径。
5.3 失败路径比成功路径更值得先测
这是我们团队踩得最深的一个坑。最开始所有技能的验收标准都是"正常输入跑通就算完成"，对失败路径想得少。上了生产环境一周，真实用户开始输入各种边界内容，问题集中爆发：
- 工单列表为空时，邮件内容生成技能还在傻乎乎地遍历空结果集
- 搜索技能遇到目标站点403，直接抛异常让整个任务中断
- 日期解析遇到"明天如果是周末就顺延到下周一"这种条件表达时，底层库解析失败
后来我定了一条死规矩：每个技能在验收时必须有专门的"失败路径测试矩阵"。至少覆盖：空输入、非法参数、目标服务不可用、权限不足、超时、部分成功。每个技能必须在SKILL.md的"失败处理"段说明这几种情况下的行为，Agent拿到错误提示才知道是重试还是放弃。
def run_with_failure_handling(skill_name, params, ctx): try: result = execute_skill(skill_name, params, ctx) except ServiceUnavailable as e: # 明确：是第三方服务挂了，与技能本身无关 return {"status": "retryable_error", "retry_after_seconds": 15, "message": f"服务暂不可用，建议稍后重试: {e}"} except PermissionDenied as e: # 权限问题不能重试，直接让Agent向用户请求新授权 return {"status": "fatal_error", "action": "request_permission", "message": f"缺少权限，请先完成授权: {e}"} except PartialSuccess as e: # 部分成功需要补偿逻辑 ctx.compensate(e.completed_items) return {"status": "partial_success_rolled_back", "message": e.message}5.4 技能版本的兼容问题
技能库大到一定程度，会面临"A技能依赖B技能的2.0版行为，但注册表里B已经升级到3.0"的问题。Agent在运行时如果拿到的是新版本行为，却按照旧版SKILL.md的理解去编排参数，很容易传错参数。
我的解决办法是在注册表里引入依赖锁定：每个技能声明自己依赖哪些共享模块和其他技能的哪个版本范围，升级时强制走语义化版本检查。同时，每个技能的SKILL.md文件头加一段metadata，包含依赖清单：
name: 工单逾期检测 version: 1.2.0 requires: shared/http_client: ">=2.1.0, <3.0.0" shared/logger: ">=1.0.0"这样做的效果是，升级依赖库时能提前发现哪些技能不兼容，而不是等Agent运行时才报错。团队里新来的同事改共享模块时，也能通过冲突提示少踩很多坑。
6. 从单体技能到技能生态：复用、共享与扩展方向
6.1 把技能库做成团队共享的"工具包"
技能库一旦成形，它就不再只是单个Agent的配置，而变成了团队内的资产。我现在鼓励组里的同学把日常处理任务的"确定性动作"沉淀成技能，放进一个统一仓库管理，类似npm私服的概念。技能写出来之后，别人拉下来就能用，但必须遵循同一套SKILL.md规范和目录结构。
这种共享模式带来的好处是隐性的"能力复用"：一个同学写好的"PDF表格提取"技能，其他Agent也都能直接调用，不用每个项目都从头写一遍。对一个团队而言，技能库的厚度比单次任务的成功率更值得关注——你积累的不是代码，而是被验证过的行为模式。
6.2 不同模型与技能之间的适配
还有一个现实问题需要提醒：技能描述和触发条件写得好不好，跟底层模型的能力是强相关的。同一个技能库，在Claude下的表现和在某轻量模型下的表现，差距可以拉得很大。轻量模型在依赖"语义判断"的场景里更容易翻车，解决办法是给不同模型配不同的路由策略——能力强的模型可以直接喂完整SKILL.md让它选技能，能力弱的模型需要更多的规则预筛兜底，甚至在候选技能只有2到3个时直接匹配关键词。
另一个实用适配方法：简化技能描述。技能描述写得再华丽，对弱小模型的帮助也有限，反而挤占上下文。对轻量模型，我只保留触发词列表和输入输出schema，把冗长的"使用边界"换成一个精简的禁忌列表，实测效果比"原封不动喂全量描述"好很多。
6.3 我接下来的扩展计划
当前这套技能系统还有一个有意思的方向没有深入：技能自动生成。现在写技能基本靠我们手工维护，成本还是偏高。我在尝试让Agent基于一段失败的对话记录，自动抽取出"这里缺一个技能"的结论，然后生成技能骨架，再由人来验证修改。把这个流程跑通，技能库的进化速度会比现在快一个量级。
另一个方向是把技能的验证规则做成可插拔的"断言库"。现在每个技能内部都写了一套验证逻辑，很多是重复的，如果能把"字段是否变更""列表是否为空""调用是否超时"这些常见断言抽成公共模块，技能的代码量会显著下降，维护起来也更轻松。
最后说句实在话。Agent开发走到今天，模型的选择固然重要，但真正让产品能用起来、让用户愿意长期信任的，是那些被反复打磨、边界清楚、失败可控的技能模块。每次模型能力提升一个台阶，技能库都能无缝地跟着受益，而不用推翻重来——这就是我认为现阶段最值得投入的资产。如果你也在做Agent方向，建议从自己业务里最痛、最高频的那几个动作开始，先沉淀出五个像样的技能，很快你就能体会到这套思路和"塞Prompt"之间的天壤之别。
