很多人在做AI Agent时一开始都会觉得“只要把Prompt写长一点、写详细一点模型就能干好活”。我早期也是这么干的结果项目越做越重一个系统提示词里塞了几十条业务规则、十几种操作指令模型开始频繁“精神分裂”该调用的工具不调用不该触发的逻辑疯狂触发。后来我把思路彻底换了一遍——把所有能力拆成独立的“技能”skills让Agent按需选择、动态加载项目结构一下就清爽了。这篇文章就围绕 agent-skills 这个方向聊聊我最近一套实践的完整思考技能到底是什么、怎么设计边界、怎么注册调用、怎么避坑以及如何持续维护一套能跟上业务变化的技能库。如果你正处在“AI应用原型能做出来、但往生产环境走总觉得乱糟糟”的阶段这篇内容应该能给你一些直接可抄的答案。1. 技能库为什么会成为Agent开发的新分水岭先说一个背景我接手过一个内部知识问答Agent最初需求很简单就是根据公司文档回答员工问题。结果三个月后这个Agent的Prompt膨胀到了两千多行里面塞了数据库查询规则、权限判断逻辑、工单创建流程、会议室预定方法……每次改需求都要在巨型Prompt里找半天该改哪一行模型输出还经常出幺蛾子。1.1 一个让系统变脆弱的典型开发路径这个Agent的“发疯”路径很有代表性大家可以对照一下自己的项目有没有同样苗头第一周Prompt只有五十行模型表现惊艳大家觉得AI太强了。第二个月业务方提了新需求开始在Prompt里追加条款两百行勉强还稳定。第三个月有用户反馈“查询权限判断错了”工程师不忍心动原有逻辑直接在Prompt最后加了一段“特殊规则”三百行开始偶尔出错。第四个月模型一会走新逻辑一会走旧逻辑没人说得清哪段Prompt生效哪段被覆盖。这种模式的本质问题在于——我们把所有“知识”和“行为”揉成了一团乱麻全部塞进上下文窗口。模型根本没有“组织能力”去分辨哪些规则适用于当前场景它只能靠概率去猜。1.2 技能化的本质把备忘录变成工具箱技能化Skills的思路和上面截然不同。它的本质是把Agent的能力从“一段长长的文字说明”拆成“一个个独立封装的工具模块”。每个技能就像一个工具箱里的独立工具扳手只管拧螺丝锤子只管敲钉子Agent接到任务时先判断“当前问题需要哪个工具”再只加载那一个技能去执行。这个转变看起来只是工程组织方式变了实际影响非常大。首先是上下文窗口的压力骤降——不用再把两千行规则全部塞进去只要加载当前任务相关的那几百行。其次是行为可预期性大幅提升——每个技能的触发条件、输入输出、失败处理都是独立定义的模型不需要在一堆互相干扰的规则里做判断。1.3 哪些场景最需要技能化从我的经验看下面这几类场景一旦业务复杂起来几乎必然要走向技能化工具数量超过十个的Agent工具一多模型选错的概率指数级上升技能化的过程会强迫你对每个工具做更清晰的边界定义。规则之间存在条件冲突的业务比如“普通员工不能查薪资数据但HR可以”这种逻辑塞在Prompt里很容易翻车做成独立的权限校验技能反而干净。同一套底座要服务多个场景同一个大模型底座要同时支撑客服、内部问答、数据分析不可能共享一份巨型Prompt。2. Skill的定义边界、粒度与命名规范很多人的第一个问题是Skill和普通Function Calling里的Function、和工作流Workflow有什么区别我的理解很简单——它们是不同抽象层次的东西。2.1 技能与函数、工具、工作流的边界从下往上分大概是这样一个层次关系函数Function最细粒度的能力单元比如“调用某个API”“执行一段Python脚本”。一个函数只做一件事没有任何业务判断。工具Tool通常是对一个或多个函数的封装例如“查天气”“发邮件”。工具开始有了一点业务语义但仍然是通用能力。技能Skill面向某个完整任务场景的组合能力通常包含多个步骤可能协调多个工具并且带有自己的决策逻辑和异常处理策略。比如“安排会议”这个技能涉及查参会人忙闲、定会议室、发邀请、生成日历事件还要处理“大家忙不过来的候补方案”。工作流Workflow更高层的流程编排把多个技能串成一条流水线通常有固定的前后依赖关系。所以设计技能的时候我的第一个判断标准是这个能力是否足够“任务完整”。它应该能独立解决一个用户会直接提出的诉求而不是一个碎到不能再碎的步骤。比如“调用搜索API”不是技能“搜索并整理相关资料的摘要”才是技能。2.2 粒度设计一个技能该多大粒度太大技能内部会重新变成一个小型“屎山”丧失可维护性粒度太小Agent光选技能就要选半天上下文里塞满不相关的技能描述。我个人的经验是拿“一个正常人需要通过几轮对话完成的一件事”作为粒度参考。举几个例子技能名称任务描述是否适合做独立技能查询员工联系方式输入姓名返回邮箱和分机号适合任务完整且高频解析身份证号中的生日输入身份证输出生日字段不适合太细直接做函数就行生成周报草稿汇总本周任务数据按模板生成周报适合典型完整任务回复客户投诉邮件分析情绪、查对应政策、起草回复适合这是复合任务计算两个日期之间的天数纯数学逻辑无业务语义不适合归入通用工具2.3 命名与描述里的沟通成本Skill的命名和描述直接决定了模型能不能正确调用它。这里有一个常被忽略的事实——Skill描述不是写给用户看的是写给大模型看的。模型通过你的描述来理解“这个技能什么时候该用”“什么时候不该用”所以描述里最忌讳的就是含糊。举个例子同样是“查询知识库”这个技能两种描述方式模糊版“查询系统里的知识内容返回相关结果。”清晰版“查询公司内部知识库Wiki中的文档内容。适合回答关于公司制度、IT运维指引、人事流程等内部政策问题。仅用于公司已收录的文档不用于联网搜索外部信息。如果用户要查新闻、股市、天气等外部信息请使用其他技能不要调用本技能。”后者明确了适用范围还主动声明了“什么情况下不要用”这个负向排除项非常有价值能显著降低模型误调用的概率。3. 技能注册与调度的核心机制有了技能定义下一步就是如何让Agent“知道”这些技能、并能正确选择调用。这块做得不好前面所有设计都会打折扣。3.1 两种注册方式的取舍目前主流的技能注册方式有两大类静态注册和动态发现。静态注册就是启动时把所有技能信息名字描述参数Schema全部塞进系统提示词或函数的声明列表里模型每次请求时都能看到所有选项。优点是实现简单、稳定缺点是技能一多光技能描述就要占掉几千个Token而且模型面对一堆无关技能时更容易选错。动态发现则是先让模型进行一次“技能路由”——只给它传所有技能的名字和一句话摘要让它判断当前任务可能需要哪些技能然后把命中的详细描述和参数Schema再注入进来。这样上下文占用小准确率也更高。我的项目采用的是折中方案先把技能按领域分组比如“人事相关”“技术运维相关”“数据查询相关”每个组有一个组级描述模型先选组再在组内选技能。实测下来比全量列表的效果好很多。3.2 让模型选对技能的关键描述质量模型选错技能大部分时候不是模型笨是描述写得烂。一个几百块钱Token就能解决的问题不要去怪模型。总结一下我写技能描述时必带的四要素技能目标一句话说清这个技能是干什么的。输入要求需要哪些类型的参数比如“需要用户提供的员工姓名或工号”。输出形式返回的内容长什么样。限制与排除明确说“什么情况不要用我”比如涉及外部实时数据就别用内部知识库技能。这里我踩过一个具体坑训练过一个“工单查询”技能描述里只写了“查询工单状态”结果模型在用户问“我提的报销单到哪一步了”时也去调这个技能。后来我在描述里加了一句“本技能仅查询IT故障类工单状态报销单属于财务流程请调用报销查询技能”误调用率立刻从接近三成降到了很低。3.3 参数校验与容错设计模型生成的参数经常不按Schema来——明明定义好了类型它还是会传字符串进去。所以技能内部必须有自己的参数校验层不能信任外部传进来的任何东西。我习惯在每个技能入口先做三件事类型检查要求integer绝不接受“3”和“3.0”混在一起。枚举值校验对有限的取值在入口就blacklist/whitelist过滤掉。业务预检比如查询工单前先确认用户有没有权限这个检查放技能内部比放外部好因为只有技能自己最清楚需要什么前置条件。4. 一套可落地的技能目录设计文件结构、加载逻辑与实例讲完了理论大家肯定更想知道落地的长什么样。我这里公开一套我在中型项目里用得很顺手的技能目录设计。4.1 文件结构与目录规划我倾向于把每个技能做成一个独立的模块而不是攒一个巨型文件。基本结构长这样skills/ ├── common/ │ ├── date_utils.py # 通用日期处理 │ ├── auth_check.py # 通用权限校验 │ └── llm_client.py # 模型调用客户端封装 ├── hr/ │ ├── employee_info/ │ │ ├── skill.json # 技能描述与参数Schema │ │ ├── run.py # 技能主逻辑 │ │ └── prompts.py # 内部使用的Prompt模板 │ ├── leave_apply/ │ │ ├── skill.json │ │ ├── run.py │ │ └── prompts.py │ └── org_structure/ │ ├── skill.json │ ├── run.py │ └── prompts.py ├── ops/ │ ├── incident_query/ │ │ ├── skill.json │ │ ├── run.py │ │ └── prompts.py │ └── service_restart/ │ ├── skill.json │ ├── run.py │ └── prompts.py └── registry.py # 技能注册中心扫描目录自动加载每个技能目录自包含技能之间的调用通过统一的接口完成不直接互相import内部函数。这样做的最大好处是一个技能挂了不影响其他技能新增技能也不要去改老代码。4.2 带上手实例一个会议纪要助手的技能下面用“会议纪要助手”这个技能把一个完整流程串起来。需求很简单用户丢一段会议的录音转写文本技能要提取决议、待办事项、负责人和截止日期并按模板输出。skill.json里的关键内容{ name: meeting_minutes_assistant, version: 1.2.0, description: 从会议录音转写文本中提取结构化会议纪要输出包括会议主题、参会人、决议事项、待办任务及负责人与截止日期。适用于内部项目例会、周会、跨部门协调会。不适用于电话录音、视频内容的字幕提取等非转写文本输入。, parameters: { type: object, properties: { transcript_text: { type: string, description: 会议录音转写得到的纯文本内容 }, meeting_type: { type: string, enum: [project, weekly, cross_team], description: 会议类型项目例会、周会、跨部门协调会 } }, required: [transcript_text] }, output: { type: object, properties: { summary: {type: string}, decisions: {type: array}, action_items: {type: array} } } }run.py的核心逻辑包括三部分先检查文本长度是否在合理范围内太长就先做分段摘要再调用LLM按内置的prompts.py模板做结构化抽取最后做一个简单的“待办校验”——把提取出的每个待办事项和负责人字段做一次非空检查是空的就抛个友好错误不硬着头皮下发。这个技能设计里最关键的一点我在parameters里设计了一个meeting_type枚举而不是让模型自由发挥。因为不同会议类型的提取侧重点差别很大——周会要重点列本周完成和下周计划跨部门会要重点标注“卡点”和“责任人”做成枚举后模型的选择负担小很多输出也更稳定。4.3 跨平台迁移的兼容性考虑如果你的技能要同时跑在多个Agent平台比如自己的API服务、某个开源Agent框架、某个商业化平台我有个很重要的建议把技能描述和技能执行逻辑分离。什么意思描述文件如skill.json尽量保持通用用团队自定义的Schema而执行层做一层薄薄的适配器把不同平台的调用格式转换成自己的标准格式。我见过太多项目被平台绑死想迁到另一个框架时所有技能重写一遍那个痛苦真的没必要。适配层只写一次后续换平台半小时搞定。5. 我在实战中踩过的技能坑三个典型问题的完整排查链路任何一个做Agent开发的人都不可能绕过“技能出错”这道坎。我把实战中踩过且特别有代表性的三个坑拿出来还原完整的排查过程而不是直接给结论。5.1 技能描述误导相似技能的甄别问题现象系统有两个技能——“查询工单状态”和“查询报销进度”。最初模型老是搞混用户问报销单走到哪了模型去调工单查询技能返回一堆无关数据。排查过程我先去查了模型实际生成的function call记录确认它不是偶发而是每次遇到“查询进度”类问题就选择工单技能。然后我对比了两个技能的描述发现问题很清楚——“查询工单状态”的描述里写着“查询处理进度”而报销技能的描述里写了“查询报销进度”模型对“进度”这个词太敏感直接匹配到第一个技能。修复给每个技能描述加了非常明确的“适用对象”和“排除对象”查询工单状态仅适用于IT故障类工单如网络、设备、软件报障不适合查询报销、请假、采购等其他流程进度。这一句话带来的准确率提升比换模型版本还明显。5.2 隐藏依赖环境上下文缺失导致的连锁失败现象某一次发布后“生成周报”技能开始间歇性失败但错误信息很奇怪不是参数错误而是“找不到用户”。排查过程我先看技能日志发现它的第一步是调用“获取用户信息”工具而这个工具依赖一个外部Session上下文。新发布时我们改了上下文传递逻辑技能内部拿不到userId了。但问题最隐蔽的地方在于技能内部对这个“缺少用户”的情况没有处理直接抛错拿不到任何提示“是权限问题还是参数问题”。修复在技能入口统一加了上下文校验缺用户信息时返回明确错误“缺少用户身份信息请先完成登录校验”而不是让下层工具抛一个裸异常。这之后任何技能出了问题看一眼错误信息就能定位到是哪一层断的。经验技能不是独立存在的它对上下文、前置工具、外部服务都是有依赖的。设计时必须明确“这个技能在什么前置条件下才可运行”并在入口处做防御性校验。5.3 冷启动与回归测试技能也需要持续维护现象两个版本之间没有任何代码变化但某个技能的输出质量突然下降。排查过程分析一通后发现问题出在大模型版本升级上——底模升级后模型对某个技能描述的理解方式变了原本能正确触发的路径不再走了。Agent系统从来不是“写一次就完事”大模型在迭代、业务在变技能描述也需要持续适配。修复我给每个技能建立了一套轻量级回归测试集每次改技能描述、参数Schema或升级模型都要跑一遍。测试集不用很大每个技能准备5到8条典型输入重点覆盖边界场景和易混淆场景就行。跑一次全量不到两分钟但节省的线上排查时间远超这个投入。6. 技能的度量与后续优化方向如何用数据而不是感觉迭代技能这东西容易“感觉很好”但经不起数据检验。我现在每个技能都做了埋点关注三个核心指标6.1 用三个指标量化技能使用效果触发准确率模型调用了某个技能这个调用里有多少比例是正确的这个指标衡量“技能描述是否清晰”。执行成功率触发之后技能内部逻辑有多少比例能顺利跑通这个指标衡量“技能工程实现是否健壮”。用户解决率用户后续是否还会追问同一个问题如果技能执行成功但用户依然追问说明技能的输出模板没命中用户真实需求。这三个指标从“选择是否对”“执行是否通”“结果是否有用”三个层次把技能状态照得清清楚楚。拿数据说话就非常容易确定下一步该优化谁。6.2 一个反直觉的反思技能是否应该让模型自己生成圈子里的另一个讨论热点是“Self-Discover”“Auto Skill Generation”之类——让大模型自主生成新技能而不是靠人来写。我做过实验的结论比较冷静模型确实能生成粗粒度的技能原型尤其在数据分析、报告生成这一类任务上模型自己生成的初版甚至在Prompt设计上比人更精细。但它一旦涉及具体业务规则权限边界、数据来源、合规条件生成的技能没法自动理解这些约束还是需要工程师把业务规则补进去。所以我的态度是把“技能生成”当做一个提效工具来用让模型产出初稿人工审核补充业务约束而不是让它完全自治。完全自治在现在这个阶段只能出现在玩具项目里生产环境还是要人来兜底。6.3 给同样在做技能化改造的同学一点个人体会最后说点经验层面的东西。技能化改造这件事最难的不是写代码是“忍住别什么都往一个技能里塞”。我发现项目里维护得最差的技能往往是那个“看起来啥都能干”的大杂烩技能——搜索、问答、推荐、计算它都管最后模型根本搞不清楚它的真实边界。我自己后来的原则极其简单一个技能一条任务线一套明确的输入输出。用户问A问题绝不让技能B来回答技能B答不了就直接说不合适而不是硬着头皮生成一段错误结果。因此如果你正筹备着把Agent能力拆开重组建议也从最小、最独立的技能开始试水跑通了再加复杂度。技能库的演化是一个持续打磨的过程但每打磨好一个技能整个系统就会更稳一分。这套投入到了后期会以“少救火”的形式成倍回报给你。