2026 年再看 Agent Skill 开发很多概念在大模型应用社区里仍然没有统一说法。Agent、Skill、MCP 经常被混在一起讲真到自己写代码时还是不知道从哪里下手。这里不聊虚的直接按“概念 - 环境 - 最小Demo - 代码实战 - 批量生产 - 排查”的顺序拆一遍目标是让读者看完能自己写一个可复用的 Agent Skill并搞清楚它和 MCP、Agent 的边界。适合已经能调用大模型 API、但正准备把能力沉淀成独立模块的开发者。1. 先搞清楚Agent Skill 到底解决什么问题1.1 从“Agent 什么都能干”到“按能力协作”先说结论Agent 是调度器Skill 是可执行的能力单元。这个区分看起来简单但很多人会一直绕。在没有 Skill 的架构里Agent 通常把所有上下文塞给大模型让模型直接生成结果。对“写一首诗、做个头脑风暴”这类开放任务效果还行。可一旦任务需要稳定调 API、读本地文件、做计算、按固定格式返回结果纯靠模型生成就很不可靠格式会漂字段会缺失同一个任务跑三次可能得到三个不同结果。Skill 的作用是把“调外部系统、处理数据、返回结果”这层逻辑从模型提示词里抽出来变成一段可测试、可复用的代码。Agent 只负责理解任务、选择技能、传入参数。这样既发挥大模型的理解和规划能力也保留了代码的确定性。举一个农业大模型场景的例子。你希望系统根据土壤、气象数据给出灌溉建议。土壤监测是一个技能气象分析是另一个技能增产建议是第三个技能。Agent 拿到实时数据后先调用土壤监测技能再调用气象分析技能最后根据结果决定是否需要提示用户灌溉。这个过程里每个技能都能单独测试也能替换实现Agent 本身并不需要理解传感器的通信协议。这个思路同样适用于通用 Agent先盘点业务里有哪些“稳定能力”再把它们变成 Skill。能力越多Agent 能处理的场景才越多。反过来如果 Agent 只是会聊天那它就不是真正意义上的 Agent只是一个包装过的对话模型。1.2 Skill 不是提示词也不是插件很多人把 Skill 理解成“写得更好的提示词”这是最常见的误区。提示词是一种文本指令它依赖模型理解能力。Skill 是一个具备输入、输出、执行逻辑和错误处理的代码单元。即使模型换掉只要接口兼容Skill 还能继续用。提示词换了理解力较弱的模型效果可能立刻崩掉。插件这个词更容易混淆。插件通常指某个平台或框架里的扩展模块比如浏览器插件、IDE 插件、Agent 框架的 tool 插件。Skill 更侧重“业务能力封装”它不关心底层是调用 HTTP API、读数据库还是执行本地脚本只关心这个能力如何被 Agent 稳定调用。可以这样理解维度提示词插件Skill本质文本指令扩展模块可复用的能力单元依赖大模型理解力平台接口调用逻辑 参数 容错稳定性低中高测试方式人工改词平台测试单元测试 日志1.3 Skill 里面到底放着什么一个可以实际使用的 Skill至少要包含五部分技能名称例如 text_summary用于注册和调用。技能描述用于让 Agent 知道“什么情况该用它”。输入参数定义说明需要哪些字段、是否必填。这是经常被忽视的部分。参数定义不清Agent 不知道该传什么调用自然失败。执行函数里面是真正的业务逻辑可以调用大模型 API、访问数据库、执行计算。错误处理和输出结构保证失败时返回可读的错误信息而不是裸抛一个异常。我在实际开发里还会额外加一个技能清单接口。它可以列出当前注册了哪些 Skill、各自参数是什么。有了清单Agent 才能做路由人也方便做调试。这是最简单的“代码实战开发”起点后面所有批量化和接口化都是在这个基础上扩展的。2. 跑一个最小的 Agent Skill 需要什么环境2.1 硬件到底要多高先给一个稳妥的结论如果 Agent Skill 只是调用云端大模型 API普通的 CPU 笔记本就够用。不用 4090不用 64GB 内存基本内存 8GB 或 16GB 都能跑。真正消耗资源的是大模型本身不是 Skill 调度代码。什么时候才需要考虑 GPU只有当你选择本地部署 AI 大模型比如自己部署开源模型做推理时才会需要明显更高的显存。你可以在低配置机器上先做 Skill 开发把模型调用细节藏在执行函数后面。等需要本地模型时再换一个调用实现Skill 的输入输出不用改动。这样能把“业务代码”和“模型环境”解耦。不过要注意“低配置能跑”不等于“适合批量跑”。如果你要同时处理几百条任务还要考虑 API 限流、磁盘空间、日志文件大小和单次任务的超时时间。这些问题在第一条任务上不会暴露批量时一定会暴露。2.2 软件和依赖怎么准备推荐 Python 3.10 以上版本。原因不是新语法多重要而是很多 AI 相关 SDK 和类型标注都开始默认支持 3.10 以上遇到依赖问题时能少踩一些坑。安装依赖时我建议按“最小化”原则来。尽量先只用 HTTP 客户端比如 requests 或 OpenAI SDK。用官方 SDK 的好处是参数更规范但坏处是多包了一层出错时排障成本更高。第一次跑通我更建议直接使用 SDK因为它的错误信息比裸 HTTP 请求更友好。一个最小依赖文件可以是openai1.0.0 python-dotenv1.0.0如果是用其它模型平台就安装对应的 SDK。这里不写死版本具体以你安装时的最新稳定版为准。安装命令就是pip install -r requirements.txt环境里最好有 .env 文件保存 API Key不要直接写在代码里。python-dotenv 读取很简单from dotenv import load_dotenv import os load_dotenv() api_key os.getenv(LLM_API_KEY) model_name os.getenv(LLM_MODEL)这里有个容易忽略的点如果你的代码里没写 .env 也能跑说明环境变量已经配置好了。但一旦换一台机器环境变量丢失程序就会报鉴权失败。所以项目里最好保留 .env.example 模板并说明需要哪些变量。2.3 最小链路定义、注册、调用第一步先不接真实大模型用一个假的摘要函数把链路跑通。目的是验证注册机制和调用逻辑没问题之后再替换成真实 API。# skill_demo.py skills {} skill_schemas {} def register(name, schema): def decorator(func): skills[name] func skill_schemas[name] schema return func return decorator def _fake_summary(text, max_length200): if not text or not isinstance(text, str): raise ValueError(text must be a non-empty string) return { summary: text[:max_length] ... if len(text) max_length else text, source_length: len(text), } register( text_summary, { name: text_summary, description: 对长文本生成摘要, parameters: { text: {type: string, required: True}, max_length: {type: integer, required: False, default: 200}, }, output: {summary: string, source_length: integer}, }, ) def text_summary_skill(inputs): max_length inputs.get(max_length, 200) return _fake_summary(inputs[text], max_length) if __name__ __main__: result skills[text_summary]( {text: 这是一个用于验证 Agent Skill 最小链路的测试文本。, max_length: 20} ) print(result)这段代码虽然简单但已经把“定义 - 注册 - 调用”这条主线跑起来了。运行后控制台会输出一个字典里面有 summary 和 source_length。这说明你的 Skill 执行环境没问题注册表也没问题。接下来再逐步接真实模型、补充错误处理和日志就不会一头雾水。3. 从零开发一个可复用的 Skill关键代码拆解3.1 输入输出契约先定下来开发 Skill 时很多人上来先写函数逻辑再想参数。我的习惯是反过来的先把输入输出契约定下来。什么叫契约就是你的 Skill 接收什么字段、每个字段什么类型、是否必填、输出返回什么结构。契约定了Agent 路由和外部调用才有一个统一标准。比如一个摘要技能输入可能是 text 和 max_length输出是 summary 和 source_length。如果输出还要包含耗时就再加一个 processing_time。这些字段一旦被多个 Agent 使用后续改结构会非常麻烦。一个简单的输入 schema 示例{ name: text_summary, description: 对长文本生成摘要, parameters: { text: {type: string, required: true}, max_length: {type: integer, required: false, default: 200} }, output: { summary: string, source_length: integer } }有了这个 schemaAgent 在路由时会更容易给出正确参数也方便做参数校验。在代码里可以增加一个通用校验函数在调用 Skill 前先检查必填字段是否存在。这样很多低级错误会在进入业务逻辑前就被拦截。3.2 用注册表管理多个 Skill当 Skill 数量多起来不能一个个手工 if-else 调用。注册表是一个很轻量的方案。它本质上是一个字典key 是技能名value 是执行函数。通过 register 装饰器把技能自动挂进表里。前面已经见过注册表代码。这里补充一个 list_skills 接口def list_skills(): return [ {name: name, schema: skill_schemas.get(name, {})} for name in skills ]这个接口的价值在于以后无论是让大模型选择技能还是做单元测试都可以遍历这张表。你不需要维护一份手工文档每个技能注册时就应该把描述和参数带进来。直接让 Agent 看到这张列表它才知道自己有哪些能力可用。有一个细节要注意技能名尽量使用英文小写加下划线比如 text_summary、weather_query。因为在大模型路由结果中中文名字可能被截断或误拼英文小写更稳定。展示给用户时可以做一层中文映射但内部标识保持简单。3.3 让 Agent 决定用哪个 Skill有两种常见路由方式。第一种是规则路由。根据用户任务中的关键词直接匹配技能。比如任务里出现“天气”就调用 weather_query。这种方式写起来最快适合技能数量少、业务规则明确的小项目。缺点是规则多了之后难以维护用户换一种说法就匹配不到。第二种是让大模型做路由。把 list_skills 的输出转成 JSON 列表塞进提示词要求模型返回一个包含技能名和参数的对象。示例提示词你是任务路由助手。请根据用户请求和可用技能列表返回 JSON 对象 {skill: 技能名, arguments: {...}} 可用技能列表 {skills} 用户请求 {user_input} 只返回 JSON不要额外解释。这种方式更灵活但新增了一个模型调用会有一定耗时和失败概率。如果路由调用失败可以退回规则匹配。实际项目里我会把两种方式结合先尝试规则匹配匹配不到再用大模型路由。这样既能降低调用成本也不会因为模型抽风导致整个 Agent 不可用。3.4 错误处理和日志要一起写Skill 开发里最容易忽略的是错误处理。你没有统一捕获异常时只要一个技能报错整个 Agent 任务就会中断。批量任务时更惨前面跑几十条都正常后面一条输入数据格式不对进程直接退出前面的结果也没保存。更稳妥的做法是在调用层统一捕获异常并返回结构化错误def safe_call(skill_name, inputs): if skill_name not in skills: return {error: fskill {skill_name} not found, status: error} try: result skills[skill_name](inputs) return {status: ok, result: result} except Exception as exc: return { status: error, error: str(exc), skill: skill_name, inputs_size: len(str(inputs)), }同时日志里要记录关键信息调用时间、技能名、输入大小、返回状态、耗时。这不是为了好看而是出问题时只有日志能还原现场。比如“模型返回空字符串”可能是因为输入文本超长被截断也可能是因为系统提示词要求返回 JSON 但模型理解偏了。没有日志你只能一次次重复跑非常耗时间。4. Agent Skill 和 MCP 有什么区别怎么选4.1 两者解决的问题不同Agent Skill 和 MCP 是最近经常被一起讨论的两个概念。不少人把它们当成同一类东西其实是两个层次。MCP 的全称是 Model Context Protocol它是一套标准化协议解决“不同工具怎么被模型统一调用”的问题。你可以把它理解成 USB 接口外部工具按照协议暴露自己的能力模型侧按协议连接两边不用关心对方具体怎么实现。它关注的是工具接入的标准化。Agent Skill 更偏向应用层解决“一个任务能力怎么被封装、组合和复用”的问题。它关注的是业务逻辑和 Agent 的决策流程。一个 Skill 内部可以调用多个 MCP 工具也可以不调用任何 MCP 工具直接写函数。举例来说文件管理是一个工具能力MCP 可以暴露 read_file、write_file、list_files 这些接口。而“整理会议纪要”是一个技能它内部可能需要先读文件、再做摘要、再写回文件。MCP 负责让每个动作可被模型调用Skill 负责把多个动作编排成完整业务能力。4.2 实际项目中是怎么配合的两者不冲突可以搭配使用。如果你已经有外部系统需要接入比如数据库、邮箱、文件服务器可以先通过 MCP 服务把接口标准化让模型能够访问。然后再在应用层写一个 Skill内部组合这些接口完成一个具体业务。如果你只是在一个小项目里做文本处理完全不需要引入 MCP。直接写一个 Python 函数注册成 Skill就可以让 Agent 调用。因为 MCP 的引入会增加调试成本你要部署服务、维护协议版本、处理鉴权。小项目用不上这些早点跑通核心链路更重要。从开发顺序上看我建议先写函数型 Skill等到出现“多个客户端要复用同一套工具、不同编程语言都要接入”的需求时再把工具层升级成 MCP。先解决业务再谈架构。4.3 选择建议维度函数型 SkillMCP 标准化接入适用场景单项目、原型验证、小团队多客户端、多语言、工具复用开发成本低中高调试难度低中典型示例text_summary、weather_query文件操作、数据库查询、邮件服务这里要给一个提醒不要为了概念而引入协议。如果你的项目里只有两三个技能直接写函数反而更清晰。等到工具数量超过十个、或者系统需要在多个 Agent 之间共享工具能力时再考虑标准化层收益会明显很多。5. 批量任务和生产化从“能跑”到“可以长期用”5.1 单任务跑稳了再考虑批量不少人在开发完一个 Skill 后第一反应是赶紧批量跑数据。我的经验是先跑三条样例确认输出、命名、耗时都正常再放大规模。直接批量跑大概率会出现输入格式不一致、某个字段缺失、API 限流、文件写入冲突这些问题。批量任务不是把单任务放进 for 循环就完事。你需要多考虑三件事任务标识、失败重试、输出保存。没有任务标识你没法知道哪条成功、哪条失败没有失败重试一条脏数据可能让整批任务中断没有输出保存进程一断结果全丢。5.2 批量输入、任务标识和失败重试一个比较稳妥的批量示例import json import time batch_tasks [ {task_id: 001, text: 第一段需要摘要的文本可能来自不同来源。}, {task_id: 002, text: 第二段需要摘要的文本。}, ] results [] for task in batch_tasks: try: result skills[text_summary]( {text: task[text], max_length: 100} ) results.append({task_id: task[task_id], status: ok, result: result}) except Exception as exc: results.append({task_id: task[task_id], status: error, error: str(exc)}) # 避免请求过快触发限流 time.sleep(0.1) with open(results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2)这里的关键点有几个。task_id 用来对账不能省略。time.sleep 是给 API 限流留缓冲具体间隔要根据你用的模型服务调整。异常捕获要放在单条任务内部不能因为一条失败就让整个循环退出。输出文件建议按批次命名比如 results_20260201_1200.json避免覆盖之前的结果。如果你的任务量很大比如几千条建议每处理 50 条就增量写一次结果。这样进程意外中断时丢失的只是最近一小批而不是全部。这个习惯在真实生产里非常重要。5.3 是否需要引入队列不是所有批量任务都需要消息队列。几十条任务用循环加 sleep 就够了。几百条任务如果处理时间不长也可以继续用循环。真正需要队列的场景是任务到达时间不固定、多个消费者需要并发处理、失败任务需要自动重试或者单任务处理时间很长。即使不引入队列你也要做两件生产化基础工作。第一是日志稳定输出最好写文件而不是只打印在控制台。第二是任务幂等同一批数据重复跑时不要产生重复结果。比如每次处理前先检查 task_id 是否已经存在于结果文件存在就跳过。这个简单的检查能帮你省掉很多麻烦。我见过很多项目第一步就上高并发结果问题全堆在一起API 限流、日志乱序、结果重复。先跑单条再跑小批量最后再考虑并发和队列。这个顺序虽然慢一点但排查成本最低。6. 常见报错和排查顺序6.1 先看现象再猜原因遇到问题先别急着改代码或调参数。先判断现象属于哪一类因为不同现象对应完全不同的排查路径。现象优先检查项无输出日志、API 错误、输入是否为空直接报错依赖版本、路径权限、参数类型任务卡住网络超时、等待用户输入、死循环输出格式不对提示词、输出 schema、字段映射比如“无输出”很多人第一反应是模型出问题了。但更常见的是输入文本为空或者 API 返回了错误但你没打印出来。这时候应该先看日志里有没有请求和响应记录再逐层排查。6.2 排查顺序输入、环境、参数、Skill我习惯按这个顺序排查先看输入。这个 Skill 接收到的 inputs 到底是什么字段名有没有拼写错误必填字段有没有传最大长度有没有限制再看环境。依赖版本是否安装成功环境变量是否读取到文件路径是否有权限代码是从项目根目录运行还是别的目录再看参数。并发数、超时时间、max_length 这类参数是否合理会不会因为单条任务处理太慢触发了某个服务的超时最后看 Skill 本身。执行函数内部有没有 bug是调 API 的代码出错还是处理返回结果的代码出错举例来说模型返回空字符串不要立刻去改提示词。先看请求日志里有没有完整的请求体再看输入文本是否超过模型上下文长度最后看解析返回结果的代码是否把字段名写错了。很多时候问题出在最后一步。另一个常见问题是“批量任务越来越慢”。原因不一定是模型处理能力不够可能是结果文件越来越大或者日志写入使用同步模式阻塞了主流程。你可以在每批次里打印处理耗时看看是整体变慢还是某个技能变慢。6.3 容易误判的两个点第一Skill 输出效果不好不一定是模型能力弱可能是 Agent 没有把参数传对。比如技能需要 text 字段Agent 路由时传成了 content技能内部取出的是 None最后只能返回空结果。这时要检查路由结果而不是反复调提示词。第二一次运行成功不代表可以上线。你只测试了一条理想输入没有覆盖空值、超长文本、特殊字符、重复任务。所以我在正式批量前会准备一个包含正常、边界、异常三类样本的小测试集。跑通后再对输出格式做一次校验确保每条结果都是可解析的 JSON而不是夹带了解释文字。Agent Skill 的关键价值是把大模型不可控的部分隔离在提示词里把能确定的部分变成可测试、可复用、可维护的代码。我个人的建议是先把单任务跑稳再考虑批量和接口。如果一个技能连三条测试都过不了堆再高的并发、再多的协议也只是把问题放大。真正落地时盯住