基于大语言模型的Agent技能管理：从Function Calling到agent-skills实践

过去几个月我一直在捣鼓基于大语言模型的Agent应用，从最开始把所有指令写进System Prompt的"草台班子"，到后来引入function calling把十几个函数一股脑丢给模型，再到最后沉淀出一套叫 agent-skills 的技能管理机制。中间踩了太多坑，最深的体会是：做Agent不难，难的是把Agent的能力做得可控、可复用、可度量。

agent-skills 解决的核心问题，简单说就一句话——让Agent拥有一批"知道自己什么时候该用、怎么用、用了会怎样"的标准化能力模块。它不是一个开箱即用的框架，而是一套设计理念和配套机制的组合。这套机制对两类人最有用：一类是正在把Demo级Agent推向生产的工程师，另一类是研究Agent编排、想把工具调用做得更工程化的同学。如果你只是写个玩具级别的聊天机器人，那下面的建议可能略微超前，但提前建立技能化思维绝对没坏处。

接下来我不打算讲空泛的概念，而是按我实际搭建这套体系的过程来展开：先讲清楚技能和Prompt、插件、函数调用的边界，再给出设计技能时真正要纠结的细节，然后是完整的代码实现，最后是运行时和评估的实战经验。你可以把这篇当成一份可以直接抄作业的工程笔记。

1. Agent Skills不是新名词：它到底在解决什么问题

1.1 一句话定义：技能是Agent的"可复用执行单元"

技能（Skill）本质上是一个自包含的能力模块：它有名字、有描述、有输入输出协议、有执行逻辑、有副作用声明。表面上它跟"工具""函数"长得很像，但有一个关键区别——技能不只是"一个能跑的代码"，还带着"如何被正确调用"的元信息，以及"调用失败后怎么办"的兜底策略。

用个生活化的类比：函数调用像是给新同事发一堆小纸条，每条上面写着"去干这件事"；而技能像是给新同事一本标准作业手册，每项任务都有适用场景、操作步骤、注意事项和异常处理流程。前者能干活，后者能在没人盯着的时候把活干对。我最早尝试把"技能"简单做成工具列表时，模型在小型任务集上表现还不错，但一旦技能数量超过20个，选择准确率就开始明显下降。这不是模型变笨了，而是调用元信息做得不够结构化。Agent Skills这套机制的核心，就是把"元信息"从代码注释提升为一等公民，让模型除了执行之外，还有能力"挑选正确的能力"。

1.2 Prompt、Plugin、Function Calling与Skill的边界

很多人会把这几个概念混淆，我先用一张表把边界理清楚。这四类东西在Agent工程里都有明确位置，但解决的问题和适用阶段完全不同：

举一个我实际遇到的例子。早期做"发送邮件"这个功能，我用的是Function Calling：声明一个send_email(recipient, cc, subject, body)函数就完了。结果模型经常把收件人和抄送搞混，该发正文的字段塞进主题。后来改成Skill之后，我在描述里明确写了"正文必须包含会议时间、地点、议程摘要，收件人必须是已验证的同事邮箱，抄送可选"，并让Skill内部先走一遍参数语义校验，模型的表现立刻稳了很多。

这里本质差别在于：Function Calling描述的是"我能做什么"，Skill描述的是"这件事在什么情况下可以做、怎么做、做错了怎么办"。后者才是生产环境需要的信息密度。我后来跟团队说得很直白：如果你把Agent当成实习生，Function Calling是给实习生一份任务清单，而Skill是给实习生一本带判断标准的操作手册。

1.3 什么时候你需要一套技能体系

不是所有项目都需要技能体系。过度设计是真实存在的事情，我自己就见过反面案例——一个总共只有5个函数的项目，团队硬上了完整技能框架，代码量翻了三倍，收益却几乎为零。我自己的判断标准有三个，满足两条以上才值得动手：

• 技能/工具数量超过15个，模型已经出现明显的选择困难，回答质量忽高忽低；
• 同一个能力被多个流程复用，且每次调用都需要不一样的参数组合，直接硬编码导致到处复制粘贴；
• 需要跨版本迭代能力，旧的调用方式不能因为一次改动就全部中断，必须有版本识别和兼容层。

