做过 Agent 项目的人应该都有同感模型选型、上下文管理、工具调用这些事折腾到最后往往不是模型不够聪明而是它“不会干活”。你给它一个目标它能把计划说得头头是道但一落到具体操作——查数据、调接口、改配置、发消息——就开始胡来或者卡住。这其实就是缺了 AI Skills 这一层。我最近在腾讯云上把一个内部工具改造成了带 Skill 体系的 Agent从“什么都能聊”变成了“叫它干啥就能干成啥”整个过程踩了不少坑也把 Skills 的正确打开方式摸清楚了。这篇就聊聊我总结出来的最佳实践。我默认看这篇文章的你已经大致了解 Agent 是什么但还没想清楚怎么把 Agent 从“聊天玩具”做成“干活员工”或者已经在腾讯云上跑过 Agent但总觉得它不够可控、能力不够用、扩展起来很别扭。我会从思路、环境准备、Skill 设计、完整案例到问题排查一步步讲尽量让你照着走也能搭出一套自己的方案。1. 先把 Agent 当“实习生”带理解 Skills 在整体架构里的位置1.1 为什么你需要的不是更聪明的模型而是更清晰的技能包很多人一开始做 Agent所有指令都往 system prompt 里塞什么“你是一个专业助手你可以查天气、发邮件、操作数据库、生成周报……”然后期待大模型自己悟出怎么用工具。实测下来Prompt 一长模型就开始“精神分裂”要么答非所问要么工具调用的参数乱传要么干脆自己脑补一个结果返回给你。后来我把这套思路换成了“实习生”管理模式。你想想一个新人入职你不会把公司所有规章制度一次性念给他听而是给他一本岗位 SOP每项任务对应什么流程、需要什么输入、调用什么系统、出错了找谁。AI Skills 就是这本 SOP——把 Agent 的某项具体能力封装成一个有“操作说明书”的独立模块。Agent 只负责理解用户意图然后把具体执行权交给匹配的 Skill效率和稳定性能提升几个量级。这套思路放到腾讯云上特别顺因为 Skills 本质上就是“把 Agent 与大模型之外的真实世界连接起来”的中间层。无论你是用云函数做 Skill 的服务端还是用 API 网关统一暴露接口或者把 Skill 的定义文件放在对象存储里动态加载腾讯云的整套 PaaS 能力刚好能承接住。1.2 Agent 和 Skill 的关系以及框架选型的一点点思考Skill 和 Agent 的区别网上讨论很多。我的理解很简单Agent 是“大脑 调度中心”负责理解、规划、决策Skill 是“手和脚”是完成某个具体任务的可执行能力单元。Agent 可以临场发挥但 Skill 必须稳定可靠——用户跟 Agent 说“帮我把这份合同里的关键条款提取出来”Agent 负责拆解任务真正干活的是一套“合同解析 Skill”。这个划分直接决定了代码怎么写。Agent 层代码往往很薄读配置、拼上下文、调模型、按路由规则分发任务。Skill 层才是重头戏每个 Skill 包含独立的 Prompt 片段、输入输出 Schema、对应工具/API 的调用逻辑、错误处理策略。这样 Agent 新增能力不需要改核心代码只需要“安装”一个新的 Skill 包这跟给电脑装软件是同一个道理。至于框架我看到圈子里的讨论越来越成熟。自研派用 LangGraph、Semantic Kernel、Microsoft Agent Framework、CodeBuddy Agent SDK 这类底座低代码派用 Dify、Coze 或者腾讯云上的智能体平台。我自己是混合路线Agent 编排用成熟的 Agent FrameworkSkill 全部自己定义标准协议。这样既不用重复造“调度”的轮子又能保证 Skill 的格式和交互逻辑完全可控。我建议新手别一上来就研究各种花哨框架先手工写 2 到 3 个 Skill把套路走通再考虑引入框架统一管理。2. 动手前先盘清楚腾讯云这边的“物料清单”2.1 你需要准备哪些云资源以及各自的作用把 Agent 部署在腾讯云上和部署一个普通后端服务不太一样你要准备的东西大概有这几类算力载体、接口暴露层、存储、密钥管理、日志与监控。算力载体我首选云函数 SCF。Agent 的 Skill 调用通常是短平快的云函数按调用次数和运行时长计费空闲时不花钱比较适合这种场景。如果是常驻的 Agent 服务比如你自己起了 LangGraph 的服务端那可以买一台轻量服务器把 Agent 主服务跑在 Docker 里Skill 的独立功能再拆到云函数里也是可以的。接口暴露层上如果 Skill 需要开放给外部业务系统回调用 API 网关统一前置如果只是 Agent 内部调用直接用云函数的 HTTP 触发器或 SDK 触发就行。存储方面Agent 的技能定义文件、会话日志、中间数据集放对象存储 COS 准没错便宜、生命周期管理方便后面接记忆功能时还要配一个向量数据库。密钥这块千万别省数据库账号、API Token 一定要用云上的密钥管理系统比如凭据管理系统托管不要直接写死在函数代码里。2.2 常见误区不是所有端口都要开也不是所有服务都要上公网看到很多刚上手的朋友买了服务器第一件事就是把所有端口都放行或者在云函数里配置成“允许所有来源调用”还觉得这样调试方便。这是一个我非常不建议的坏习惯。安全组和访问控制的意义不是“限制你”而是“保护你”。Agent 的 Skill 一旦暴露成公网接口就不仅仅是你自己调用了——扫描工具、恶意请求、数据爬虫都会顺着端口找上门。正确的姿势是只开放确实需要公网访问的端口比如 80/443走域名 HTTPS其余的用内网 IP 互调或腾讯云 VPC 内部通信。API 网关层面加鉴权云函数走函数鉴权或私有网络访问。如果你只是本地测试直接用云函数控制台的测试功能就行完全没必要把所有端口对公网敞开。2.3 本地先跑通再上云一次让我印象深刻的联调事故这里我多说一句很多 Agent 项目死在“直接上云”。之前有个同事代码在本地明明好好的部署到云函数后就是报错日志一片空白查了半天发现是他本地读的是相对路径文件而云函数的运行环境是只读的 /tmp 之外的目录都不能写。这就是典型的本地环境和云端环境不一致。我的习惯是先把 Skill 的核心逻辑在本地跑通——用 Docker 模拟一个接近云函数的运行环境写好单元测试和集成测试然后再部署到腾讯云。整个过程可以参考这个顺序本地 mock 外部依赖 - 本地真实调用第三方 API - 云函数本地调试插件 - 云端测试。每一步都验证通过再进入下一步能省掉大量“盲人摸象”式的定位时间。3. 把能力拆成 Skill核心设计方法论与实操3.1 Skill 描述文件怎么设计才能让模型“看得懂”每个 Skill 本质上是一份“给大模型看的说明书”。你可能会觉得既然是给模型看的那自然语言写好不就行了对自然语言很重要但不代表不需要结构化。一个我在生产环境验证过多次的 Skill 描述至少要包含以下字段skill_name、description、when_to_use、input_schema、output_schema、examples。重点是 description 和 when_to_use这两个字段是模型决定“要不要调用这个 Skill”的唯一依据。比如我写过一个小工具库里面有一个“查询订单物流”的 Skill我一开始的描述是“订单物流查询”结果模型经常把普通商品信息查询也路由到这个 Skill 上。后来改成“当用户主动询问某个订单物流轨迹或快递进度并提供订单号或快递单号时使用。普通商品咨询请勿使用本工具。”效果立刻好转。不要觉得描述越长越好而是要精准描述边界和触发条件。input_schema 和 output_schema 我建议用 JSON Schema 定义字段名、类型、是否必填、取值范围都给全。模型的参数抽取能力再强也需要一个清晰的“填空模板”。给个实际例子{ skill_name: query_express, description: 根据订单号或快递单号查询最新的物流轨迹, when_to_use: 用户询问‘我的快递到哪了’‘物流进度’‘订单什么时候送达’时使用普通商品详情咨询请勿使用, input_schema: { type: object, properties: { order_id: { type: string, description: 订单号通常以字母开头如 JD123456789 }, express_no: { type: string, description: 快递单号纯数字或字母数字混合 } }, oneOf: [ { required: [order_id] }, { required: [express_no] } ] }, output_schema: { type: object, properties: { status: { type: string, enum: [in_transit, delivered, exception] }, latest_track: { type: string }, track_list: { type: array, items: { type: string } } } } }注意这个oneOf的用法模型看到两种参数都可能缺但至少得给一个它抽参时就会更严谨。同理output_schema 里把返回的枚举值写清楚模型就更容易把执行结果准确地转述给用户。3.2 技能注册和路由为什么我不用“平铺所有 Skill”的方式如果你只有三五个 Skill那把描述全部塞给模型、让它自己选问题不大。但我测试下来Skill 数量超过十个之后把全部描述拼进 Prompt对 Token 的消耗、模型的选择准确率都是不小的挑战。你会发现模型开始“眼花”该用 Skill A 的时候非要用 Skill B尤其两个 Skill 描述相似时特别容易翻车。所以我用了一个“两级路由”的结构先把 Skill 分成几大类比如【查询类】【处理类】【通知类】。Agent 收到用户请求后第一轮先判断这是哪一类第二轮再在对应类别下选具体 Skill。描述相似的两个查询类 Skill因为第一轮已经把范围缩小第二次选择的干扰项就少了。这个思路和检索里的“粗排 精排”有点像效果非常明显。另外Skill 必须做“失败兜底”当模型犹豫不决时我给它一个固定的 fallback 规则比如“无法确定使用哪个 Skill 时优先调用 default_reply 技能告诉用户需要提供更明确的信息并提供可执行的选项”。没有兜底规则的话模型经常会出现灵异行为——明明没有匹配的 Skill它也能自己想象出一个结果来“演”给你看。3.3 记忆、上下文和 Skill 的配合不把记忆塞给每个 Skill关于 Agent 的记忆很多文章讲得玄乎。我的实践经验是短期对话记忆放 Agent 层长期记忆外置到向量库切勿让每个 Skill 自己维护状态。举个具体场景文件归档助手用户先问“帮我整理昨天上传的发票”然后再问“把金额大的几个挑出来”第二句话没有出现“发票”这个实体词它依赖的是短期对话记忆。这种记忆Agent 层用滑动窗口就能解决不劳烦 Skill。长期记忆的作用是识别用户的偏好和模式比如某个用户每次上传文件都喜欢按“YYYY-MM/项目名称”的路径归档。那 Agent 就应该在归档时主动套用这个偏好。实现方式很简单在 Skill 执行完后把用户意图、参数、该用户的历史偏好摘要写进向量库下次同用户触发另一个 Skill 时先从向量库里检索几条相关历史记录作为 System Context 的一部分。这个设计的关键点在于Skill 保持“无状态”每次执行都是一次干净的调用记忆只是作为上下文注入而不是让 Skill 内部去查历史、猜用户想法。这样 Skill 的测试和维护成本就低很多因为你不需要构造“前几次对话后的状态”就能单测。很多 Agent 项目后期 Bug 频出就是因为在 Skill 里偷偷塞了状态导致复现问题极其困难。3.4 把 Skill 包传到 COS让 Agent 的能力可以动态装卸Skill 设计好了怎么管理一开始我是把 Skill 描述直接写死在代码里每次加一个 Skill 都要重新发版。加了五六个以后就受不了了于是我把 Skill 定义做成了独立 JSON 文件打包上传到 COS 的固定目录下Agent 启动时拉取清单运行中还可以定期刷新。这样做的好处非常直接运营同学改一套话术模板不需要动代码上线一个新 Skill只要把 JSON 定义和函数代码传上去再把 COS 里的配置加一项Agent 下次同步时就能“学会”新能力。配合 COS 的版本管理功能哪个版本出了问题还可以一键回退。如果你有更复杂的需求还可以做分级发布先在内部群里让测试 Agent 加载灰度 Skill确认没问题再全量放开。4. 完整案例在腾讯云上养一个“文件归档 Agent”4.1 需求拆解这不是一个简单的上传工具为了把上面的方法串起来我以一个实际做过的“文件归档 Agent”为例。它的核心任务是把用户丢过来的各种文件截图、PDF、Word、表格、原始代码片段自动识别内容、打标签、然后存到指定的 COS 目录里并在最后给用户发一条归档摘要。听起来不复杂但你要是一股脑把“文件识别 标签提取 存储操作 摘要生成 消息通知”全部塞给一个大模型函数去处理马上就会遇到问题识别出来的标签格式不稳定、存储路径时对时错、摘要有时是中文有时是英文。拆成三个 Skill 就好办多了Skill A文件内容解析与标签提取。输入文件 URL输出文件类型、标题、关键词列表、内容摘要。Skill B归档路径决策与存储。输入标签列表、文件元数据根据预置规则比如按月份/业务线计算 COS 路径执行存储返回访问链接。Skill C归档结果通知。输入归档摘要、链接决定这套摘要怎么发送发到企微群还是站内信取决于配置。每个 Skill 独立测试再让 Agent 负责任务编排“用户丢文件 - Agent 调 A - 拿结果给 B - 拿结果给 C - 汇总回复用户”。这就是 Skills 的威力模型只做决策和串联脏活累活由 Skill 干。4.2 Skill A 里的关键前处理从文件 URL 到结构化信息我只讲讲最容易翻车的地方。Skill A 的第一件事是根据文件扩展名和 Content-Type 判断该走哪条解析通道。图片类走 OCRPDF 走文档解析代码片段则直接按文本处理。刚开始我用了一个“万能解析模型”结果图片文字多时效果差强人意、代码文件会被转义成奇怪格式。后来老老实实上了多路解析。这里有一个腾讯云上常用的组合方案文件先落在 COS触发云函数事件云函数里根据文件类型选择调用 OCR 接口或者文档解析服务。拿到原始识别文本后再交给大模型提炼标签。注意不要让大模型直接去读图片的二进制内容第一是 Token 开销太大第二是很多模型对多图的识别稳定性不如专用 OCR。正确做法是专用模型OCR/ASR/解析工具负责把非结构化数据转成结构化文本大模型负责“理解提炼”各司其职。提炼这步里我加了几个“强制输出项”标签数量限制在 3 到 8 个关键词必须是原文里出现的词摘要不超过 50 字。因为模型一旦自由发挥下游的归档规则就不好匹配会出现同一个文件今天打上“发票”明天打出“收据”归档路径自然也就乱了。4.3 Skill B 的路径决策宁可保守不要灵活Skill B 的职责是“把文件放对位置”。很多人会觉得既然有标签了那让大模型根据标签“智能”决定放哪不就行了我试过结果可以用“随心所欲”来形容。模型觉得今天是 2026 年 5 月就把文件放到 2026-05 目录下但实际上这批文件是 2024 年的合同归档逻辑被彻底带偏了。所以我后来把归档规则从“模型自由决策”改成了“规则引擎 模型填充”。意思是归档路径的模板是提前配置好的比如/{业务线}/{年份}/{月份}/{文件类型}/。Skill B 只负责从文件内容和标签里抽取出业务线、年份、月份、文件类型这几个槽位值然后拼路径。槽位抽不出来时宁可把文件放到_pending_目录等人来处理也不要自己拍脑袋生成路径。这个思路我也建议你应用到其他类似的 Skill 里凡是下游系统对格式有严格要求的字段不要让模型直接输出最终结果而是让模型输出“槽位”再用确定性代码拼装最终结果。模型出错了可以让人一眼看出来而不是直接污染下游数据。4.4 Skill C 的通知一个被很多人忽略的失败点最后是通知 Skill。一开始我以为这不就是个 HTTP 调用吗有什么难的。实际跑起来才发现最大的问题是“调用了但没人知道调用失败了”。企微机器人有频率限制如果 Agent 在短时间内往同一个群里发了多条归档通知后面的消息会被限流丢弃而 Skill 返回给 Agent 的状态还是“成功”。我后来在通知 Skill 里设计了三层确认第一层判断消息长度和类型超长的走文件形式发送不直接发正文第二层捕获腾讯云 API 返回的业务错误码码比如限流就自动退避重试三次第三层发送后主动拉取一条回执确认消息真的送达了而不是只看 HTTP 200。这个“结果校验”思维特别重要凡是调用外部系统都要避免把“请求发出去了”等同于“事办成了”。4.5 联调时我用来定位问题的一个笨办法整套 Skill 开发完联调是免不了的。但我发现Agent 跑出错的时候定位问题比普通后端更难——因为中间隔着一层大模型的“自由发挥”你可能都不知道它有没有调用 Skill、调用的参数是什么。所以我在 Agent 层加了完整的 trace 日志每条用户消息、Agent 思考过程、Skill 选择结果、Skill 入参、Skill 出参全都记录下来。腾讯云的日志服务在这里帮了大忙。把 Agent 的 stdout 结构化日志直接打到日志服务里配上关键词检索和可视化面板。查问题时我一般是搜“skill_name归档 存储”然后看这条日志前后的 trace。比如用户问“把我的 file 存了”模型没提取出业务线字段直接把归档路径判断成了_pending_——通过 trace 一眼就能看出是抽参的问题还是路由的问题不用去猜。5. 常见问题排查与踩坑实录5.1 Agent 死活不调用设计好的 Skill这是新手最容易遇到的问题。代码写得没问题Skill 也在清单里但用户提问时模型就是不调用。我排查过几次原因基本集中在三处。第一处是 Skill 的描述太含糊。描述里只有“某某工具”没有说明“什么场景下用、什么场景下不用”。模型不知道何时该调用自然就不调用。第二处是用户消息里的实体和 Skill 输入字段对不上比如 Skill 要求“订单号”用户只说“我那个蓝色包装的东西到哪了”模型无法抽参就直接放弃了。第三处是系统提示词里写了“你可以与用户自由聊天不必使用工具”这会给模型一种“能聊就聊不用干活”的暗示。解决办法也很直接给每个 Skill 至少配 3 个触发示例而且示例要覆盖用户可能的不同说法。然后把系统提示词里那种“自由散漫”的表述删掉明确写“当任务涉及文件处理时必须先调用对应 Skill”。5.2 参数传递错乱和幻觉字段Skill 调用时传参不对比不调用好排查一些但也容易让人抓狂。我遇过模型把“文件大小”当成“文件数量”传进去的还遇到过它自己脑补了一个“file_typepdf”但实际是 PNG 文件的。这里有两个关键手段。一个是 Schema 里把字段描述写得更细比如“file_url文件在 COS 上的完整 HTTPS 地址不是文件名”。另一个是在 Skill 内部做参数强校验不满足要求直接返回“参数错误”把问题抛给 Agent 让它重新抽参或向用户追问。不要让 Skill 内部将错就错地执行下去这会把错误蔓延到下游。也建议你在 Agent 层加一个“参数确认”环节当某个 Skill 的参数置信度不高或参数值比较异常时Agent 先向用户反问一句“你确认是这个文件吗”。多一次确认后面能少很多返工。虽然会增加一点交互次数但对于归档、支付、发送消息这类容错率低的操作值得。5.3 云函数冷启动导致 Skill 响应超时云函数按量扩缩容的特性决定了它存在冷启动。Skill 如果依赖比较大的依赖包比如文档解析库、OCR SDK冷启动时间可能达到几秒Agent 那边的等待容易超时。我一开始把解析文件的整个 process 都塞进云函数冷启动经常 3 到 5 秒体验直接崩。后来做了两个优化第一把依赖分成核心依赖和延迟加载依赖初始化时只加载必要的需要在具体请求时才 import 的模块放到函数内部按需加载第二给云函数配置了预置并发让几个热实例常驻扛住日常流量。如果还慢那就说明这个 Skill 不适合用云函数承载应该拆成常驻服务。选型要匹配场景不是所有能力都硬塞到函数计算里才叫“无服务器”。5.4 问题速查表现象常见原因解决方案Agent 从不调用 Skill描述和触发条件不清晰补全 when_to_use加入 3 个以上触发示例调用了但参数乱传JSON Schema 字段说明不具体给每个字段写清楚含义、取值范围、来源Skill 返回成功但业务没生效只看了 HTTP 状态码没看业务回执增加业务级结果校验和重试机制云函数执行很慢冷启动 依赖加载过长按需加载依赖、配置预置并发、评估换常驻服务日志查不到调用链Agent 层和 Skill 层日志没有串起来输出结构化 trace带全局 request_id本地正常云端异常环境不一致比如文件系统只读用 Docker 模拟云环境写测试用例再上云5.5 安全配置的几条红线说到安全问题我归纳下来就这么几条红线第一密钥永远不要放在代码或镜像里统一放凭据管理系统云函数运行时通过环境变量或 API 动态获取第二Skill 的公网入口必须走认证至少是 API 网关的密钥对最好再做一层自定义鉴权第三上传文件类 Skill 一定要限制文件类型和大小并对文件内容做检测别让恶意文件打到后面的解析服务第四Agent 的执行权限遵循最小化原则COS 写权限只授给指定目录不要给整个存储桶数据库账号只给执行必要 SQL 的权限。上面这些条不是“大厂才需要考虑的事”。我见过一个小项目因为 Skill 的鉴权没做好被人刷了几千次 OCR 调用账单直接爆掉。安全意识这种东西越早刻进肌肉记忆后面越省心。6. 我的一些体会Agent 养成不是一次开发而是持续喂养这个“文件归档 Agent”从原型到稳定运行前后差不多三周。真正让我觉得它变得“好用”的不是某个瞬间的技术突破而是后续持续补充 Skill、修正描述、调整参数 schema 的过程。第一周觉得 Agent 蠢得要命现在回头想蠢的其实是我——很多边界没定义清楚很多输出没校验只顾着给它画大饼让它自由发挥。所以如果你现在也在做 Agent我的建议是先别追求“全能”而是把它先养成一个只擅长两三件事的“专才小助手”。这两三件事做成闭环用户说人话 - Agent 听懂 - 调用 Skill - Skill 干成 - 结果确认 - 反馈给用户。把这条链路跑到 90% 以上的成功率再去横向加新的 Skill 让它越来越“全能”。这种增量养成的路径比一开始就设计一个几十个 Skill 的宏大系统要靠谱得多。最后再分享一个容易被忽略的小技巧Skill 的迭代记录一定要留好。现在每个 Skill 都像一个小版本库描述文件改了 v1.2、v1.3哪怕只是加了个“当用户提到 XX 时优先使用本工具”的触发条件也要记录原因。等到 Skill 多到几十个的时候你会发现版本历史就是最好的调参依据它能告诉你每一个改动到底带来了多少效果提升而不是凭感觉瞎调。