开头直接进入状态，像在技术社区分享个人经验的语气，围绕“agent-skills”这个标题展开：大模型Agent的技能体系设计、拆解、实现和调试。
1. 为什么我说“agent-skills”不只是写几个函数
我见过不少团队做智能体，最初的形态都是“一个主程序 + 一堆prompt模板”，遇到什么任务就往LLM里塞一段提示词。这种做法在Demo阶段没问题，但一旦任务变多、逻辑变复杂，提示词之间互相干扰，参数越来越难调，你根本说不清楚某个功能是谁在什么时候触发的，更别说让多个Agent协作。后来我意识到，真正该做的是把“模型能力”沉淀成“技能”，也就是把Agent可执行的原子操作整理成一个结构化、可注册、可发现、可组合的“技能层”。这就是我项目标题命名为“agent-skills”的原因。
技能层的核心价值，不是把代码封装成类那么简单，而是给大模型一张看得懂、能决策、敢调用的“菜单”。模型本身的强项是语义理解和任务分解，弱项是精确计算、稳定执行和跨环境操作。技能层正好补上这个短板：LLM负责判断“该做什么”，技能层负责“做成什么样、怎么做完”。如果你正在做Agent相关的工作，或者你准备给某个业务系统加入AI自动化能力，这篇内容会非常有参考价值。
2. 技能层怎么设计才不会被“模型乱调”
2.1 先把“技能”和“工具”区分开，这一步很多人搞反了
谈技能设计之前，我建议你先想清楚一个概念：工具（Tools）和技能（Skills）不是一回事。
工具是底层的能力接口，比如“执行Shell命令”“读取文件”“调用某API”。技能则是“为了完成一类有意义任务而编排好的能力单元”，它内部可以调用多个工具，也可以包含一些固定的决策逻辑。比如“从网页中抽取正文内容”是一个技能，它内部可能需要工具A（发起HTTP请求）、工具B（解析HTML）、工具C（清理模板噪声），甚至还需要一个小分类模型判断正文区块。
为什么要做这个区分？因为模型的上下文长度有限，如果所有底层工具一股脑塞给模型，模型会陷入选择困难，决策质量直线下降。技能层做了一道抽象：模型只看到“从网页中抽取正文”这个语义明确的技能，而不需要关心底层到底用了什么工具。这样不仅减少了上下文占用，也降低了模型误用工具的几率。
我拿自己实际调过的例子来对比：
| 设计方式 | 模型看到的接口 | 实际效果 |
|---|---|---|
| 直接暴露底层工具 | read_file, execute_command, http_request, html_parse, extract_text... | 模型经常选错工具，尤其在任务边界模糊时；上下文被大量接口说明占用；排错靠猜 |
| 暴露技能层 | extract_web_article, analyze_sentiment, generate_report... | 决策路径清晰，模型更容易选出正确技能；技能内部行为可控；新增能力不用改主流程 |
这只是第一层切分。真正困难的是技能粒度的选择，我下一小节展开。
2.2 技能粒度定多细，决定你后半夜会不会被叫起来修复
技能粒度这个事，没有标准答案，但有一个非常实用的判断原则：以“语义完整性”为边界，而不是以“代码重复度”为边界。
说得直白一点，如果某个操作单独拿出来，能够回答用户一个完整的问题或者完成一个有意义的步骤，那它就够格成为一个技能。比如“查询今日天气”“把长文本拆成摘要要点”“检查代码风格并自动修复”“从简历里抽取候选人技能标签”，这些都是完整的技能。反过来，如果某个操作只是技能内部的一小环，比如“把字符串转成MD5”“请求某个接口并解析JSON”，这些不应该是技能，它们应该作为技能内部的底层函数。
粒度太粗的问题很明显：技能内部逻辑过于庞杂，复用性差，模型执行时一旦中间步骤出错，你没法精确控制哪一部分需要重试。比如“自动完成股票分析并用邮件发送结果”这个技能，看起来一劳永逸，可模型如果中途拉取数据失败，你是让它重跑一遍还是只重试数据拉取？粒度太粗以后，这个问题没法优雅解决，只能整单重来，既浪费token又浪费时间。
粒度太细的问题也很麻烦：技能数量爆炸，模型在众多微技能之间跳来跳去，决策链路特别长，一旦某个微技能返回的格式与预期不符，后续所有技能都会连锁出错。我见过一个项目把“打开文件”“读取第一行”“切换到下一行”都拆成了独立技能，结果模型经常先执行“打开文件”，再执行“切换行”，但实际上前一个技能已经返回了全文内容，白白浪费大量推理步骤。
我建议的颗粒度标准是：一个技能应该在一到三次“模型决策”内完成，执行过程最多嵌套两到三层工具调用。超过这个复杂度，要么拆成多个串联技能，要么在技能内部写更固定的逻辑流程（比如直接在一个技能里用代码完成循环，而不是反复调用模型）。这样的技能既足够灵活，又可测试、可调参、可排错。
2.3 技能接口设计，除了参数还有三样东西不能少
很多人在设计技能接口时，只写了“技能名称 + 参数列表”，但真正在Agent场景里跑起来会发现远远不够。我推荐每个技能在描述上至少包含以下五部分：
- 技能名称：必须简短、语义明确，最好一眼能看出“这个技能是干嘛的”，比如
fetch_webpage_content、generate_meeting_minutes。 - 技能描述：说明这个技能适合做什么、不适合做什么、输入数据的常见来源。描述要像写产品需求一样，把边界条件说清楚。
- 参数定义：每个参数的类型、取值范围、默认值、是否必填，最好配上示例。这直接影响模型能不能正确填参。
- 输出结构：技能返回的数据结构要稳定、可预期。建议统一封装成
status + data + error三段式结果。 - 使用注意：比如“该技能依赖外部网络，可能会耗时3-5秒”“该技能仅支持中文文本”“该技能返回的内容可能包含敏感信息，请勿直接外发”等。这些信息可以帮助模型在决策时避免走弯路。
核心是让模型像人一样，拿到一份完整的“入职手册”，而不是给它一张只有名词的通讯录。我在实际项目里看到，很多Agent调用失败，最后排查下来不是函数写错了，而是技能描述里没有说明“该技能只能处理UTF-8编码”，模型传了一个GBK路径进去，整个流程就崩了。
还有一个细节容易踩坑：参数描述必须写“单位”和“边界”。比如timeout参数，如果只写“number”，模型很可能传一个10进去，但它不确定是秒还是毫秒。我建议所有数值型参数都写明单位和取值范围，例如“timeout（秒，取值0.5-30，默认5）”。越是能消除歧义，模型跑起来越稳。
3. 注册、发现和调度，让模型在正确时机选对技能
3.1 技能清单用JSON Schema描述，让模型一眼看明白
同一个技能库，不同的模型、不同的版本，对技能描述的理解能力差别很大。所以我会给技能层做一层非常严格的机器可读描述，通常是JSON Schema格式。这一步不能省，因为它是“模型能正确发现技能”的基础。
举个例子，假设我要注册一个“生成会议摘要”的技能，它的Schema会是这样：
{ "name": "generate_meeting_minutes", "description": "将会议录音转写文本或会议讨论文本整理为结构化的会议摘要，包括议题、结论、待办事项。适用于中文会议内容，输入文本长度建议不超过1万字。", "parameters": { "type": "object", "properties": { "source_text": { "type": "string", "description": "会议的原始文本内容，可以是ASR转写结果，也可以是人工整理的讨论记录。" }, "include_action_items": { "type": "boolean", "description": "是否在输出中提取待办事项，默认为true。" }, "summary_length": { "type": "integer", "description": "期望的摘要篇幅，取值为short（100字以内）、medium（300字左右）、long（800字左右）。" } }, "required": ["source_text"] }, "returns": { "type": "object", "properties": { "status": {"type": "string"}, "data": {"type": "object"}, "error": {"type": "string"} } } }这一层描述的作用包括：
- 模型决策时会扫描技能清单，判断哪个技能与用户意图匹配；
- 模型调用时会按照参数定义自动生成JSON参数，不会出现传参类型错误；
- 平台层可以做校验，参数不合法时直接拒绝，不用等技能内部报错。
从我踩过的坑来说，Schema里最容易忽视的是“description”的长度。太短了模型搞不清边界，太长了又占用上下文。我一般把每个技能的描述控制在40到80个汉字之间，尽量只保留“输入是什么、输出是什么、有什么限制”这三个信息。
3.2 让模型从“看到技能”到“选对技能”，还需要一层推理增强
仅仅把技能清单塞进system prompt是不够的。原因很简单：复杂任务往往涉及多个技能协同，模型在第一时间可能无法判断该用哪一个，或者该按照什么顺序编排。
我常用的做法是给Agent加一层“规划器”。规划器负责接收用户请求，输出一份技能调用计划，例如：
{ "intent": "分析某股票近期走势并生成一份简短报告", "steps": [ {"skill": "search_stock_data", "params": {"symbol": "600519"}}, {"skill": "calculate_moving_average", "params": {"window": 5}}, {"skill": "generate_analysis_report", "params": {"format": "short"}} ] }这层规划器的好处是：模型在“计划”阶段就可以把整体任务拆清楚，而不是边做边想。实际执行时，每个技能返回结果后，Agent再把结果动态放入下一轮的上下文中。这种方式尤其适合任务步骤相对固定的场景。
当然，规划器不是所有场景都必须。如果任务很简单，比如“帮我把这段文字翻译成英文”，直接让模型技能就足够了。但我建议在技能数量超过10个或者任务步骤可能超过3步的项目里，无论如何都要引入规划器。因为它提供了一次“全局思考”的机会，能大幅减少任务执行过程中的返工次数。
3.3 多技能组合时，要处理“依赖关系”和“备用路径”
技能的调用经常不是孤立的。比如“整理竞品动态并生成日报”，需要先调用“搜索新闻”，再调用“提取关键信息”，再调用“对比历史数据”，最后调用“生成日报”。一套技能之间天然有先后依赖。
我在做技能编排时，会在技能描述里显式标注“前置技能”和“后续建议”。还是沿用上面的会议摘要例子，在描述里可以加一句“通常与’提取行动项’技能配合使用”。这句话看似简单，但对模型组合技能很有帮助，它相当于给了模型一张地图，模型知道下一步往哪里走。
另一个容易被忽略的问题是“备用路径”。执行技能时，外部依赖很可能出问题，比如某个API超时、某个服务返回乱码、某个文件不存在。如果不设计备用路径，Agent遇到异常就会卡死。我通常会给关键技能写“降级策略”，例如“搜索某股票数据失败时，可以改用缓存目录下的最近一份数据，并在报告中标注’数据时间为昨日’”或“PDF解析失败时，尝试用OCR服务再解析一次”。这些降级策略写进技能描述后，模型遇到异常时就有机会自行恢复。
4. 实操：从零搭一个可复用的技能库，我这样走了一遍
4.1 先盘点需求，再决定技能树怎么展开
假设我现在要做一个通用的“文档处理Agent”，它可以处理用户上传的各种文档：提取正文、翻译、总结、提取关键实体、情感分析、生成摘要报告。
我会先把需求拆成如下技能树：
文档输入与解析技能
load_local_file：加载本地路径下的各类文档，支持txt、docx、pdf、markdown格式parse_web_document：从URL抓取网页并提取正文内容，去除页眉页脚和广告convert_file_format：把源文件转换为统一的纯文本格式
内容处理技能
extract_keywords：抽取文本中的关键词列表，附带相关性权重generate_summary：按指定长度生成内容摘要translate_text：在指定源语言和目标语言之间翻译文本extract_entities：抽取人名、地名、机构名、时间、货币等实体analyze_sentiment：判断文本的情感倾向（正面、负面、中性）
输出与交付技能
render_markdown_report：把结果渲染为结构化的markdown报告send_email_report：把报告通过邮件发送给接收人save_to_workspace：把结果保存到工作目录，返回文件路径
这样拆分之后，Agent的主流程就是：接收任务 → 规划器拆解 → 选择文档解析技能 → 调用内容处理技能 → 渲染交付。每一条链路里的技能可以独立替换，例如有人想换成更强的翻译模型，我只需要重写translate_text内部实现，外部接口完全不变。
4.2 技能实现模板：先定骨架，再填业务逻辑
具体写技能时，我强烈建议先定一个统一的“技能包装器”。我写技能统一是四个函数：
class BaseSkill: def __init__(self, config): ... def validate_inputs(self, params): # 检查参数是否合法 def execute(self, params): # 执行核心逻辑 def format_result(self, result): # 格式化输出validate_inputs的作用特别大，它能把模型传参错误在入口处拦截。比如某个技能要求输入文本长度不能超过5000字，如果模型传了8000字，技能可以先截断或报错，而不是等后续逻辑处理到一半才失败。
execute里我会做“错误处理+降级策略”。比如调用外部API失败时，尝试重试一次；重试还失败，就返回一个自定义错误码，并附加一段自然语言描述，例如“外部天气API暂时不可用，已改为使用内置的静态天气数据，请注意时效性”。这段描述会回到模型侧，模型可以据此向用户解释，让用户知道情况被处理了，而不是一头雾水。
4.3 技能测试：不只是验证“能跑”，还要验证“会选”
技能实现完之后，光写单元测试还不够。我还会做两类测试。
第一类是“单技能测试”。直接给定一组参数，确认输出结构正确、边界条件处理正常。比如对文本长度为0的空字符串、超长文本、带特殊符号的文本，都要跑一遍。
第二类是“端到端意图测试”。这是更接近实际运行的测试：给Agent一个半开放的用户请求，比如“帮我看一下这份合同里关于违约金的部分，然后总结成三条要点”，然后观察模型是否选择了正确的技能、是否按正确的顺序调用、输出结果是否合理。
端到端测试经常能暴露一些单测发现不了的问题，比如模型选了技能，但技能描述没写“本技能不支持PDF扫描件”，于是模型把一个扫描版PDF传给了extract_keywords，结果返回空列表，任务失败。这类问题只有在“模型-技能”协同测试时才能暴露出来。
我有一个实际踩过的例子：某个技能query_database，返回结果是一个很长的JSON数组，模型拿到数据后自己写代码处理，完全绕开了后续技能。这样看着也能完成任务，但执行逻辑不可控，而且如果数据库返回的字段格式变了，模型写的临时代码很可能直接报错。后来我在技能描述里加了一句“数据处理必须调用transform_table_data技能完成，不要自己编写临时处理逻辑”，情况立刻改善。很多时候不是模型能力不行，而是你给它的描述太自由了。
4.4 技能调参：描述怎么改，效果天差地别
在技能描述上，我也总结了一些实战经验。同样的技能实现，描述表述不同，模型调用结果差异非常大。举几个我调过的真实案例：
最初我写的技能描述是“判断文本情感，返回positive或negative”。模型调用时经常把中性文本误判为positive，因为它看到没有明确负面词就倾向于返回positive。
修改后的描述变成了“判断文本整体情感倾向。如果文本表达的情绪明显积极，返回positive；明显消极，返回negative；如果情绪复杂度较高或无明显倾向，返回neutral。注意，讽刺、疑问、双重否定等表达需要仔细辨别语气，不要被表面词汇误导。”
改完之后，准确率提升了大约15个百分点，说明描述里的“边界情况和易错提醒”对模型决策质量的提升非常明显。
另外一个经验是：参数描述尽量用“正面清单+反面禁止”的方式。例如：
skill: extract_entities description: "从文本中识别人名、地名、机构名、时间、货币和百分比。 注意：只识别文本中显式出现的信息，不要基于常识联想补全缺失信息。 如果文本中某类实体不存在，返回空列表，不要编造。"这样模型就知道“什么情况下不掏结果”，而不是为了“完成度”强行脑补，输出一堆不存在的实体。这个问题在做Agent技能时非常普遍：模型倾向于“完成一个看起来完整的答案”，但很多任务里宁可少给，不能瞎给。
5. 运行调试与性能排查，我踩过的坑比写过的代码还多
5.1 技能上下文污染：多个技能结果叠加后，模型容易“精神分裂”
这是我在技能编排里遇到的最大一坑。当一个Agent连续调用多个技能时，前几个技能的完整结果会全部留在上下文里。执行最后一个技能时，模型已经“看”了很多历史内容，经常会混淆：比如把上一个任务里的数据处理逻辑，沿用到当前任务中；或者把之前代码里定义的变量名拿来引用，但当前上下文里根本没有。
我的应对方案有两个：
第一，尽量不在上下文中堆叠原始返回结果。每个技能执行完后，只保留“摘要化”的结果或者关键数据点。例如fetch_stock_data返回的一个1000行K线数据，没有必要全部塞给模型，可以先在技能内部做一次数据压缩，只输出最近30天的关键点。这样上下文几乎不膨胀，模型决策也不会被大量冗余数据干扰。
第二，在技能返回结果里增加“数据来源时间”和“处理状态”标签。比如as_of_time: "2026-01-15 10:00"，这样模型在后续推理时知道数据是什么时点取的，不会拿昨天的数据回答今天的问题。这些元信息放在结构化数据字段里，模型可以感知到，又不影响正常输出。
5.2 技能执行顺序错了，结果跟着错，但很难排查
技能编排最怕“看起来差不多，实际上顺序不对”。比如“抽取文本关键词”应该在“生成摘要”之前还是之后？如果先抽关键词，再让模型生成摘要，摘要会围绕关键词展开，逻辑更集中，但会损失一些次要信息。如果先生成摘要，再抽取关键词，关键词容易更全面但比较泛，缺少主题聚焦。
这类“顺序敏感”问题，我建议在技能描述中显式标注，例如：
generate_summary: description: "根据输入文本生成摘要。建议在调用extract_keywords之后执行， 以便摘要能覆盖核心关键词对应的主题；如果文本本身很短，也可以直接使用。"更重要的是，在规划器里我要写死“高优先级任务的固定顺序”，不让模型自由发挥。也就是说，对于关键业务链路，我们要对编排做约束，而不是把一切交给模型临场决策。虽然从产品角度看，模型“自由调度”很酷，但真正生产环境里，稳定高于炫技。我个人的经验是：百分之八十的流程固定编排，百分之二十的边缘场景允许模型自由决策。这样既稳定，又保留了泛化能力。
5.3 可观测性：技能日志不是用来看的，是用来追责的
技能多了之后，最可怕的事情是“某一天突然某条任务链路失败了，但不知道是哪一步失败了”。为了避免这种瞎猜的情况，我在技能层做了非常结构化的日志。
每条技能调用的日志记录以下信息：
- 技能名称与版本号（技能代码更新后版本号要变，否则无法追踪行为差异）
- 传给技能的完整参数（含默认参数）
- 技能执行开始和结束时间
- 返回结果的状态码
- 如果失败，失败原因和重试记录
- 调用的上游技能ID（链路追踪用）
有了日志之后，我把它们聚合到一个统一的看板上。当任务失败时，我先看状态码，再顺着链路ID定位到具体是哪一个技能出了问题。如果某技能连续失败率高，我会检查是参数不稳定、外部依赖波动，还是技能描述导致的选择策略偏差。这个习惯帮我节省了大量调试时间，没有它，排错全凭感觉，效率太低了。
日志还有个好处：可以用它来做“技能质量评估”。比如统计每个技能被调用的次数、成功率、平均耗时，定期清理那些很少被调用或者准确率特别低的技能。这就像收拾工具箱，长期不用或者已经生锈的工具，要么修复要么丢掉，不要让它们占着上下文的坑位。
6. 技能库的长期维护，以及我最想提醒你的几件事
技能层不是建完就结束了。它就像一套第三方基础库，需要持续迭代。我会在每次真实任务结果中抽样，让用户对结果进行反馈（点赞/点踩或直接改文字），把负面案例喂回给技能描述和参数设计里。
比如某次用户反馈“生成的摘要太笼统，没有包含具体的数字指标”。我会去看技能描述，发现描述里根本没提到“需要保留所有数值指标”。于是我在描述里加了“生成摘要时，所有关键数字指标（金额、百分比、日期、版本号）必须原样保留”。此后这类问题大幅减少。
技能设计有一个不变的原则：你描述得越明确，模型发挥越稳定。不要指望模型具备“常识”来自动理解你的业务复杂度，它的确有一些通用能力，但任何业务里都有大量隐性规则和边界约束，你把这些规则写进技能描述里，模型才可能表现得好。
最后再分享一个我坚持了很久的小习惯：每次新增技能，都要顺手写一个“该技能不能做什么”的负面清单。这一条在别人看来可能多余，但实际运行中，负面清单是减少模型误调用的最有效手段之一。模型不是逻辑上不知道该不该调用，而是它经常过于自信，而负面清单会像一道保险丝，把那些不合理的调用思路提前掐断。我建议你也在自己的Agent项目中尝试一下，大概率会减少很多深夜排查问题的机会。