如果三条中只中了一条，继续用Function Calling或者干脆写死在Prompt里就够了。技能体系的价值是"规模效应"释放出来的，数量不够的时候，它的管理成本会超过收益。这是我踩过坑之后才敢说的实话。

2. 设计一个技能，先想清楚这四样东西

技能设计决定了后面所有环节的上限。运行时调度、评估、迭代，全都是在设计的地基上盖楼。地基歪了，后面所有楼层都会跟着歪。

2.1 技能名称与描述：模型靠"文字直觉"做选择

技能的名称和描述是模型做"技能选择"时最主要的依据。这里我吃过大亏。早期写描述时我追求"文艺"，什么"将零散思绪编织成结构化篇章"，结果模型在总结任务上绕了三圈才选中它，还偶尔选错。后来我总结出一个原则——描述要像API文档的注释，而不是广告词。

写清楚四件事：这个技能负责什么任务；什么时候应该调用它；什么时候不应该调用它；输入参数怎么填最合适。比如会议纪要这个技能，我最终敲定的描述是：

skill: meeting_minutes description: 将会议录音的文字转写整理为结构化会议纪要。 在会议结束后、需要生成可分发文档时调用。 不要用于实时字幕，也不要用于逐字转写。 输入是转写文本，输出包含议题、结论、待办和风险四部分。 每个待办必须注明负责人和截止日期。

这段描述实测下来命中率接近97%。关键就在"什么时候不该用"这一句——它帮模型排除了大量相似场景，比如"会议还没开完"或者"用户只要一句话摘要"这种边界情况。很多人只写"能做什么"，不写"不能做什么"，结果模型把所有类似的请求都当成这一个技能的活儿。

2.2 输入输出Schema：把自由度留给模型，把确定性留给自己

技能的所有参数应该用JSON Schema严格声明。我见过太多人只写参数名和类型，不写约束和示例，结果模型自由发挥，传入的对象千奇百怪。

我自己的Schema模板包含：类型（string/integer/array等）、必填与否、枚举值（能枚举就枚举）、格式约束（如正则、日期格式）、默认值、示例值。最容易被忽略的是"示例值"，但它其实是模型构造参数时的重要参考锚点，特别对于复杂嵌套结构。举个例子：

{ "type": "object", "properties": { "transcript": { "type": "string", "minLength": 100, "description": "会议全程的语音转写文本，需包含发言内容", "examples": ["主持人：今天讨论Q3计划..."] }, "language": { "type": "string", "enum": ["zh", "en"], "default": "zh" } }, "required": ["transcript"] }

输出端同理，不要满足于"技能返回一段文本就够了"，而要定义输出Schema——字段名、类型、嵌套结构、是否可空。输出结构稳定了，下游编排和前端展示才不会天天修bug。我见过一个项目，技能输出的待办事项字段一开始是"谁负责+任务"，后来变成"负责人+任务+备注"，下游解析代码改了三次，这就是输出Schema不设防的代价。

2.3 副作用声明与失败策略：技能不是纯函数

技能可能有副作用：写数据库、发消息、调外部API、改文件。这些动作如果不在元信息里声明，模型在规划复杂任务时就会做出危险的假设——比如以为"发送邮件"只是生成草稿，实际却把邮件发出去了。

我在Skill对象里加了一个side_effects字段，用枚举声明READ_ONLY、WRITE_DB、SEND_MESSAGE、CALL_EXTERNAL_API等类型。调度器可以对那些带副作用的技能采取更严格权限策略（比如要求用户二次确认），对只读技能则放开执行。同时，每个技能必须定义失败策略：重试、降级、返回错误码、还是直接中止整个任务链。

这里我的经验是：优先让技能内部做兜底，把"可处理的异常"消化在技能内部。比如外部API超时，技能可以先重试一次，再降级用缓存数据，实在不行才返回错误码。只有跨技能协作层面的错误才往上抛给编排层。如果所有错误都往上层抛，Agent的规划器就会被各种异常打断，整个任务链很难跑通。

