从“会写提示词”到“真能干活”中间隔着整个 Agent 工程化。这篇我拿腾讯云 AI Skills 当一个完整案例来拆从 Skills 该怎么规划、怎么写到怎么把 Skill 变成一个能独立决策的 Agent再到上线后遇到的各种坑一次性讲透。1. 整体设计思路为什么选 AI Skills 而不是硬编码流程很多人在做 Agent 时有个误区一上来就写一堆if-else把业务流程写死或者把所有工具调用塞进一个巨大的 prompt。这样做的代价在后期会集中爆发。我见过一个项目一个 prompt 里塞了十几个工具的说明模型经常在工具选择上犯迷糊这周修好了下个版本换了模型又翻车。腾讯云 AI Skills 这套体系解决的正是这个问题。它的核心思想是把 Agent 的能力按“技能”拆分每个 Skill 只负责一件完整的事Agent 本身则是一个编排器负责根据用户的意图去发现技能、组合技能、完成任务。这个思路其实和微服务架构非常像只不过微服务拆的是后端服务AI Skills 拆的是模型能力的执行单元。举个例子。假设你想做一个“文章自动发布 Agent”它可以读取你上传的文档提取核心内容判断适合发到哪个平台自动配图最后生成发布文案并推送。如果不用 Skills你的 prompt 会变得非常臃肿而且每扩展一个新平台就要改动整个 prompt。用 AI Skills你可以把“文档解析”做成一个 Skill把“平台适配”做成一个 Skill把“文案生成”做成一个 Skill把“发布执行”做成一个 Skill。Agent 拿到用户输入后自己去判断该调用哪些 Skill、按什么顺序调用每个 Skill 内部只关心自己的输入输出。我在实际项目中总结过一条经验一个 Skill 的职责边界应该以“一个用户可感知的完整功能”为最小单位。“读取文件”不能算一个 Skill因为它不是一个完整的用户任务“解析文档并生成摘要”才算。判断标准很简单——如果用户说“把这篇文章总结一下”Agent 能通过这个 Skill 独立完成回应那这个 Skill 就是合格的。另外Skills 设计还有一个隐蔽的好处可测试性。单独一个 Skill 的输入输出是可控的出了问题你知道去查哪个 Skill而整套流程出了问题你可以逐段验证。没有这层拆分调试 Agent 就像在黑暗里摸象哪里坏了根本看不出来。2. 从“工具调用”到“技能编排”的认知升级2.1 先说清楚 Skill 和 Agent 的区别这是我觉得所有人最容易搞混的地方。Skill 是能力Agent 是决策者。Skill 解决的是“能做什么”Agent 解决的是“该做什么、怎么做、先后顺序如何”。你写了一个“调用天气预报 API”的 Skill这个 Skill 自己永远不会知道用户想不想知道天气只有当 Agent 判断出用户的意图是“问天气”时这个 Skill 才会被激活。用大白话说Skill 是工具箱里的螺丝刀Agent 是用螺丝刀的人。螺丝刀不会自己拧螺丝但人也得有合适的螺丝刀才能把活干好。腾讯云 AI Skills 的设计里这两者天然是解耦的Agent 通过自然语言或结构化描述去“发现”SkillSkill 通过清晰的描述信息告诉 Agent“我能做什么、什么时候该用我、需要什么参数”。这个设计有个很关键的工程意义Skill 可以被复用和共享。团队里有人写了一个很好的“数据图表生成 Skill”其他人创建的 Agent 也能直接挂载这个 Skill不需要重复造轮子。长线来看你的 Skill 库会越来越庞大新 Agent 的搭建成本会越来越低这就是组合复利。2.2 什么时候应该做 Agent什么时候不需要我必须泼一盆冷水并不是所有场景都需要 Agent。如果一个任务的流程是完全固定的比如收到工单→判断类型→自动回复那用传统的 workflow 就够了引入 Agent 反而会让系统不稳定因为大模型的决策有随机性你很难保证每一次都走同一条路。需要 Agent 的场景有几个典型的特征意图是开放的、步骤是不固定的、输入是杂乱的。比如“帮我安排今天的日程包括查天气、看路线、订餐厅”这类任务没法写死流程因为用户的表述千变万化场景组合也千变万化必须由模型来理解意图、编排技能。腾讯云的 AI Skills 平台本身就支持 workflow 和 Agent 两种形态如果你的任务偏固定建议先用 workflow 串起来只有当分支太复杂、意图太多变时才把决策权交给 Agent。我个人的建议是从最小可用的 Agent 做起不要一开始就想要做一个“全能助手”。先把一两个核心场景跑通后面再慢慢加 Skills。Agent 最怕的就是能力太杂但每个都浅用户试一次不满意后面就不会再用了。3. 核心细节拆解设计一个高质量 Skill 的完整流程从一个想法到一个能跑的 Skill中间有几个关键步骤我逐个拆开讲。3.1 第一步定义技能的目标与边界动手写 Skill 之前先回答三个问题这个 Skill 解决什么类型的用户请求这个 Skill 不解决什么它的输入是什么、输出是什么就我以前写“周报生成 Skill”的经验来说一开始我把边界定得太宽——什么都能干结果用户让它统计项目工时它也往里套。后来我把输入严格要求为“项目列表 每个人的工作内容描述”输出为“Markdown 格式周报”并且明确告诉它“如果用户请求中缺少必要信息先向用户询问”效果就好了很多。边界定义得越清楚Agent 就越知道什么时候该用这个 Skill、什么时候不该用。很多 Agent 表现不佳不是因为模型不行而是因为 Skill 自己都没搞清楚自己该干什么。3.2 第二步把技能逻辑描述清楚这里是容易被忽略的细节。Agent 选择 Skill 不是靠执行代码去试而是靠“看”Skill 的描述信息来做语义匹配。所以 Skill 的描述description写得是否清晰、是否包含触发场景直接决定了 Agent 能不能正确调用它。我见过很多开发者在写描述时只写一句“生成周报”结果 Agent 在用户说“汇总下这周工作”时根本没联想到这个 Skill。改法是把触发场景写进去比如“当用户需要汇总本周的工作内容、项目进度、遇到的问题或请求以周报/月报格式输出报告时使用”。实测后调用准确率有明显提升。另外参数parameters定义一定要用清晰的 JSON Schema。类型要明确、必填项要标清楚、描述要能让 Agent 知道每个参数该填什么。特别是在有枚举值的情况下一定要把可选项列全否则 Agent 可能会凭空捏造一个值导致后续处理直接出错。3.3 第三步写好指令相当于 Skill 的“岗位说明书”在腾讯云 AI Skills 的 Skill 配置里核心就是接点配置包括指令和工具调用。在写指令时有一个技巧可以分享不要只写“干某事”要把处理步骤、边界条件、异常情况的应对都写进去。比如一个“文档翻译 Skill”它的指令可以包含提取原文内容时保持格式不变对专业术语优先使用用户提供的术语表术语表中没有的词汇可根据上下文确定含义如果原文是图片且无法直接提取文字则调用 OCR 工具处理后翻译翻译结果输出为双语对照格式原文在前译文在后。可以看到我把“怎么做”拆成了规则模型看到这些规则后执行起来会稳定得多。Skill 的指令本质上就是一份“给模型看的傻瓜操作手册”写得越具体模型的发挥就越稳定。3.4 第四步测试 Skill 并收集反馈测试阶段要刻意制造极端输入。我在测试“发票信息提取 Skill”时专门丢了几张模糊的照片、倒着的照片、有杂乱的背景的照片看模型的鲁棒性如何。结果发现原版提取逻辑在“模糊照片”场景下会直接报错加了“对图片进行方向矫正和画质增强”的预处理步骤后准确率从七成提到了九成以上。这里尤其要说一下Skill 的维护不是一锤子买卖。模型可能会升级API 可能会变用户的使用习惯也会变。建议给每个 Skill 加版本号记录迭代历史方便回归对比。4. 实现一个可直接复用的 Skill 配置模板这里我把一个比较通用的 Skill 配置模板拆给你们可以直接抄。以“网页内容摘要生成 Skill”为例它做的事情是用户丢来一个网址或一段长文本Skill 抓取内容后生成结构化摘要。4.1 配置 Skill 基本信息Skill 的配置通常包含这几个字段名称name建议用英文短横线命名比如web-content-summarizer方便标识。显示名称display_name给用户看的用中文更友好比如“网页内容摘要生成”。描述description这是给 Agent 看的必须写清触发条件和能力边界。版本号version建议用1.0.0这样的语义化版本号方便追溯。作者author团队内分享时很有用方便使用者联系维护人。具体到本案例描述可以这样写当用户提供一个网址、一段链接或一篇文章的长文本要求“总结、提炼、梳理核心信息、生成摘要”时使用本技能。本技能可以自动抓取网页正文内容并生成包含核心观点、关键数据和结论的结构化摘要。如果用户提供的仅是一句话而不是完整文章请直接回答不要调用本技能。这里特意写了“如果用户提供的仅是一句话不要调用本技能”目的是防止 Agent 误用。4.2 配置输入参数给这个 Skill 配置输入参数时可以使用这样的 JSON Schema{ type: object, properties: { url: { type: string, description: 待摘要的网页链接必须以 http:// 或 https:// 开头 }, content: { type: string, description: 待摘要的长文本内容当 url 未提供时必填 } }, oneOf: [ { required: [url] }, { required: [content] } ] }这里的关键是oneOf这个约束。它告诉 AgentURL 和纯文本二选一不能两个都不填。我在实战中发现参数的“必填校验”是模型最容易出错的地方如果不加约束模型有时会两个参数都不填Skill 执行时只能拿空值去跑最后返回一个莫名其妙的错误。有了oneOf约束后Agent 在调用前就会自己想办法补齐参数。4.3 指令prompt的写法Skill 的指令是核心中的核心。我在这个示例里会这样写你是一个网页内容摘要生成器。你接收一个网址或一段长文本。如果收到的是网址先用 web_fetch 工具抓取页面内容然后忽略广告、导航栏、页脚等无关元素只保留正文部分。如果收到的直接是文本则直接处理。 摘要要求 1. 先给出文章的一句话核心结论。 2. 再分条输出关键要点每条不超过 50 字。 3. 如有涉及数据、人名、金额等关键信息请单独列出“数据摘要”。 4. 输出使用 Markdown 格式。 5. 如果页面内容是英文摘要也用英文输出否则用中文输出。 6. 如果抓取内容超过 5000 字只保留前 5000 字作为输入。注意到第 6 条了吗这是我很早以前踩过的坑。模型有上下文长度限制如果网页内容太长直接把整个页面塞进 prompt必然导致截断或报错。在 Skill 指令里提前限制“只保留前 5000 字”可以让 Agent 在进入模型前就做一次内容裁剪大大降低温度过高的问题。4.4 关联工具调用腾讯云 AI Skills 平台上的 Skill 可以挂载工具。所谓工具可以是平台内置能力也可以是 HTTP 插件。上面这个例子需要调用一个web_fetch工具来抓取网页内容。在配置工具时要注意工具的输入要能和 Skill 的参数对齐。比如web_fetch需要url字段就和 Skill 的url参数绑定。工具调用失败时要设置兜底逻辑。我在指令里通常会写一句“如果 web_fetch 调用失败则返回错误并提示用户检查网址是否可访问。”这看起来是小细节但实际体验会好很多不会让用户面对一堆不知所谓的系统错误。工具调用必然会引入额外的延迟。所以 Skill 里能不用工具就不用工具能用一次工具解决的绝不调用两三次。5. 从 Skill 到 Agent把零散技能串成一个全流程应用Skill 做完了距离“全能 Agent”还差一步——把多个 Skill 挂在 Agent 上并让 Agent 学会什么时候用哪个、怎么组合。5.1 Agent 的“决策大脑”怎么配在腾讯云 AI Skills 平台创建 Agent 时核心要配置的是“指令”部分。这个指令和 Skill 的指令不一样Agent 的指令相当于“主帅的作战方针”而不是具体每个岗位的职责。拿一个“智能内容运营 Agent”来举例。假设它挂载了三个 Skillweb-content-summarizer摘要、article-generator写稿、publisher发布。Agent 指令可以这样写你是一个内容运营助手负责从素材到发布的完整流程。 当用户提供一篇外链文章时你应先用 web-content-summarizer 生成摘要再询问用户是否需要基于摘要生成新的原创文章。 如果用户说“写一篇介绍XX的文章”你应该先判断素材是否足够如果用户没有给素材先向用户索要参考资料或链接。 发布操作必须经过用户确认后才能执行。这里的关键是“流程编排”和“确认机制”。Agent 不能自己决定把内容直接发布出去必须在发布前向用户确认。我见过不少 Agent 因为缺少这种“确认节点”在真实环境里做出了一些不可撤销的操作后果相当麻烦。Agent 的自主性和可控性之间必须要有明确的边界。5.2 编排逻辑怎么写腾讯云 AI Skills 的 Agent 编排支持两种模式自动编排和手动流程编排。自动编排下Agent 根据用户输入自行决定调用哪些 Skill手动流程编排则是你提前指定节点顺序Agent 只负责在每个节点上执行参数填充。我的经验是关键节点建议用手动编排。比如“生成稿件→用户确认→发布”这三步是固定的那就直接在流程编排里把顺序定死Agent 不能跳步。至于“用户说的话该怎么理解、字段怎么提取”这部分信任模型让它自动处理。混合编排是我目前用得最多的方式核心链路固定外围判断交给模型。既能保证安全底线又能让交互灵活。5.3 多 Agent 协作的必要性当流程过于复杂一个 Agent 的指令可能会变得极其臃肿维护成本飙升。这时候可以考虑拆分多个 Agent各自承担一个角色再用主 Agent 做路由。比如“全能内容管家”可以拆成“分析 Agent”“创作 Agent”“发布 Agent”主 Agent 收到用户需求后判断该交给谁处理。这也是为什么我建议在 Skills 设计时就把“技能”和“流程”分开——Agent 层面的编排是基于 Skill 的Skill 本身不该关心自己处于哪条流程。不过多 Agent 的引入也会带来问题通信成本增加、连接处错误率上升、调试复杂度增加。所以我的原则是能单 Agent 解决的绝不上多 Agent只有在单个 Agent 指令超过某个规模上限、或权限隔离要求很高时才考虑多 Agent。6. 云端部署与配置从本地联调到上线注意事项开发完 Skill 和 Agent接下来是部署上线。这个过程涉及腾讯云侧的不少配置我把容易踩坑的点挑出来说。6.1 环境准备与服务开通在腾讯云上Agent 开发依赖 AI 开发平台中“应用”与“模型服务”相关能力。你需要登录腾讯云控制台开通相应的服务。有一个高频问题我先说一句只有在你的账号完成实名认证的情况下才能正常使用这些服务否则云 API 和工具有很多都调不通。如果你的账号注册后提示环境异常、无法注册或无法登录通常和当前网络环境有关。可以尝试更换浏览器、清理缓存或者在手机流量环境下重新操作。我在实际操作中解决过类似问题最后是在清理了浏览器 Cookie 并关闭代理插件后才顺利完成的。6.2 配置部署所需权限无论是调用模型接口还是云函数都有一个前置条件配置好身份凭证。在本地调试时可以用环境变量的方式配置export TENCENTCLOUD_SECRET_ID你的 SecretId export TENCENTCLOUD_SECRET_KEY你的 SecretKey在云端运行时则建议使用角色授权而非永久密钥。我强烈建议不要在生产环境里使用个人密钥管理风险很高。我见过有人把密钥提交到了代码仓库几个小时后账号就被刷掉了大量资源。6.3 域名与端口问题有朋友问过“腾讯云怎么申请二级域名”“腾讯云如何开放所有端口”这些问题本质上都属于资源访问配置。现实中你并不需要“开放所有端口”只需要按需放行服务所需的最小端口集合。比如云函数部署的 HTTP 服务你只需要让 API 网关触发对应的函数即可安全组没必要对全端口开放。至于二级域名通常是在域名解析控制台添加一个 DNS 记录指向你的负载均衡或 API 网关。这样 Agent 的回调地址就可以用一个稳定的二级域名来对外暴露避免 IP 变动带来的维护麻烦。6.4 上传与版本迭代策略Skill 开发完成后需要打包上传。上传的内容包括配置文件和代码文件。我建议把 Skill 的配置文件单独放一个目录按版本号归档这样上传时不怕覆盖旧版本。my-awesome-skill/ ├── config.json # Skill 配置 ├── skill.py # 核心代码 ├── requirements.txt # 依赖列表 └── README.md # 使用说明上线后一旦发现 Skill 在特定场景下表现不佳不要马上改配置热更新建议先拉一个新版本分支改完在沙箱环境或你自己本地环境里跑几轮测试确认无误后再切到生产版本。模型类应用最大的特点就是“不稳定是常态”没有版本回退机制你半夜都可能被线上问题叫起来。7. 成长与优化让 Agent 越用越聪明一个 Agent 从能跑到好用中间还隔着长期的调优。这一节主要写写我踩过的大量坑以及总结出的调优方法论。7.1 记忆与上下文管理最开始跑 Agent 时我发现一个棘手的问题用户说“再简化一点”Agent 根本不知道“再”字指代的是什么因为它没有记住之前生成的内容。这是因为在模型交互里对话上下文是独立的每一次执行 Skill 都是一次独立的 API 调用。要想实现“多轮对话记忆”必须自己做记忆管理。推荐的做法是在 Agent 层维护一个记忆列表每次调用 Skill 前把当前记忆和本次用户输入一起注入 prompt在 Skill 返回结果后把关键信息追加进记忆。这里要注意记忆长度不要让记忆无限增长否则迟早会把模型的上下文窗口撑爆。我给自己的配置是一个会话最多保留 10 轮核心记忆超出的部分做摘要归档。记忆这一块是 Agent 体验的重中之重。没有记忆的 Agent就是金鱼用户用完一次就忘了你是谁。7.2 如何处理模型输出的稳定性问题模型输出的随机性是大模型应用绕不开的坑。同一个输入温度参数为 0.3 时可能是好的结果但温度参数设为 1.0 时可能就跑偏了。经过大量实验我总结出一个经验工具类 Skill 的温度尽量调低0~0.3创作类 Skill 的温度可以适当调高0.5~0.8。如果温度已经很低了输出还是不稳定那问题往往出在指令不够具体上。我见过最典型的例子是让 Skill 输出 JSON但忘了在指令里写明“只输出 JSON不要使用 Markdown 代码块”。模型加了三个反引号下游解析直接崩溃。这种问题的修法就是回到指令优化给模型更多“格式约束”和“示例为准”的引导。指令规范化的程度越高模型的输出方差越小。7.3 追踪与复盘最后说说追踪。Agent 上线后每次运行都会产生一份完整的调用日志用户输入、Agent 选择了哪个 Skill、每个 Skill 输入的参数是什么、输出是什么、执行结果如何。建议定期复盘这些日志你会发现一些规律用户频繁请求某个功能但这个功能你没有对应的 Skill——那就赶紧补一个某个 Skill 被调用频率很低但描述写得很长——说明 Agent 没识别出来该用需要改描述某个 Skill 调用后返回错误的比例偏高——那多半是参数定义或指令逻辑有问题。模型应用没有“一次做对”的说法它更像养盆栽需要持续地观察、修剪、调整。迭代三个版本以上Agent 的可用性才会有质的提升。8. 常见问题与排查技巧实录我整理了一张常见问题速查表都是团队在搭建和运维 Agent 过程中真实遇到的问题帮助各位快速定位。现象可能原因排查方法Agent 不调用某个 SkillSkill 描述里没有写触发场景优化描述加入“当用户……时使用”Skill 调用成功但返回空值参数校验没做Agent 没补齐必填参数检查 JSON Schema补充必填约束模型输出不是合法 JSON缺少输出格式约束在指令中明确“只输出 JSON不要代码块”云端环境访问超时本地接口被防火墙策略拦截检查安全组和 API 网关网络配置上传 Skill 后新 Agent 不生效没有同步到生产环境检查上传流程版本状态重新发布账号提示环境异常无法注册浏览器缓存或网络环境异常清理缓存、更换网络环境再试长文本场景经常截断报错内容超过上下文限制在 Skill 指令中增加文本长度上限限制发布操作状态不可知缺少异步任务回调云端部署配置好回调 URL保留任务状态 腾讯云AI Skills实战：从Skill设计到Agent编排部署全攻略
从“会写提示词”到“真能干活”中间隔着整个 Agent 工程化。这篇我拿腾讯云 AI Skills 当一个完整案例来拆从 Skills 该怎么规划、怎么写到怎么把 Skill 变成一个能独立决策的 Agent再到上线后遇到的各种坑一次性讲透。1. 整体设计思路为什么选 AI Skills 而不是硬编码流程很多人在做 Agent 时有个误区一上来就写一堆if-else把业务流程写死或者把所有工具调用塞进一个巨大的 prompt。这样做的代价在后期会集中爆发。我见过一个项目一个 prompt 里塞了十几个工具的说明模型经常在工具选择上犯迷糊这周修好了下个版本换了模型又翻车。腾讯云 AI Skills 这套体系解决的正是这个问题。它的核心思想是把 Agent 的能力按“技能”拆分每个 Skill 只负责一件完整的事Agent 本身则是一个编排器负责根据用户的意图去发现技能、组合技能、完成任务。这个思路其实和微服务架构非常像只不过微服务拆的是后端服务AI Skills 拆的是模型能力的执行单元。举个例子。假设你想做一个“文章自动发布 Agent”它可以读取你上传的文档提取核心内容判断适合发到哪个平台自动配图最后生成发布文案并推送。如果不用 Skills你的 prompt 会变得非常臃肿而且每扩展一个新平台就要改动整个 prompt。用 AI Skills你可以把“文档解析”做成一个 Skill把“平台适配”做成一个 Skill把“文案生成”做成一个 Skill把“发布执行”做成一个 Skill。Agent 拿到用户输入后自己去判断该调用哪些 Skill、按什么顺序调用每个 Skill 内部只关心自己的输入输出。我在实际项目中总结过一条经验一个 Skill 的职责边界应该以“一个用户可感知的完整功能”为最小单位。“读取文件”不能算一个 Skill因为它不是一个完整的用户任务“解析文档并生成摘要”才算。判断标准很简单——如果用户说“把这篇文章总结一下”Agent 能通过这个 Skill 独立完成回应那这个 Skill 就是合格的。另外Skills 设计还有一个隐蔽的好处可测试性。单独一个 Skill 的输入输出是可控的出了问题你知道去查哪个 Skill而整套流程出了问题你可以逐段验证。没有这层拆分调试 Agent 就像在黑暗里摸象哪里坏了根本看不出来。2. 从“工具调用”到“技能编排”的认知升级2.1 先说清楚 Skill 和 Agent 的区别这是我觉得所有人最容易搞混的地方。Skill 是能力Agent 是决策者。Skill 解决的是“能做什么”Agent 解决的是“该做什么、怎么做、先后顺序如何”。你写了一个“调用天气预报 API”的 Skill这个 Skill 自己永远不会知道用户想不想知道天气只有当 Agent 判断出用户的意图是“问天气”时这个 Skill 才会被激活。用大白话说Skill 是工具箱里的螺丝刀Agent 是用螺丝刀的人。螺丝刀不会自己拧螺丝但人也得有合适的螺丝刀才能把活干好。腾讯云 AI Skills 的设计里这两者天然是解耦的Agent 通过自然语言或结构化描述去“发现”SkillSkill 通过清晰的描述信息告诉 Agent“我能做什么、什么时候该用我、需要什么参数”。这个设计有个很关键的工程意义Skill 可以被复用和共享。团队里有人写了一个很好的“数据图表生成 Skill”其他人创建的 Agent 也能直接挂载这个 Skill不需要重复造轮子。长线来看你的 Skill 库会越来越庞大新 Agent 的搭建成本会越来越低这就是组合复利。2.2 什么时候应该做 Agent什么时候不需要我必须泼一盆冷水并不是所有场景都需要 Agent。如果一个任务的流程是完全固定的比如收到工单→判断类型→自动回复那用传统的 workflow 就够了引入 Agent 反而会让系统不稳定因为大模型的决策有随机性你很难保证每一次都走同一条路。需要 Agent 的场景有几个典型的特征意图是开放的、步骤是不固定的、输入是杂乱的。比如“帮我安排今天的日程包括查天气、看路线、订餐厅”这类任务没法写死流程因为用户的表述千变万化场景组合也千变万化必须由模型来理解意图、编排技能。腾讯云的 AI Skills 平台本身就支持 workflow 和 Agent 两种形态如果你的任务偏固定建议先用 workflow 串起来只有当分支太复杂、意图太多变时才把决策权交给 Agent。我个人的建议是从最小可用的 Agent 做起不要一开始就想要做一个“全能助手”。先把一两个核心场景跑通后面再慢慢加 Skills。Agent 最怕的就是能力太杂但每个都浅用户试一次不满意后面就不会再用了。3. 核心细节拆解设计一个高质量 Skill 的完整流程从一个想法到一个能跑的 Skill中间有几个关键步骤我逐个拆开讲。3.1 第一步定义技能的目标与边界动手写 Skill 之前先回答三个问题这个 Skill 解决什么类型的用户请求这个 Skill 不解决什么它的输入是什么、输出是什么就我以前写“周报生成 Skill”的经验来说一开始我把边界定得太宽——什么都能干结果用户让它统计项目工时它也往里套。后来我把输入严格要求为“项目列表 每个人的工作内容描述”输出为“Markdown 格式周报”并且明确告诉它“如果用户请求中缺少必要信息先向用户询问”效果就好了很多。边界定义得越清楚Agent 就越知道什么时候该用这个 Skill、什么时候不该用。很多 Agent 表现不佳不是因为模型不行而是因为 Skill 自己都没搞清楚自己该干什么。3.2 第二步把技能逻辑描述清楚这里是容易被忽略的细节。Agent 选择 Skill 不是靠执行代码去试而是靠“看”Skill 的描述信息来做语义匹配。所以 Skill 的描述description写得是否清晰、是否包含触发场景直接决定了 Agent 能不能正确调用它。我见过很多开发者在写描述时只写一句“生成周报”结果 Agent 在用户说“汇总下这周工作”时根本没联想到这个 Skill。改法是把触发场景写进去比如“当用户需要汇总本周的工作内容、项目进度、遇到的问题或请求以周报/月报格式输出报告时使用”。实测后调用准确率有明显提升。另外参数parameters定义一定要用清晰的 JSON Schema。类型要明确、必填项要标清楚、描述要能让 Agent 知道每个参数该填什么。特别是在有枚举值的情况下一定要把可选项列全否则 Agent 可能会凭空捏造一个值导致后续处理直接出错。3.3 第三步写好指令相当于 Skill 的“岗位说明书”在腾讯云 AI Skills 的 Skill 配置里核心就是接点配置包括指令和工具调用。在写指令时有一个技巧可以分享不要只写“干某事”要把处理步骤、边界条件、异常情况的应对都写进去。比如一个“文档翻译 Skill”它的指令可以包含提取原文内容时保持格式不变对专业术语优先使用用户提供的术语表术语表中没有的词汇可根据上下文确定含义如果原文是图片且无法直接提取文字则调用 OCR 工具处理后翻译翻译结果输出为双语对照格式原文在前译文在后。可以看到我把“怎么做”拆成了规则模型看到这些规则后执行起来会稳定得多。Skill 的指令本质上就是一份“给模型看的傻瓜操作手册”写得越具体模型的发挥就越稳定。3.4 第四步测试 Skill 并收集反馈测试阶段要刻意制造极端输入。我在测试“发票信息提取 Skill”时专门丢了几张模糊的照片、倒着的照片、有杂乱的背景的照片看模型的鲁棒性如何。结果发现原版提取逻辑在“模糊照片”场景下会直接报错加了“对图片进行方向矫正和画质增强”的预处理步骤后准确率从七成提到了九成以上。这里尤其要说一下Skill 的维护不是一锤子买卖。模型可能会升级API 可能会变用户的使用习惯也会变。建议给每个 Skill 加版本号记录迭代历史方便回归对比。4. 实现一个可直接复用的 Skill 配置模板这里我把一个比较通用的 Skill 配置模板拆给你们可以直接抄。以“网页内容摘要生成 Skill”为例它做的事情是用户丢来一个网址或一段长文本Skill 抓取内容后生成结构化摘要。4.1 配置 Skill 基本信息Skill 的配置通常包含这几个字段名称name建议用英文短横线命名比如web-content-summarizer方便标识。显示名称display_name给用户看的用中文更友好比如“网页内容摘要生成”。描述description这是给 Agent 看的必须写清触发条件和能力边界。版本号version建议用1.0.0这样的语义化版本号方便追溯。作者author团队内分享时很有用方便使用者联系维护人。具体到本案例描述可以这样写当用户提供一个网址、一段链接或一篇文章的长文本要求“总结、提炼、梳理核心信息、生成摘要”时使用本技能。本技能可以自动抓取网页正文内容并生成包含核心观点、关键数据和结论的结构化摘要。如果用户提供的仅是一句话而不是完整文章请直接回答不要调用本技能。这里特意写了“如果用户提供的仅是一句话不要调用本技能”目的是防止 Agent 误用。4.2 配置输入参数给这个 Skill 配置输入参数时可以使用这样的 JSON Schema{ type: object, properties: { url: { type: string, description: 待摘要的网页链接必须以 http:// 或 https:// 开头 }, content: { type: string, description: 待摘要的长文本内容当 url 未提供时必填 } }, oneOf: [ { required: [url] }, { required: [content] } ] }这里的关键是oneOf这个约束。它告诉 AgentURL 和纯文本二选一不能两个都不填。我在实战中发现参数的“必填校验”是模型最容易出错的地方如果不加约束模型有时会两个参数都不填Skill 执行时只能拿空值去跑最后返回一个莫名其妙的错误。有了oneOf约束后Agent 在调用前就会自己想办法补齐参数。4.3 指令prompt的写法Skill 的指令是核心中的核心。我在这个示例里会这样写你是一个网页内容摘要生成器。你接收一个网址或一段长文本。如果收到的是网址先用 web_fetch 工具抓取页面内容然后忽略广告、导航栏、页脚等无关元素只保留正文部分。如果收到的直接是文本则直接处理。 摘要要求 1. 先给出文章的一句话核心结论。 2. 再分条输出关键要点每条不超过 50 字。 3. 如有涉及数据、人名、金额等关键信息请单独列出“数据摘要”。 4. 输出使用 Markdown 格式。 5. 如果页面内容是英文摘要也用英文输出否则用中文输出。 6. 如果抓取内容超过 5000 字只保留前 5000 字作为输入。注意到第 6 条了吗这是我很早以前踩过的坑。模型有上下文长度限制如果网页内容太长直接把整个页面塞进 prompt必然导致截断或报错。在 Skill 指令里提前限制“只保留前 5000 字”可以让 Agent 在进入模型前就做一次内容裁剪大大降低温度过高的问题。4.4 关联工具调用腾讯云 AI Skills 平台上的 Skill 可以挂载工具。所谓工具可以是平台内置能力也可以是 HTTP 插件。上面这个例子需要调用一个web_fetch工具来抓取网页内容。在配置工具时要注意工具的输入要能和 Skill 的参数对齐。比如web_fetch需要url字段就和 Skill 的url参数绑定。工具调用失败时要设置兜底逻辑。我在指令里通常会写一句“如果 web_fetch 调用失败则返回错误并提示用户检查网址是否可访问。”这看起来是小细节但实际体验会好很多不会让用户面对一堆不知所谓的系统错误。工具调用必然会引入额外的延迟。所以 Skill 里能不用工具就不用工具能用一次工具解决的绝不调用两三次。5. 从 Skill 到 Agent把零散技能串成一个全流程应用Skill 做完了距离“全能 Agent”还差一步——把多个 Skill 挂在 Agent 上并让 Agent 学会什么时候用哪个、怎么组合。5.1 Agent 的“决策大脑”怎么配在腾讯云 AI Skills 平台创建 Agent 时核心要配置的是“指令”部分。这个指令和 Skill 的指令不一样Agent 的指令相当于“主帅的作战方针”而不是具体每个岗位的职责。拿一个“智能内容运营 Agent”来举例。假设它挂载了三个 Skillweb-content-summarizer摘要、article-generator写稿、publisher发布。Agent 指令可以这样写你是一个内容运营助手负责从素材到发布的完整流程。 当用户提供一篇外链文章时你应先用 web-content-summarizer 生成摘要再询问用户是否需要基于摘要生成新的原创文章。 如果用户说“写一篇介绍XX的文章”你应该先判断素材是否足够如果用户没有给素材先向用户索要参考资料或链接。 发布操作必须经过用户确认后才能执行。这里的关键是“流程编排”和“确认机制”。Agent 不能自己决定把内容直接发布出去必须在发布前向用户确认。我见过不少 Agent 因为缺少这种“确认节点”在真实环境里做出了一些不可撤销的操作后果相当麻烦。Agent 的自主性和可控性之间必须要有明确的边界。5.2 编排逻辑怎么写腾讯云 AI Skills 的 Agent 编排支持两种模式自动编排和手动流程编排。自动编排下Agent 根据用户输入自行决定调用哪些 Skill手动流程编排则是你提前指定节点顺序Agent 只负责在每个节点上执行参数填充。我的经验是关键节点建议用手动编排。比如“生成稿件→用户确认→发布”这三步是固定的那就直接在流程编排里把顺序定死Agent 不能跳步。至于“用户说的话该怎么理解、字段怎么提取”这部分信任模型让它自动处理。混合编排是我目前用得最多的方式核心链路固定外围判断交给模型。既能保证安全底线又能让交互灵活。5.3 多 Agent 协作的必要性当流程过于复杂一个 Agent 的指令可能会变得极其臃肿维护成本飙升。这时候可以考虑拆分多个 Agent各自承担一个角色再用主 Agent 做路由。比如“全能内容管家”可以拆成“分析 Agent”“创作 Agent”“发布 Agent”主 Agent 收到用户需求后判断该交给谁处理。这也是为什么我建议在 Skills 设计时就把“技能”和“流程”分开——Agent 层面的编排是基于 Skill 的Skill 本身不该关心自己处于哪条流程。不过多 Agent 的引入也会带来问题通信成本增加、连接处错误率上升、调试复杂度增加。所以我的原则是能单 Agent 解决的绝不上多 Agent只有在单个 Agent 指令超过某个规模上限、或权限隔离要求很高时才考虑多 Agent。6. 云端部署与配置从本地联调到上线注意事项开发完 Skill 和 Agent接下来是部署上线。这个过程涉及腾讯云侧的不少配置我把容易踩坑的点挑出来说。6.1 环境准备与服务开通在腾讯云上Agent 开发依赖 AI 开发平台中“应用”与“模型服务”相关能力。你需要登录腾讯云控制台开通相应的服务。有一个高频问题我先说一句只有在你的账号完成实名认证的情况下才能正常使用这些服务否则云 API 和工具有很多都调不通。如果你的账号注册后提示环境异常、无法注册或无法登录通常和当前网络环境有关。可以尝试更换浏览器、清理缓存或者在手机流量环境下重新操作。我在实际操作中解决过类似问题最后是在清理了浏览器 Cookie 并关闭代理插件后才顺利完成的。6.2 配置部署所需权限无论是调用模型接口还是云函数都有一个前置条件配置好身份凭证。在本地调试时可以用环境变量的方式配置export TENCENTCLOUD_SECRET_ID你的 SecretId export TENCENTCLOUD_SECRET_KEY你的 SecretKey在云端运行时则建议使用角色授权而非永久密钥。我强烈建议不要在生产环境里使用个人密钥管理风险很高。我见过有人把密钥提交到了代码仓库几个小时后账号就被刷掉了大量资源。6.3 域名与端口问题有朋友问过“腾讯云怎么申请二级域名”“腾讯云如何开放所有端口”这些问题本质上都属于资源访问配置。现实中你并不需要“开放所有端口”只需要按需放行服务所需的最小端口集合。比如云函数部署的 HTTP 服务你只需要让 API 网关触发对应的函数即可安全组没必要对全端口开放。至于二级域名通常是在域名解析控制台添加一个 DNS 记录指向你的负载均衡或 API 网关。这样 Agent 的回调地址就可以用一个稳定的二级域名来对外暴露避免 IP 变动带来的维护麻烦。6.4 上传与版本迭代策略Skill 开发完成后需要打包上传。上传的内容包括配置文件和代码文件。我建议把 Skill 的配置文件单独放一个目录按版本号归档这样上传时不怕覆盖旧版本。my-awesome-skill/ ├── config.json # Skill 配置 ├── skill.py # 核心代码 ├── requirements.txt # 依赖列表 └── README.md # 使用说明上线后一旦发现 Skill 在特定场景下表现不佳不要马上改配置热更新建议先拉一个新版本分支改完在沙箱环境或你自己本地环境里跑几轮测试确认无误后再切到生产版本。模型类应用最大的特点就是“不稳定是常态”没有版本回退机制你半夜都可能被线上问题叫起来。7. 成长与优化让 Agent 越用越聪明一个 Agent 从能跑到好用中间还隔着长期的调优。这一节主要写写我踩过的大量坑以及总结出的调优方法论。7.1 记忆与上下文管理最开始跑 Agent 时我发现一个棘手的问题用户说“再简化一点”Agent 根本不知道“再”字指代的是什么因为它没有记住之前生成的内容。这是因为在模型交互里对话上下文是独立的每一次执行 Skill 都是一次独立的 API 调用。要想实现“多轮对话记忆”必须自己做记忆管理。推荐的做法是在 Agent 层维护一个记忆列表每次调用 Skill 前把当前记忆和本次用户输入一起注入 prompt在 Skill 返回结果后把关键信息追加进记忆。这里要注意记忆长度不要让记忆无限增长否则迟早会把模型的上下文窗口撑爆。我给自己的配置是一个会话最多保留 10 轮核心记忆超出的部分做摘要归档。记忆这一块是 Agent 体验的重中之重。没有记忆的 Agent就是金鱼用户用完一次就忘了你是谁。7.2 如何处理模型输出的稳定性问题模型输出的随机性是大模型应用绕不开的坑。同一个输入温度参数为 0.3 时可能是好的结果但温度参数设为 1.0 时可能就跑偏了。经过大量实验我总结出一个经验工具类 Skill 的温度尽量调低0~0.3创作类 Skill 的温度可以适当调高0.5~0.8。如果温度已经很低了输出还是不稳定那问题往往出在指令不够具体上。我见过最典型的例子是让 Skill 输出 JSON但忘了在指令里写明“只输出 JSON不要使用 Markdown 代码块”。模型加了三个反引号下游解析直接崩溃。这种问题的修法就是回到指令优化给模型更多“格式约束”和“示例为准”的引导。指令规范化的程度越高模型的输出方差越小。7.3 追踪与复盘最后说说追踪。Agent 上线后每次运行都会产生一份完整的调用日志用户输入、Agent 选择了哪个 Skill、每个 Skill 输入的参数是什么、输出是什么、执行结果如何。建议定期复盘这些日志你会发现一些规律用户频繁请求某个功能但这个功能你没有对应的 Skill——那就赶紧补一个某个 Skill 被调用频率很低但描述写得很长——说明 Agent 没识别出来该用需要改描述某个 Skill 调用后返回错误的比例偏高——那多半是参数定义或指令逻辑有问题。模型应用没有“一次做对”的说法它更像养盆栽需要持续地观察、修剪、调整。迭代三个版本以上Agent 的可用性才会有质的提升。8. 常见问题与排查技巧实录我整理了一张常见问题速查表都是团队在搭建和运维 Agent 过程中真实遇到的问题帮助各位快速定位。现象可能原因排查方法Agent 不调用某个 SkillSkill 描述里没有写触发场景优化描述加入“当用户……时使用”Skill 调用成功但返回空值参数校验没做Agent 没补齐必填参数检查 JSON Schema补充必填约束模型输出不是合法 JSON缺少输出格式约束在指令中明确“只输出 JSON不要代码块”云端环境访问超时本地接口被防火墙策略拦截检查安全组和 API 网关网络配置上传 Skill 后新 Agent 不生效没有同步到生产环境检查上传流程版本状态重新发布账号提示环境异常无法注册浏览器缓存或网络环境异常清理缓存、更换网络环境再试长文本场景经常截断报错内容超过上下文限制在 Skill 指令中增加文本长度上限限制发布操作状态不可知缺少异步任务回调云端部署配置好回调 URL保留任务状态