上个月我把自己的 Agent 从“只会聊天”调教成“能干活”的状态时被问得最多的一个问题不是模型选型也不是 Prompt 怎么写而是“你这套 AI Skills 到底是怎么组织的”。我当时的回答很直接别急着堆功能先把 Agent 的能力边界拆开让每个技能都能被单独开发、单独测试、单独部署。这个思路放在腾讯云上跑通之后整个 Agent 的开发效率提升了不少所以这篇就把“腾讯云 AI Skills 最佳实践”完整复盘一遍从技能拆解、SKILL.md 编写、上传部署、二级域名绑定、端口开放到 LiteLLM Proxy 这类网关的接入与排查全链路都有适合正在做 Agent 开发的团队和个人开发者参考。先交代项目背景。我手上的 Agent 是一个偏工程向的智能体要给研发同学提供类似“qorder 编程技能”这种可复用的编码辅助能力同时还要接一些外部 API 做数据查询和自动化操作。最开始我走了一条弯路把所有能力都塞进系统提示词System Prompt结果 Agent 的上下文窗口很快被塞满指令一多它就开始“左右互搏”该调工具的时候不调不该调的时候乱调。后来我花了一个周末把项目整个重构了一遍核心就一句话Agent 不应该是“一个大 Prompt”而应该是一个“会调度的壳 一堆可插拔的 Skills”。这套结构放到腾讯云上跑结合云函数、API 网关等底座整个链路才真正变得可控。1. 先想清楚Skill 和 Agent 到底怎么分工1.1 为什么很多人把 Agent 做成“一个大 Prompt”我在很多 Agent 项目里见过一种典型的坏味道开发者为了省事把角色设定、任务清单、工具调用规则、输出格式全部揉进一段长达三千字的系统提示词里然后让模型自己“悟”。刚跑通 demo 的时候看起来很聪明一旦投入真实使用就会暴露出几个非常致命的毛病。第一是上下文污染。系统提示词越长模型在生成时注意力被稀释得越厉害。你要它遵守输出 JSON 格式的规则它记着记着就开始自由发挥你要它优先调用某个外部工具它可能因为上下文里有一句类似的描述就“自作主张”。第二是难以维护。业务上每新增一种技能你就要改一次那三千字的提示词改完之后还需要重新验证旧功能有没有被破坏回归成本巨大。第三是故障定位极其痛苦一旦 Agent 在某个技能上行为异常你很难判断是提示词写得不对、参数没传对、还是外部接口出错了。我踩过这个坑之后对 Skill 和 Agent 分层的价值体会特别深。1.2 我的拆法Agent 做编排Skill 做专业能力打个比方一个合格的老师傅在干活时身上背着一整个工具箱他需要判断“现在是拧螺丝的场景”还是“是切割的场景”从而从箱子里拿出对应的专用扳手或切割机。工具箱里的每件工具就是 Skill老师傅的判断力就是 Agent 的编排能力。两者职责必须清晰混在一起的结果就是工具永远不会被正确使用。Agent 层关心的核心问题只有这三个理解用户意图判断当前任务需要调用哪些能力维护对话上下文和任务状态做好记忆管理调度 Skill 的执行顺序并对结果做取舍与汇总。Skill 层关心的则是完全不同的东西某项专业能力的输入约定是什么、输出格式是什么内部要调哪个外部 API、用什么参数、如何处理失败如何被 Agent 准确发现也就是技能描述写得够不够清晰。所以我在项目里坚持一个原则Agent 里不放任何业务细节所有能被独立描述的能力全部下沉到 Skill 里。这样每个 Skill 都是一个可独立开发、独立测试、独立部署的模块新同学进来想给 Agent 加能力只需要照着 Skill 模板写一个技能包完全不需要理解 Agent 整体的调度逻辑这种“低耦合”的开发模式在多人协作时收益极大。2. AI Skills 到底怎么写从“一句话需求”到“可上线技能包”2.1 技能描述先行让 Agent “看见”这个技能AI Skills 的载体是一段结构化的技能描述文件通常叫 SKILL.md。很多新手写这个文件时最大的误区是把它当成给人类看的 README写一堆“本技能用于文字摘要”结果 Agent 根本不会主动调用它。原因很简单模型在判断是否调用某个技能时主要看技能描述里的触发条件是否和用户当前意图匹配描述越模糊被调用的概率就越低。我总结了一套比较可靠的写法一个 SKILL.md 文件分成前端配置和正文两大部分。前端配置用 YAML frontmatter 承载技能元信息正文部分用 Markdown 描述使用场景和细则。下面这个例子是我为一个“代码审查技能”写的 SKILL.md 的 frontmatter 部分结合了 qorder 这类编程辅助场景的实际需求--- name: code-review-skill description: 当用户提交代码片段或 PR 链接、要求做代码质量检查、寻找潜在 Bug、评估逻辑边界时使用。如果用户只是闲聊或询问一般编程概念不要使用本技能。 version: 1.0.0 author: your-name when_to_use: 用户在讨论具体代码实现、请求 review、或贴出报错栈并要求定位问题时 ---注意 description 里我特意写了“什么时候不要用”。这句话看起来不起眼但它能有效降低 Agent 的误调用率。我实测过加了排除条件之后误调用率从大约 15% 降到了 3% 以内。背后的逻辑是模型在做工具选择时本质上是在做“文本匹配”你提供的触发条件越精确匹配的边界就越清晰。这一点在很多 AI Agent 开发教程里不会强调但恰恰是决定体验的核心细节。2.2 定义动作接口参数比 Prompt 更重要SKILL.md 的正文部分不能只写“我会怎么做”更要写清楚“我需要什么参数”“我返回什么结构”。我把技能动作定义成接口的形式每个技能支持一到多个动作每个动作都有明确的输入输出。这套思路和开发 RESTful API 是一样的Skill 的调用方是 AgentAgent 需要根据技能的动作签名来填充参数动作接口定义得越清楚Agent 传参就越准确。用 YAML 给技能定义动作看起来是这样的actions: - name: review_code description: 对传入的代码片段执行静态审查返回问题列表与修改建议 parameters: - name: code_language type: string required: true description: 代码语言例如 python / javascript / go - name: code_content type: string required: true description: 待审查的代码正文 - name: check_security type: boolean required: false default: false description: 是否启用安全漏洞专项检查 output: type: object fields: - issue_count - issues - suggestion这个 skill 对应的是“编程好用的 AI 编程辅助能力”场景。参数里每个字段我都要写清楚类型的取值空间和默认值。有一个经验是Agent 模型非常擅长根据参数描述做填空但它不会去猜你没写的约束。如果你的 code_content 参数没有说明“接受 Base64 编码的字符串”当你传入二进制或超长代码块时聪明一点的模型可能自行截断不聪明的模型就直接报错了。把参数说明写到“字段级”是最划算的投入之一。2.3 给 Agent 出“面试题”离线验证技能边界Skill 写完之后最忌讳的事情就是直接扔到线上让 Agent 去试。我自己的习惯是先给 Skill 做一轮离线验证。具体做法是编写一批典型用户输入然后模拟 Agent 去调用这个 Skill看描述是否被准确触发、动作能否正确执行。我把这批测试输入称为“给 Agent 出的面试题”。以代码审查技能为例我会准备这些用例用例类型输入示例期望行为正面触发“帮我看看这段 Python 代码有没有并发问题”调用 review_codelanguagepython正面触发“这个 PR 的改动靠谱吗”调用 review_code需要设计拉取远程代码逻辑负面排除“Python 和 Go 哪个好”不调用 review_code走普通对话边界情况“这段代码在跑的时候 OOM 了”无代码正文先主动询问代码内容再决定是否调用参数补全“审查一下这段 JS重点看 XSS”没传 language根据内容推断语言自动补全 languagejavascript离线验证这一步看着简单但它能把大量问题拦截在部署之前。我经常发现某个技能写完之后Agent 在一次测试里连续触发错相邻技能其实就是两个 SKILL.md 里的 when_to_use 描述重叠了把重叠部分改清晰误触发就消失了。3. 腾讯云部署的完整链路上传、域名、端口一样都不能少3.1 Skill 上传之前要做好哪些本地检查当 Skill 内容在本地验证通过后才进入真正的部署环节。腾讯云上承载 AI Skills 的方式我比较推荐“对象存储/云函数 API 网关”的组合SKILL.md 和技能描述这类静态文件放对象存储需要真实计算逻辑的技能则放云函数再配合 API 网关对外暴露统一入口。这样拆分的好处是静态技能可以被多个 Agent 复用动态技能则可以独立扩缩容资源消耗和调用频率完全隔离。上传之前我在本地一定会做三个检查。第一是依赖声明完整凡是技能运行时要 import 的第三方库必须在打包配置里逐个列清楚腾讯云的云函数在安装依赖时一旦遇到缺失会直接拉取失败如果本地静默安装了某些包而没写进声明上传后就会出现“本地能跑、线上 500”的尴尬局面。第二是入口文件命名正确云函数平台通常要求固定入口文件名比如 index.py 里的 main_handler拼错一个字母整个函数就无法被触发。第三是 SKILL.md 的格式校验YAML 的缩进错位会导致 Agent 无法解析这个技能我在本地会先跑一遍 YAML parser 确认没有语法错误。提示上传 Skill 技能包之前可以先在本地用命令行工具跑一次“干跑”dry-run把技能包和 Agent 的调用链路都模拟一遍。我发现很多“上线后无法调用”的问题其实在本地干跑阶段就会暴露没必要把错误带上云端。3.2 二级域名申请与解析为什么我总是先在本地把 CNAME 写对接下来要解决的是给 API 网关绑定一个对外可访问的地址。这部分和腾讯云上申请二级域名的操作强相关。很多第一次接触云端部署的同学不理解“为什么不能直接用平台默认分配的地址”原因在于默认地址通常是一长串随机字符难以记忆而且当 Agent 需要回调或校验域名白名单时一个规整的二级域名远比随机字符串省心。申请二级域名的流程大概是先在域名注册控制台添加一个子域名记录比如 skill.example.com然后在 API 网关的自定义域名配置里绑定这个二级域名再按平台提示到 DNS 服务商处添加一条 CNAME 记录指向 API 网关分配的域名。这里有个关键细节CNAME 记录一定要先在本地确认解析值正确再操作否则平台侧校验域名归属时很可能失败。我试过几次在控制台直接复制粘贴结果从别处复制来的值带了空格提交失败后排查了大半天最后发现只是多了一个不可见字符非常浪费时间。绑定完成之后还有一个经常被忽略的点如果你要开 HTTPS别忘记申请 SSL 证书并完成证书配置。Agent 的运行时和模型网关在做外部调用时对自签名证书非常不友好不少大模型 API 在收到一个不安全连接时直接就是 403。所以你在腾讯云上绑定二级域名之后顺手把证书托管也做了后续能省掉大量 TLS 握手报错。3.3 端口开放与安全组“端口不通”和“权限过宽”是同一个问题的两面另一类高频问题是端口配置。云函数本身没有传统意义上的端口监听概念但如果你在云服务器或容器里部署 Agent 运行时比如自建了一个 LiteLLM Proxy、跑了一个 Harness 服务、或者临时用内网穿透工具调试那就必然要和“入站规则”“安全组开放端口”打交道。我的建议是遵循最小开放原则默认不开放任何公网端口只有需要被公网访问的服务才按需放行。在腾讯云的安全组控制台里你需要同时配置入站规则和出站规则。入站规则是别人访问你的服务的入口出站规则是你的服务访问外部网络的能力。出现过 Agent 调用外部 API 一直超时的情况结果不是入站端口的问题而是出站规则把到目标地址的流量拦了。排查网络问题时两条规则都要看别只盯着入站。以我部署 LiteLLM Proxy 为例它是统一管理多个模型 API 的代理服务默认监听 8000 或 4000 端口。我在安全组里只放行了 4000 端口来源 IP 范围设置成仅允许自己的出口 IP然后加上一条 443 端口给 HTTPS 访问留门其他端口一律拒绝。这样即使代理服务本身有漏洞被外部探测到的概率也大大降低。端口放行后用这条命令做连通性测试是最快的curl -v https://skill.example.com/v1/models如果看到 HTTP 200 或者模型列表 JSON说明域名解析、证书校验、安全组放行、服务监听全部正常如果返回超时或连接被拒那就按照 DNS 解析、TCP 连通性、服务状态、安全组规则这个顺序从上到下排查。我把这个检查顺序写进项目文档里每次新环境部署都按顺序过一遍几乎不会卡住。4. 把 Skill 接到 Agent 运行时一次完整的联调记录4.1 为什么我这里选了 LiteLLM Proxy 做统一网关技能开发完、基础设施就绪后下一步是让 Agent 运行时能真正消费这些 Skill。我这里选择引入 LiteLLM Proxy 作为统一的模型访问网关而不让 Agent 直接调用各家模型的原始 API。这么做有三个原因。第一是接口标准化。不同的模型服务商提供的 API 格式差异较大有的走 OpenAI 兼容格式有的是 Anthropic 风格Skill 如果依赖 Agent 直接调用这些五花八门的接口技能内部就要写很多兼容代码。LiteLLM Proxy 会把所有上游模型接口都转成统一的 OpenAI 格式Skill 只需实现一个客户端协议就能访问不同模型真正做到了“一套代码多家模型”。第二是配置管理集中化。API Key 散落在各个 Skill 的配置文件里是非常危险的事情一旦某个配置文件被误提交到代码仓库密钥就泄露了。我把所有模型 API Key 集中放在 LiteLLM Proxy 的环境变量或密钥管理服务里Skill 本身不感知具体 Key它在运行时只需要访问网关地址由网关负责鉴权和计费。这样既降低了密钥泄露风险也方便做调用量审计。第三是能统一处理重试与限流。Skill 在做真实的业务调用时上游模型经常会出现限流429或临时过载5xx如果每个 Skill 都自己实现一套重试策略代码重复而且行为不一致。LiteLLM Proxy 在网关层统一做重试、超时和熔断Skill 面对的是一个“更稳定”的模型后端故障处理起来要轻松得多。4.2 从“调不通”到“跑起来”一次典型的 timeout 排查理论说完分享一次真实又典型的排障经历。某个 Skill 上线后Agent 执行到一半给我的日志里出现了类似“agent execution provider did not respond in time”的报错。这个报错从字面看是 Agent 执行提供方没有在时限内响应但具体情况需要抽丝剥茧。我先做了三层定位。第一层看 Agent 日志确认它已经把 Skill 的调用请求发出了第二层到 LiteLLM Proxy 的访问日志里查结果根本没看到这条请求进来说明请求可能在到达网关之前的链路就断了第三层打开云服务器上的 tcpdump 抓包发现 TCP 握手能完成但应用层一直没有返回数据。排查到这里我大概猜到了问题方向不是代理服务没起来而是它监听的对象不对。跑到服务器上用命令确认了一下netstat -tlnp | grep 4000结果发现进程确实在 4000 端口上不过监听地址写的是 127.0.0.1也就是只允许本机访问。外部请求经过安全组放行、到达云服务器之后发现这个端口上并没有一个对外可见的服务在接收流量请求自然就挂住了。把 LiteLLM Proxy 的监听地址从 127.0.0.1 改成 0.0.0.0 再重启然后再执行一次 curl 命令立刻就通了。这个问题排查过程大概花了我四十分钟核心原因就一句话服务监听的网卡和外部访问的路径不一致。还有一次遇到的是“agent execution terminated due to error”这是更笼统的报错。一步步查下来才发现是 Skill 里调用外部 API 时设置了太短的超时时间而那个上游接口因为业务高峰平均响应就要 8 秒结果每次调用都在 5 秒超时后被强制中断。我把 Skill 内部 HTTP 客户端的超时时间从 5 秒调整到 15 秒同时把重试策略从“重试 3 次”改成“重试 2 次开启退避”问题就消失了。这里也想提醒大家Agent 整体的超时时间和单个 Skill 内部调用的超时时间要匹配否则内层还没跑完外层就已经判定执行超时了这种错误报出来非常难查。5. 避坑速查表我在这条路上反复踩过的坑经历了多个项目的实际打磨之后我把自己反复踩过的坑整理成一张速查表发布 AI Skills 前逐条过一遍能躲掉 80% 的线上故障。坑位典型表现排查方向一劳永逸的做法端口未放行Agent 回调超时curl 不通安全组入站规则、服务监听地址最小化放行端口并写进 IaC禁止控制台手改CNAME 解析漂移域名时而通时而不通DNS 解析记录是否变更在 Cloudflare/腾讯云 DNS 控制台锁住记录SKILL.md 描述含糊Agent 永远不调用该技能看 Agent 的工具选择日志描述中写清楚触发条件与排除条件缺少必要字段技能执行报参数错误看 Agent 实际传参结果动作参数定义到字段级并给默认值内层超时小于外层技能被外层强制中止检查各环节超时配置按链路最短原则倒推设定超时参数API Key 泄露风险代码仓库扫描出密钥git 历史中查找已暴露的 Key一律走环境变量/密钥管理禁止硬编码通配端口开放服务器被扫描爆破安全组规则是否 0.0.0.0/0 全放只放行必要端口并限定来源 IP监听 127.0.0.1外网访问不通进程监听地址是否绑定所有网卡明确设置 HOST0.0.0.0 并通过 curl 验证其中 SKILL.md 描述含糊这条值得展开说。有一次我写了一个“数据恢复分析”技能description 写着“当用户提到文件系统或数据恢复时使用”。结果实际使用中用户只是在问“Linux 下误删除的文件还能找回来吗”Agent 就触发了这个技能去调用底层的数据恢复工具差点把正在运行的服务目录扫描了一遍。后来我把 description 改成“当用户要求对指定路径执行数据恢复操作、需要扫描文件系统元数据时使用若只咨询恢复原理而不涉及具体操作应仅提供理论回答”。改完之后技能被准确调用的次数直线上升误触发问题基本消失。这件事给我的启发是写技能描述最关键的不是告诉 Agent“我能做什么”而是告诉它“什么情况下该用我什么情况下不该用我”。这个分寸感决定了 Agent 整体的智能度。还有一个小技巧想分享如果一个 Agent 同时挂了多个 Skill尽量让每个技能的 description 里包含该技能独有的动作词。比如代码审查技能里带“review”“PR”“bug 排查”这类高频词代码生成技能里带“写出”“实现”“生成函数”这类词技能之间重叠的语义越少模型在做意图路由时困惑就越少。如果发现两个技能经常被同时唤起优先检查它们之间是否存在同一个触发词这时候不一定是提示词写得不好也可能两个技能本来就应该合并成一个大技能。6. 关于“框架选型与安全”我最后想说的几点Agent 技能化改造做完后团队里有人问过我一个问题要不要引入一个更重的 Agent 框架来做任务编排我理解这个想法市面上像 Harness 这类工具确实能把 Agent 执行过程可视化、流程化看起来很“正规”。但这里必须分清诉求层次。如果你只是需要 Agent 能够按顺序调用几个 API、做几次条件判断那么自己维护一套轻量的 Skill 调度逻辑可能更快如果你的场景里有复杂的多 Agent 协作、需要暂停恢复、人工审批、分支回滚那引入 Harness 这类框架就是合理的。我在项目中采用的是一个折中方案编排层保持轻量把“当前的用户意图对应到哪个 Skill”的选择逻辑外置到一个可配置的路由表中。这样既不上重框架又不用把全部逻辑硬编码在 Prompt 里。对于大多数中低频的 Agent 场景来说这种“规则路由 Skill 调用”的混合模式可能比纯靠模型做工具选择更可控尤其在业务方要求技能执行结果“可解释”的时候规则路由天然就有审计日志。安全性方面我再补充一个容易被忽略的细节Agent 在调用 Skill 的时候会把自己的对话上下文打包传给 Skill。如果上下文中包含敏感信息比如生产环境的数据库连接串、客户的个人信息、内部系统的凭据这些信息就可能被 Skill 里的模型请求带回给上游模型厂商。所以我在设计 Skill 的动作参数时建立了一个“最小字段原则”Skill 不能拿到整个对话上下文只能拿到动作参数里明确声明的那几个字段。这个原则能避免很多隐含的数据外泄风险。我在腾讯云控制台做权限配置时也会为每个 Skill 关联独立的子账号或角色只授予它真正需要的资源访问权限最小权限原则放在 AI 应用里同样适用。最后的实操体会这套“腾讯云 AI Skills 最佳实践”从拆解、编写、部署到联调整条链路我在多个项目里反复验证过最大的感受是AI Skills 的价值不在“写得好不好”而在“能不能被 Agent 正确发现、稳定执行、快速排障”。技能包拆得再漂亮如果 Agent 的调度层不理解触发条件一切白搭部署链路再稳如果技能描述里的排除条件写得不清楚线上的误调用就会一直消耗你的额度。所以我在每次发布新 Skill 之前一定会做两件事第一打开 Agent 的日志看技能是否有被正确触发第二故意准备几个“不该调用本技能”的输入去测试它会不会误触发。这两关过了才敢真正上线。把“技能开发”这件事当成“给 Agent 培养一个靠谱的同事”沟通清楚边界、提供清晰的接口、建立完善的反馈机制Agent 才会越来越可靠。 腾讯云AI Skills最佳实践：Agent技能拆解与部署全流程
上个月我把自己的 Agent 从“只会聊天”调教成“能干活”的状态时被问得最多的一个问题不是模型选型也不是 Prompt 怎么写而是“你这套 AI Skills 到底是怎么组织的”。我当时的回答很直接别急着堆功能先把 Agent 的能力边界拆开让每个技能都能被单独开发、单独测试、单独部署。这个思路放在腾讯云上跑通之后整个 Agent 的开发效率提升了不少所以这篇就把“腾讯云 AI Skills 最佳实践”完整复盘一遍从技能拆解、SKILL.md 编写、上传部署、二级域名绑定、端口开放到 LiteLLM Proxy 这类网关的接入与排查全链路都有适合正在做 Agent 开发的团队和个人开发者参考。先交代项目背景。我手上的 Agent 是一个偏工程向的智能体要给研发同学提供类似“qorder 编程技能”这种可复用的编码辅助能力同时还要接一些外部 API 做数据查询和自动化操作。最开始我走了一条弯路把所有能力都塞进系统提示词System Prompt结果 Agent 的上下文窗口很快被塞满指令一多它就开始“左右互搏”该调工具的时候不调不该调的时候乱调。后来我花了一个周末把项目整个重构了一遍核心就一句话Agent 不应该是“一个大 Prompt”而应该是一个“会调度的壳 一堆可插拔的 Skills”。这套结构放到腾讯云上跑结合云函数、API 网关等底座整个链路才真正变得可控。1. 先想清楚Skill 和 Agent 到底怎么分工1.1 为什么很多人把 Agent 做成“一个大 Prompt”我在很多 Agent 项目里见过一种典型的坏味道开发者为了省事把角色设定、任务清单、工具调用规则、输出格式全部揉进一段长达三千字的系统提示词里然后让模型自己“悟”。刚跑通 demo 的时候看起来很聪明一旦投入真实使用就会暴露出几个非常致命的毛病。第一是上下文污染。系统提示词越长模型在生成时注意力被稀释得越厉害。你要它遵守输出 JSON 格式的规则它记着记着就开始自由发挥你要它优先调用某个外部工具它可能因为上下文里有一句类似的描述就“自作主张”。第二是难以维护。业务上每新增一种技能你就要改一次那三千字的提示词改完之后还需要重新验证旧功能有没有被破坏回归成本巨大。第三是故障定位极其痛苦一旦 Agent 在某个技能上行为异常你很难判断是提示词写得不对、参数没传对、还是外部接口出错了。我踩过这个坑之后对 Skill 和 Agent 分层的价值体会特别深。1.2 我的拆法Agent 做编排Skill 做专业能力打个比方一个合格的老师傅在干活时身上背着一整个工具箱他需要判断“现在是拧螺丝的场景”还是“是切割的场景”从而从箱子里拿出对应的专用扳手或切割机。工具箱里的每件工具就是 Skill老师傅的判断力就是 Agent 的编排能力。两者职责必须清晰混在一起的结果就是工具永远不会被正确使用。Agent 层关心的核心问题只有这三个理解用户意图判断当前任务需要调用哪些能力维护对话上下文和任务状态做好记忆管理调度 Skill 的执行顺序并对结果做取舍与汇总。Skill 层关心的则是完全不同的东西某项专业能力的输入约定是什么、输出格式是什么内部要调哪个外部 API、用什么参数、如何处理失败如何被 Agent 准确发现也就是技能描述写得够不够清晰。所以我在项目里坚持一个原则Agent 里不放任何业务细节所有能被独立描述的能力全部下沉到 Skill 里。这样每个 Skill 都是一个可独立开发、独立测试、独立部署的模块新同学进来想给 Agent 加能力只需要照着 Skill 模板写一个技能包完全不需要理解 Agent 整体的调度逻辑这种“低耦合”的开发模式在多人协作时收益极大。2. AI Skills 到底怎么写从“一句话需求”到“可上线技能包”2.1 技能描述先行让 Agent “看见”这个技能AI Skills 的载体是一段结构化的技能描述文件通常叫 SKILL.md。很多新手写这个文件时最大的误区是把它当成给人类看的 README写一堆“本技能用于文字摘要”结果 Agent 根本不会主动调用它。原因很简单模型在判断是否调用某个技能时主要看技能描述里的触发条件是否和用户当前意图匹配描述越模糊被调用的概率就越低。我总结了一套比较可靠的写法一个 SKILL.md 文件分成前端配置和正文两大部分。前端配置用 YAML frontmatter 承载技能元信息正文部分用 Markdown 描述使用场景和细则。下面这个例子是我为一个“代码审查技能”写的 SKILL.md 的 frontmatter 部分结合了 qorder 这类编程辅助场景的实际需求--- name: code-review-skill description: 当用户提交代码片段或 PR 链接、要求做代码质量检查、寻找潜在 Bug、评估逻辑边界时使用。如果用户只是闲聊或询问一般编程概念不要使用本技能。 version: 1.0.0 author: your-name when_to_use: 用户在讨论具体代码实现、请求 review、或贴出报错栈并要求定位问题时 ---注意 description 里我特意写了“什么时候不要用”。这句话看起来不起眼但它能有效降低 Agent 的误调用率。我实测过加了排除条件之后误调用率从大约 15% 降到了 3% 以内。背后的逻辑是模型在做工具选择时本质上是在做“文本匹配”你提供的触发条件越精确匹配的边界就越清晰。这一点在很多 AI Agent 开发教程里不会强调但恰恰是决定体验的核心细节。2.2 定义动作接口参数比 Prompt 更重要SKILL.md 的正文部分不能只写“我会怎么做”更要写清楚“我需要什么参数”“我返回什么结构”。我把技能动作定义成接口的形式每个技能支持一到多个动作每个动作都有明确的输入输出。这套思路和开发 RESTful API 是一样的Skill 的调用方是 AgentAgent 需要根据技能的动作签名来填充参数动作接口定义得越清楚Agent 传参就越准确。用 YAML 给技能定义动作看起来是这样的actions: - name: review_code description: 对传入的代码片段执行静态审查返回问题列表与修改建议 parameters: - name: code_language type: string required: true description: 代码语言例如 python / javascript / go - name: code_content type: string required: true description: 待审查的代码正文 - name: check_security type: boolean required: false default: false description: 是否启用安全漏洞专项检查 output: type: object fields: - issue_count - issues - suggestion这个 skill 对应的是“编程好用的 AI 编程辅助能力”场景。参数里每个字段我都要写清楚类型的取值空间和默认值。有一个经验是Agent 模型非常擅长根据参数描述做填空但它不会去猜你没写的约束。如果你的 code_content 参数没有说明“接受 Base64 编码的字符串”当你传入二进制或超长代码块时聪明一点的模型可能自行截断不聪明的模型就直接报错了。把参数说明写到“字段级”是最划算的投入之一。2.3 给 Agent 出“面试题”离线验证技能边界Skill 写完之后最忌讳的事情就是直接扔到线上让 Agent 去试。我自己的习惯是先给 Skill 做一轮离线验证。具体做法是编写一批典型用户输入然后模拟 Agent 去调用这个 Skill看描述是否被准确触发、动作能否正确执行。我把这批测试输入称为“给 Agent 出的面试题”。以代码审查技能为例我会准备这些用例用例类型输入示例期望行为正面触发“帮我看看这段 Python 代码有没有并发问题”调用 review_codelanguagepython正面触发“这个 PR 的改动靠谱吗”调用 review_code需要设计拉取远程代码逻辑负面排除“Python 和 Go 哪个好”不调用 review_code走普通对话边界情况“这段代码在跑的时候 OOM 了”无代码正文先主动询问代码内容再决定是否调用参数补全“审查一下这段 JS重点看 XSS”没传 language根据内容推断语言自动补全 languagejavascript离线验证这一步看着简单但它能把大量问题拦截在部署之前。我经常发现某个技能写完之后Agent 在一次测试里连续触发错相邻技能其实就是两个 SKILL.md 里的 when_to_use 描述重叠了把重叠部分改清晰误触发就消失了。3. 腾讯云部署的完整链路上传、域名、端口一样都不能少3.1 Skill 上传之前要做好哪些本地检查当 Skill 内容在本地验证通过后才进入真正的部署环节。腾讯云上承载 AI Skills 的方式我比较推荐“对象存储/云函数 API 网关”的组合SKILL.md 和技能描述这类静态文件放对象存储需要真实计算逻辑的技能则放云函数再配合 API 网关对外暴露统一入口。这样拆分的好处是静态技能可以被多个 Agent 复用动态技能则可以独立扩缩容资源消耗和调用频率完全隔离。上传之前我在本地一定会做三个检查。第一是依赖声明完整凡是技能运行时要 import 的第三方库必须在打包配置里逐个列清楚腾讯云的云函数在安装依赖时一旦遇到缺失会直接拉取失败如果本地静默安装了某些包而没写进声明上传后就会出现“本地能跑、线上 500”的尴尬局面。第二是入口文件命名正确云函数平台通常要求固定入口文件名比如 index.py 里的 main_handler拼错一个字母整个函数就无法被触发。第三是 SKILL.md 的格式校验YAML 的缩进错位会导致 Agent 无法解析这个技能我在本地会先跑一遍 YAML parser 确认没有语法错误。提示上传 Skill 技能包之前可以先在本地用命令行工具跑一次“干跑”dry-run把技能包和 Agent 的调用链路都模拟一遍。我发现很多“上线后无法调用”的问题其实在本地干跑阶段就会暴露没必要把错误带上云端。3.2 二级域名申请与解析为什么我总是先在本地把 CNAME 写对接下来要解决的是给 API 网关绑定一个对外可访问的地址。这部分和腾讯云上申请二级域名的操作强相关。很多第一次接触云端部署的同学不理解“为什么不能直接用平台默认分配的地址”原因在于默认地址通常是一长串随机字符难以记忆而且当 Agent 需要回调或校验域名白名单时一个规整的二级域名远比随机字符串省心。申请二级域名的流程大概是先在域名注册控制台添加一个子域名记录比如 skill.example.com然后在 API 网关的自定义域名配置里绑定这个二级域名再按平台提示到 DNS 服务商处添加一条 CNAME 记录指向 API 网关分配的域名。这里有个关键细节CNAME 记录一定要先在本地确认解析值正确再操作否则平台侧校验域名归属时很可能失败。我试过几次在控制台直接复制粘贴结果从别处复制来的值带了空格提交失败后排查了大半天最后发现只是多了一个不可见字符非常浪费时间。绑定完成之后还有一个经常被忽略的点如果你要开 HTTPS别忘记申请 SSL 证书并完成证书配置。Agent 的运行时和模型网关在做外部调用时对自签名证书非常不友好不少大模型 API 在收到一个不安全连接时直接就是 403。所以你在腾讯云上绑定二级域名之后顺手把证书托管也做了后续能省掉大量 TLS 握手报错。3.3 端口开放与安全组“端口不通”和“权限过宽”是同一个问题的两面另一类高频问题是端口配置。云函数本身没有传统意义上的端口监听概念但如果你在云服务器或容器里部署 Agent 运行时比如自建了一个 LiteLLM Proxy、跑了一个 Harness 服务、或者临时用内网穿透工具调试那就必然要和“入站规则”“安全组开放端口”打交道。我的建议是遵循最小开放原则默认不开放任何公网端口只有需要被公网访问的服务才按需放行。在腾讯云的安全组控制台里你需要同时配置入站规则和出站规则。入站规则是别人访问你的服务的入口出站规则是你的服务访问外部网络的能力。出现过 Agent 调用外部 API 一直超时的情况结果不是入站端口的问题而是出站规则把到目标地址的流量拦了。排查网络问题时两条规则都要看别只盯着入站。以我部署 LiteLLM Proxy 为例它是统一管理多个模型 API 的代理服务默认监听 8000 或 4000 端口。我在安全组里只放行了 4000 端口来源 IP 范围设置成仅允许自己的出口 IP然后加上一条 443 端口给 HTTPS 访问留门其他端口一律拒绝。这样即使代理服务本身有漏洞被外部探测到的概率也大大降低。端口放行后用这条命令做连通性测试是最快的curl -v https://skill.example.com/v1/models如果看到 HTTP 200 或者模型列表 JSON说明域名解析、证书校验、安全组放行、服务监听全部正常如果返回超时或连接被拒那就按照 DNS 解析、TCP 连通性、服务状态、安全组规则这个顺序从上到下排查。我把这个检查顺序写进项目文档里每次新环境部署都按顺序过一遍几乎不会卡住。4. 把 Skill 接到 Agent 运行时一次完整的联调记录4.1 为什么我这里选了 LiteLLM Proxy 做统一网关技能开发完、基础设施就绪后下一步是让 Agent 运行时能真正消费这些 Skill。我这里选择引入 LiteLLM Proxy 作为统一的模型访问网关而不让 Agent 直接调用各家模型的原始 API。这么做有三个原因。第一是接口标准化。不同的模型服务商提供的 API 格式差异较大有的走 OpenAI 兼容格式有的是 Anthropic 风格Skill 如果依赖 Agent 直接调用这些五花八门的接口技能内部就要写很多兼容代码。LiteLLM Proxy 会把所有上游模型接口都转成统一的 OpenAI 格式Skill 只需实现一个客户端协议就能访问不同模型真正做到了“一套代码多家模型”。第二是配置管理集中化。API Key 散落在各个 Skill 的配置文件里是非常危险的事情一旦某个配置文件被误提交到代码仓库密钥就泄露了。我把所有模型 API Key 集中放在 LiteLLM Proxy 的环境变量或密钥管理服务里Skill 本身不感知具体 Key它在运行时只需要访问网关地址由网关负责鉴权和计费。这样既降低了密钥泄露风险也方便做调用量审计。第三是能统一处理重试与限流。Skill 在做真实的业务调用时上游模型经常会出现限流429或临时过载5xx如果每个 Skill 都自己实现一套重试策略代码重复而且行为不一致。LiteLLM Proxy 在网关层统一做重试、超时和熔断Skill 面对的是一个“更稳定”的模型后端故障处理起来要轻松得多。4.2 从“调不通”到“跑起来”一次典型的 timeout 排查理论说完分享一次真实又典型的排障经历。某个 Skill 上线后Agent 执行到一半给我的日志里出现了类似“agent execution provider did not respond in time”的报错。这个报错从字面看是 Agent 执行提供方没有在时限内响应但具体情况需要抽丝剥茧。我先做了三层定位。第一层看 Agent 日志确认它已经把 Skill 的调用请求发出了第二层到 LiteLLM Proxy 的访问日志里查结果根本没看到这条请求进来说明请求可能在到达网关之前的链路就断了第三层打开云服务器上的 tcpdump 抓包发现 TCP 握手能完成但应用层一直没有返回数据。排查到这里我大概猜到了问题方向不是代理服务没起来而是它监听的对象不对。跑到服务器上用命令确认了一下netstat -tlnp | grep 4000结果发现进程确实在 4000 端口上不过监听地址写的是 127.0.0.1也就是只允许本机访问。外部请求经过安全组放行、到达云服务器之后发现这个端口上并没有一个对外可见的服务在接收流量请求自然就挂住了。把 LiteLLM Proxy 的监听地址从 127.0.0.1 改成 0.0.0.0 再重启然后再执行一次 curl 命令立刻就通了。这个问题排查过程大概花了我四十分钟核心原因就一句话服务监听的网卡和外部访问的路径不一致。还有一次遇到的是“agent execution terminated due to error”这是更笼统的报错。一步步查下来才发现是 Skill 里调用外部 API 时设置了太短的超时时间而那个上游接口因为业务高峰平均响应就要 8 秒结果每次调用都在 5 秒超时后被强制中断。我把 Skill 内部 HTTP 客户端的超时时间从 5 秒调整到 15 秒同时把重试策略从“重试 3 次”改成“重试 2 次开启退避”问题就消失了。这里也想提醒大家Agent 整体的超时时间和单个 Skill 内部调用的超时时间要匹配否则内层还没跑完外层就已经判定执行超时了这种错误报出来非常难查。5. 避坑速查表我在这条路上反复踩过的坑经历了多个项目的实际打磨之后我把自己反复踩过的坑整理成一张速查表发布 AI Skills 前逐条过一遍能躲掉 80% 的线上故障。坑位典型表现排查方向一劳永逸的做法端口未放行Agent 回调超时curl 不通安全组入站规则、服务监听地址最小化放行端口并写进 IaC禁止控制台手改CNAME 解析漂移域名时而通时而不通DNS 解析记录是否变更在 Cloudflare/腾讯云 DNS 控制台锁住记录SKILL.md 描述含糊Agent 永远不调用该技能看 Agent 的工具选择日志描述中写清楚触发条件与排除条件缺少必要字段技能执行报参数错误看 Agent 实际传参结果动作参数定义到字段级并给默认值内层超时小于外层技能被外层强制中止检查各环节超时配置按链路最短原则倒推设定超时参数API Key 泄露风险代码仓库扫描出密钥git 历史中查找已暴露的 Key一律走环境变量/密钥管理禁止硬编码通配端口开放服务器被扫描爆破安全组规则是否 0.0.0.0/0 全放只放行必要端口并限定来源 IP监听 127.0.0.1外网访问不通进程监听地址是否绑定所有网卡明确设置 HOST0.0.0.0 并通过 curl 验证其中 SKILL.md 描述含糊这条值得展开说。有一次我写了一个“数据恢复分析”技能description 写着“当用户提到文件系统或数据恢复时使用”。结果实际使用中用户只是在问“Linux 下误删除的文件还能找回来吗”Agent 就触发了这个技能去调用底层的数据恢复工具差点把正在运行的服务目录扫描了一遍。后来我把 description 改成“当用户要求对指定路径执行数据恢复操作、需要扫描文件系统元数据时使用若只咨询恢复原理而不涉及具体操作应仅提供理论回答”。改完之后技能被准确调用的次数直线上升误触发问题基本消失。这件事给我的启发是写技能描述最关键的不是告诉 Agent“我能做什么”而是告诉它“什么情况下该用我什么情况下不该用我”。这个分寸感决定了 Agent 整体的智能度。还有一个小技巧想分享如果一个 Agent 同时挂了多个 Skill尽量让每个技能的 description 里包含该技能独有的动作词。比如代码审查技能里带“review”“PR”“bug 排查”这类高频词代码生成技能里带“写出”“实现”“生成函数”这类词技能之间重叠的语义越少模型在做意图路由时困惑就越少。如果发现两个技能经常被同时唤起优先检查它们之间是否存在同一个触发词这时候不一定是提示词写得不好也可能两个技能本来就应该合并成一个大技能。6. 关于“框架选型与安全”我最后想说的几点Agent 技能化改造做完后团队里有人问过我一个问题要不要引入一个更重的 Agent 框架来做任务编排我理解这个想法市面上像 Harness 这类工具确实能把 Agent 执行过程可视化、流程化看起来很“正规”。但这里必须分清诉求层次。如果你只是需要 Agent 能够按顺序调用几个 API、做几次条件判断那么自己维护一套轻量的 Skill 调度逻辑可能更快如果你的场景里有复杂的多 Agent 协作、需要暂停恢复、人工审批、分支回滚那引入 Harness 这类框架就是合理的。我在项目中采用的是一个折中方案编排层保持轻量把“当前的用户意图对应到哪个 Skill”的选择逻辑外置到一个可配置的路由表中。这样既不上重框架又不用把全部逻辑硬编码在 Prompt 里。对于大多数中低频的 Agent 场景来说这种“规则路由 Skill 调用”的混合模式可能比纯靠模型做工具选择更可控尤其在业务方要求技能执行结果“可解释”的时候规则路由天然就有审计日志。安全性方面我再补充一个容易被忽略的细节Agent 在调用 Skill 的时候会把自己的对话上下文打包传给 Skill。如果上下文中包含敏感信息比如生产环境的数据库连接串、客户的个人信息、内部系统的凭据这些信息就可能被 Skill 里的模型请求带回给上游模型厂商。所以我在设计 Skill 的动作参数时建立了一个“最小字段原则”Skill 不能拿到整个对话上下文只能拿到动作参数里明确声明的那几个字段。这个原则能避免很多隐含的数据外泄风险。我在腾讯云控制台做权限配置时也会为每个 Skill 关联独立的子账号或角色只授予它真正需要的资源访问权限最小权限原则放在 AI 应用里同样适用。最后的实操体会这套“腾讯云 AI Skills 最佳实践”从拆解、编写、部署到联调整条链路我在多个项目里反复验证过最大的感受是AI Skills 的价值不在“写得好不好”而在“能不能被 Agent 正确发现、稳定执行、快速排障”。技能包拆得再漂亮如果 Agent 的调度层不理解触发条件一切白搭部署链路再稳如果技能描述里的排除条件写得不清楚线上的误调用就会一直消耗你的额度。所以我在每次发布新 Skill 之前一定会做两件事第一打开 Agent 的日志看技能是否有被正确触发第二故意准备几个“不该调用本技能”的输入去测试它会不会误触发。这两关过了才敢真正上线。把“技能开发”这件事当成“给 Agent 培养一个靠谱的同事”沟通清楚边界、提供清晰的接口、建立完善的反馈机制Agent 才会越来越可靠。