2.4 技能粒度：拆到什么程度才算合适

粒度是我被问得最多的问题。我的经验值：一个技能应该能在一分钟到两分钟内干完一个完整子任务，输入输出语义清晰，不需要再拆。

举两个反例。一个是"提取发言人列表"——它太碎了，模型不会为了这个小步骤专门去切换技能，硬拆成技能只会增加选择负担。另一个是"处理项目所有相关文档"——它又太大了，模型根本搞不清楚边界，参数也不知道该怎么填。判断粒度是否合适有个简单方法：写技能描述时，如果能用一两句话讲清楚"什么输入做什么输出"，粒度大概率是对的；如果描述必须绕好几句话还说不清楚，就继续拆。这个方法我让团队用了一年，基本没出过错。

3. 从零搭建技能注册与调度机制

理论讲完了，上实际代码。下面这套实现我用的是Python，核心思想不绑框架，你也可以移植到TypeScript、Go等任何语言。关键就三件事：注册表、校验器、调度器。这三件事分别解决"有哪些技能""参数对不对""怎么安全地执行"。

3.1 一个轻量级技能注册表的核心数据结构

先定义Skill这个数据类。它比普通函数多出来的所有字段，都是为了"让模型更准确地选它、更安全地调它"：

from dataclasses import dataclass, field from typing import Callable, Optional, Any import json import jsonschema @dataclass class Skill: name: str # 技能唯一标识，通常用 snake_case description: str # 面向LLM的能力描述 input_schema: dict # JSON Schema 格式 output_schema: dict # 输出结构约束 handler: Callable # 实际执行函数 side_effects: list = field(default_factory=list) # 副作用声明 version: str = "1.0.0" tags: list = field(default_factory=list) # 便于路由/检索 enabled: bool = True def validate_input(self, params: dict) -> dict: # 用 jsonschema 库做严格校验，返回校验结果对象 validator = jsonschema.Draft7Validator(self.input_schema) errors = sorted(validator.iter_errors(params), key=lambda e: e.path) if errors: return {"ok": False, "errors": [e.message for e in errors]} return {"ok": True, "data": params}

然后是注册装饰器。我习惯用装饰器而不是手动往字典里塞，因为技能定义和执行逻辑放在一起，维护成本最低，也方便后面写自动扫描和文档生成：

SKILL_REGISTRY: dict[str, Skill] = {} def register_skill(name, description, input_schema, output_schema, side_effects=None, version="1.0.0", tags=None): def decorator(func): skill = Skill( name=name, description=description, input_schema=input_schema, output_schema=output_schema, handler=func, side_effects=side_effects or [], version=version, tags=tags or [], ) if skill.name in SKILL_REGISTRY: raise ValueError(f"技能重名: {skill.name}") SKILL_REGISTRY[skill.name] = skill return func return decorator

3.2 实战案例：写一个"会议纪要"技能

拿会议纪要这个例子完整走一遍。先定义技能，这是最繁琐但也是最核心的部分：

@register_skill( name="meeting_minutes", description="将会议录音的文字转写整理为结构化会议纪要。" "在会议结束后、需要生成可分发文档时调用。" "不要用于实时字幕或逐字转写。" "输出包含议题、结论、待办和风险四部分。", input_schema={ "type": "object", "properties": { "transcript": {"type": "string", "description": "完整的会议转写文本"}, "language": {"type": "string", "enum": ["zh", "en"], "default": "zh"} }, "required": ["transcript"] }, output_schema={ "type": "object", "properties": { "topics": {"type": "array", "items": {"type": "string"}}, "conclusions": {"type": "array", "items": {"type": "string"}}, "action_items": { "type": "array", "items": { "type": "object", "properties": { "owner": {"type": "string"}, "due_date": {"type": "string"}, "task": {"type": "string"} }, "required": ["owner", "task"] } }, "risks": {"type": "array", "items": {"type": "string"}} }, "required": ["topics", "conclusions", "action_items", "risks"] }, side_effects=["READ_ONLY"], tags=["meeting", "document"], ) def meeting_minutes(transcript: str, language: str = "zh") -> dict: # 实际逻辑：调用LLM做结构化抽取 + 规则后处理 # 这里简化为示意实现，重点在于输出强制符合 schema result = llm_extract_structured( transcript, output_format="meeting_minutes_schema" ) # 对输出做二次校验，不符合schema时触发修复 return normalize_to_schema(result, output_schema)

强调一个细节：技能内部也要做输出校验。LLM抽取结果偶尔会缺字段，我习惯在handler里加一道normalize逻辑，缺什么补什么。比如action_items缺due_date，就根据会议时间推算一个默认值，并打上auto标记。这样下游拿到数据永远都是完整的，不会因为一个空字段导致整个UI崩溃。

3.3 多技能编排：从单技能调用到任务规划

单技能好搞，多技能协作才是Agent的日常。我的做法是引入"协调器"，它维护一个执行上下文，让技能之间通过上下文传递数据，而不是每个技能都去读全局变量。这样单个技能可以独立测试、独立并发，互不干扰：

class SkillCoordinator: def __init__(self, registry: dict): self.registry = registry def invoke(self, skill_name: str, params: dict, context: dict) -> dict: skill = self.registry.get(skill_name) if not skill or not skill.enabled: return {"ok": False, "error": f"未知或禁用的技能: {skill_name}"} # 1. 参数校验，不通过直接返回，不进入handler validated = skill.validate_input(params) if not validated["ok"]: return {"ok": False, "error": validated["errors"]} # 2. 副作用策略检查（例如需要审批则拦截） if "SEND_MESSAGE" in skill.side_effects and not context.get("approved"): return {"ok": False, "error": "need_approval"} # 3. 执行 + 输出校验 raw = skill.handler(**validated["data"], context=context) checked = validate_output(skill.output_schema, raw) if not checked["ok"]: return {"ok": False, "error": "output_schema_mismatch"} return {"ok": True, "data": checked["data"]}

规划层面，我建议先用"技能选择器+顺序执行器"的组合。让规划模型输出一个技能调用计划，然后协调器按计划逐段执行，每步执行结果写入context，供下一步技能读取。等团队对技能比较熟了，再上更复杂的图状编排也不迟。先让线性的链路稳定跑通，再谈非线性编排的收益，这个顺序不要颠倒。

4. 运行时最容易被忽视的三件事：选择、冲突与权限

框架搭起来、技能都注册好了，运行起来才会发现一堆"看起来没问题但实际会炸"的细节。这三件事我都是在生产环境被教育过后才补上的，每条都对应过真实事故。

4.1 技能选择：不要让模型在100个技能里做阅读理解

技能数量一旦上规模，把全部技能描述塞给模型让它在里面挑，选择质量和Token成本都会快速恶化。我实测的经验数据如下：模型在20个技能以内时，直接全部列出效果最好；超过30个，就开始出现"选了一个看似相关但实际不对"的技能；超过50个，准确率会掉到让人头疼的程度。

我采用的缓解方案是分层路由：第一层用规则+关键词给请求打标签，只把候选技能缩小到相关标签下；第二层再把缩小后的技能描述给模型做精确选择。

def route_to_skill(user_intent: str) -> list[str]: tags = extract_tags(user_intent) # 规则引擎 + 关键词匹配 candidates = [] for skill in SKILL_REGISTRY.values(): if set(skill.tags) & set(tags): candidates.append(skill.name) return candidates or list(SKILL_REGISTRY.keys())

注意：tag不是写死的分类目录，而是技能设计时一起定义的能力边界。如果某个技能可以被多个场景复用，多打几个标签就行。这套方案把模型的选择空间从接近100个降到10个左右，准确率和速度都明显改善。我后面只要新注册技能，第一件事就是确认它的标签足够覆盖真实请求。

4.2 冲突处理：同名技能、相似描述与优先级

技能多了，两个麻烦必然出现：重名，以及"两个技能都能处理同一个请求"。重名我在注册阶段就拦截了，注册器里直接抛异常，不允许同名，这个没有商量余地。但相似描述更阴险——比如"会议纪要"和"谈话整理"，语义高度重叠，模型随机选择，用户体验一会儿一样一会儿不一样。

我的做法是给技能增加优先级字段，并允许在技能描述中显式声明"如果同时匹配了xx技能，优先使用本技能"。另外，在技能选择层的提示词里加一条硬规则：当存在相似技能时，优先选择副作用更小、更通用的那个。比如READ_ONLY优先于WRITE_DB，查询类优先于写操作类。这条规则能够避免模型在情况模糊时选一个"能写库但只读就够"的技能，减少无谓的写入操作。

4.3 权限与隔离：技能能调API，但能调"你的"API吗

技能里有READ_ONLY、有SEND_MESSAGE、有CALL_EXTERNAL_API，权限策略必须按副作用分档。我把执行级别分为三档：L1是只读、无外部副作用，直接放行；L2是写本地存储或内部数据库，需要业务规则检查（比如不能覆盖未提交数据）；L3是发送消息、调用外部API、删除数据，必须用户确认或走审批白名单。

在代码里，调度器在invoke前根据side_effects检查context里的权限标记。没有权限标记就返回need_approval，而不是直接执行。这个机制救过我一次：有一次模型规划了一个"先读取邮件、再自动回复全部邮件"的链路，如果L3拦截不存在，这几封邮件就真的全部发出去了。权限层级的核心逻辑，就是把"模型想干什么"和"系统允许它干什么"彻底分开。隔离方面还有个细节：技能之间不共享全局状态，所有跨技能数据都通过context显式传递。这样单个技能的并发执行是安全的，也不会有隐式的数据污染。

5. 踩坑实录：我的五个典型翻车现场

这节全部来自真实生产事故，没有虚构。每个问题我都按"现象-根因-修复"来写，方便你直接对照排查。也是这五个坑让我把 agent-skills 从"能用"磨到了"好用"。

5.1 现象：描述写得越详细，模型越容易选错

最早我觉得技能描述写得越全越好，于是把语法规则、格式要求、边角案例、历史背景全部塞进去，写成了一篇两百字的小作文。结果模型的注意力被后面那些边角案例带走，反而忽略了最核心的适用场景。根因很清楚：模型在长文本里找关键信息的能力没有我想象的强，冗长描述稀释了核心信号。修复方案把描述结构化为"任务定位+触发时机+禁忌+输出概要"四行，长尾注意事项全部移动到Schema的字段描述中，不再堆在技能描述里。改完之后，选择准确率从82%升到96%，这个数据对比让我彻底信了"减法优先"。

5.2 现象：跳过了JSON Schema校验，接口参数直接崩

早期图省事，觉得"大模型肯定不会乱传参数"，于是模型传什么参数就往handler里塞，跳过了入口校验。结果有一次模型把字符串空数组传了进去，handler内部直接报错，整个任务链路失败，用户看到的是一个莫名的红色错误页。根因不是模型抽风，而是我把校验这个本该由系统完成的工作完全托付给了模型的"自觉"。修复方案很简单：调度器中固定走validate_input，把jsonschema校验放在handler之前，并给校验错误设计统一返回结构。这之后几乎所有参数问题都在入口被拦截，handler代码可以放心做假设，再也不需要在每个函数里写一堆防御式判断。

5.3 现象：输出格式没有被强约束，下游解析全乱套

第一次写会议纪要技能的时候，我让LLM输出自然语言，然后用正则去抽字段。看起来灵活，结果待办事项经常抽不全，负责人名字带上各种前缀后缀，日期格式三天两头变。根因是我把"结构化输出"这个责任交给了不稳定的正则表达式。修复是把输出定义为严格JSON Schema，技能内部用few-shot示例引导LLM按schema输出，并对结果做二次校验和修复。这块改完后，下游UI和编排没有再因为格式问题返工，之前每天花在修数据上的时间基本归零。

5.4 现象：技能之间共享状态，出现竞态

运行一段时间后我开始做技能并发，结果发现数据对不上。排查半天，根因是我在context里放了一个可变list，两个技能并发执行时都往里追加数据，数据交错之后出现同一个待办被记录了两次、另一个待办丢失的情况。修复方案是：把context改成不可变快照，技能执行时只能读取传入的context，返回的新数据由协调器统一合并。任何需要跨技能传递的数据都显式在步骤间声明依赖关系。这个改动让技能之间的耦合变得可见，代码审查也更容易发现数据流问题。

5.5 现象：只测正常链路，上线第一天就翻车

我们当时用五六个精心准备的"正常输入"测了所有技能，觉得稳了，结果上线当天用户上传了一份2000行的会议转写文本，token直接超限，技能超时报错。另外用户用英文提问，但技能只处理了中文文本，返回了一堆空字段。根因是测试的视角太"温室"了，完全没有考虑真实世界的脏数据和规模问题。修复是给每个技能补齐边界测试：超长输入、空输入、多语言混合、字段缺失、并发调用、超时降级。这之后我把"边界用例"写进了每个技能的回归集，并且形成了一条硬规矩：没有边界测试的技能不允许上线。

这几个问题的共同本质，我用一句话总结：技能做的是"让模型在结构化的约束下发挥创造力"，设计者必须把所有不确定性的边界焊死。模型擅长发散，系统必须擅长收敛。

6. 如何评估一套技能体系：指标、回归集与日志复盘

技能体系上线不等于结束，它需要像其他系统一样被持续度量。我习惯用一套相对简单的指标和流程来保持技能体系的健康度，不搞复杂的指标体系，够用且能被团队真正执行才是关键。

6.1 两个核心指标：命中率与完成率

我把技能评估简化为两个最核心指标，分别衡量"选择阶段"和"执行阶段"的质量：

• 技能命中率（Skill Hit Rate）：给定一条用户意图，模型是否选中了正确的技能。分母是全部测试意图，分子是选中正确技能的数量。
• 任务完成率（Task Completion Rate）：选中技能后，技能是否能成功执行并返回符合Schema的结果。执行中的任何异常、超时、Schema不匹配都算失败。

除此之外我会记录每次调用的Token消耗和延迟。Token消耗特别能反映技能描述的质量——描述冗长、候选列表过大都会造成Token成本翻倍。我见过最夸张的一次：路由层没做标签过滤，调用一次做日程安排的技能竟然消耗了2万Token，全花在选择阶段了。这个数据直接推动我们上了分层路由，之后Token消耗降了70%。

6.2 构建技能回归测试集

评估不能靠拍脑袋，要有一份随版本迭代的回归测试集。我的做法是每个技能维护三组用例：正向组是典型的正常输入，验证核心功能；边界组是空输入、超长输入、缺字段、混合语言等，验证健壮性；对抗组是和另一个技能高度相似的意图，或者模型容易误解的描述，验证选择准确性。

这些用例不一定是真实用户数据，但我会从真实日志中持续抽取典型case补充进去。每次技能注册表或调度逻辑变更，就跑一遍全量回归。命中率和完成率掉了任何一个点，都要找到具体case修复，而不是假装看不见：

6.3 从Agent日志里挖技能优化的机会

日志是技能体系最值钱的副产品。我每次复盘都固定看三类日志：一是重试记录，同一意图触发多次技能调用，说明技能描述或Schema让模型犹豫不决；二是错误码分布，校验失败占比高，说明输入Schema约束不够或描述误导了参数构造；三是被拒绝的调用，模型选择了某个技能但被权限拦截，这可能是模型规划错了，也有可能是权限策略太紧。

我会从日志里挑出Top10的失败case，每周集中优化一次。这个节奏不需要追求大改，每次只改一两个技能的描述或Schema，用回归集验证，稳定了就上线。迭代多了之后，我对团队说最多的一句话是：技能体系不是设计出来的，是迭代出来的。

我个人在实际项目中体会最深的一点是：Agent的能力边界，其实是由技能体系的描述质量决定的。你花在写技能描述、设计Schema上的每一分钟，最后都会转化成生产环境里的稳定性和Token成本的收益。所以如果你正准备把Agent推向生产，我建议从今天起就给你的每个能力模块加上完整的元信息——这比换个更贵的模型划算得多。