讲件我最近鼓捣了很久的事Agent 开发。前几个月我一直有两个困惑一是网上大家都在说 Agent 能自动干活可真到自己上手写的时候总觉得模型不吃指令二是光会写提示词还不够一涉及真实项目就得连部署带调接口环境全是坑。后来我索性把一套名叫“腾讯云 AI Skills”的机制翻了个底朝天拿来养自己手头的 Agent终于把“只会聊天”变成了“能按流程出活”。这篇文章不聊虚的我只讲自己验证过的操作思路和最容易踩的坑。哪怕是刚接触 Agent 的新手照下面的步骤走也能在腾讯云环境里把一个小而完整的“全能 Agent”跑起来。先说结论Agent 好不好用不看模型多聪明而看你会不会把能力拆成 Skills 喂给它。1. Agent 和 Skills 到底是啥关系1.1 Agent 不是一个能聊天的壳现在市面上大量 Demo 都把自己叫 Agent但很多本质还是“聊天机器人套了一层 CSS”。真正的 Agent 起码要具备三样东西会拆解目标、能调用工具、能根据中间结果调整策略。你可以把它理解成雇了一个实习生你给它一句“帮我搞定这件事”它得自己分解成查资料、写代码、跑测试、出报告几个环节然后逐项执行。我习惯把 Agent 分成两层底层是“大脑”也就是大模型上层是“手脚”也就是工具与流程。大脑负责理解和推理手脚负责把推理落到实际动作上。绝大多数人在底层选型上花了很多心思却忽略了上层工具编排结果就是模型能力很强但干不了实事。1.2 Skills 机制解决的就是“手脚不够用”Skills 直译过来是“技能”在 Agent 体系里它指一段结构化的能力定义包含任务描述、触发条件、执行步骤和输出格式。比如我想让 Agent 帮我写专利交底材料辅助以前得在对话框里反复提醒模型“按专利模板写”“要有技术问题、技术方案、有益效果”现在不需要。我把这套要求封装成一个 Skill 文件Agent 一旦收到相关任务就会自动加载并执行。你可以把 Skills 理解为公司里的 SOP。新员工再怎么聪明没有一套明确的流程文档也会把事做偏。Agent 也一样模型天然不会稳定遵守很多人脑中的“潜规则”你必须在 Skills 里把规则写死、写细、写可执行。1.3 为什么“Skills”成了 Agent 圈热门词最近无论是 Claude Code 的官方 Skills还是 Codex、OpenCode 等框架都在强调这种机制。原因不复杂预训练大模型的通用能力已经够用竞争焦点转移到“如何低成本地让模型适配具体业务”。微调成本高、周期长数据还难搞Skills 则完全不同它只需要你写文档把能力模块化随时加载、随时卸载。拿我自己的项目举例我用腾讯云跑 Agent 时一开始把十几个功能全写进一个大提示词里结果模型老是忘掉后面的步骤。后来我把每个功能拆成独立 Skills按需加载准确率直接提升一个台阶。从社区反馈来看这也是现在做 Agent 的最佳实践从“拼模型”转向“拼技能包”。2. 腾讯云 AI Skills 的整体设计思路2.1 选腾讯云做落地的逻辑可能有人问做 Agent 不是本地搞个大模型就行了吗实测下来本地跑的 Agent 能力非常有限尤其是要接业务数据、要长期持续运行、要对外提供服务时一台个人电脑撑不住。我在腾讯云上跑 Agent主要图三点一是环境稳定不用操心断电断网二是对象存储、域名、API 网关这些配套能力强Agent 需要对外暴露接口时特别顺手三是人工智能开发相关服务齐全应用发布链路短。这里要单独说明一下标题里的“腾讯云 AI Skills”并不只是一个技术文件更接近一套云端开发的最佳实践。核心流程是在本地把 Agent 的能力拆好然后在云端准备好运行环境把技能包传上去通过 API 网关或域名暴露服务最后让 Agent 在云端持续对外提供服务。2.2 Skills 加载的本质是“内外双循环”我自己的理解是腾讯云 AI Skills 加载体系存在两个循环。内循环发生在模型推理前系统会先看用户输入触发了哪些 Skills把对应的提示词片段注入上下文外循环发生在模型推理后Agent 需要执行具体动作时会调用云端写好的 API 工具。两个循环互相配合Agent 才能既有“思维”又有“行动”。试着把这个概念讲得更直白一点内循环像是给模型看菜谱“今天客户点了红烧肉你就按这张红烧肉的菜谱做”外循环像是让模型去拿菜刀、开火、起锅。只有菜谱没有厨具光说不练只有厨具没有菜谱乱炖一气。AI Skills 的价值就是同时解决“做什么”和“用什么做”。2.3 这套设计比传统 Bot 好在哪传统任务型 Bot 多采用“意图识别 槽位填充 固定对话流”的方式。好就好在逻辑可控坏也坏在逻辑太死。用户换一种问法模型就不知道你是不是要订机票了。而基于 Agent Skills 的设计不需要穷举所有可能提问只看用户当前任务是否命中某个 Skill。在真实工程里这意味着维护成本转移到技能文档上。传统 Bot 加一个新功能要重新设计对话流、标数据、训练意图模型Skills 方案则是写一份新文档告诉模型“遇到这类问题按这个流程走”半天就能上线。我试过用同样的服务接入不同业务场景传统 Bot 得重新搭一套而我的 Agent 只需要调整加载的 Skills 集合省了至少一半工作量。3. 动手实操把一个 Agent 从零跑起来3.1 先确定你的最小可用 Agent 范围新手最容易犯的错就想着一步到位做一个“全能 Agent”结果路线图越画越复杂最后直接放弃。我的建议是先圈一个极窄的场景把链路跑通再慢慢往上加。最近我在做的实验是让 Agent 辅助我整理技术文档并补全专利申请方向的内容拆解。这个场景很适合练手因为它不涉及太复杂的实时交互主要考察 Agent 的资料处理能力、文档结构能力和格式输出能力。我把这个 Agent 定位成“内容辅助类 Agent”初始需要四个 Skills资料收集 Skill、内容结构化 Skill、措辞审查 Skill、格式输出 Skill。每个 Skill 负责一个环节Agent 接收到任务请求后按照顺序依次加载对应 Skill 模块整个流程就自动跑起来了。3.2 准备运行环境与技能包结构我用的是比较稳妥的路线在腾讯云服务器上直接布了一套 Python 应用环境配合对象存储来存放 Agent 的技能文档。之所以选 Python不是因为其他语言不行而是后续要挂 AI 开发套件、处理文本数据时生态最省心。技能包的文件结构我参考了 Claude Code Skills 和 Codex Skills 的思路大致长这样agent-skills/ ├── skills/ │ ├── research/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── structure/ │ │ ├── SKILL.md │ │ └── examples/ │ ├── review/ │ │ ├── SKILL.md │ │ └── rules/ │ └── output/ │ ├── SKILL.md │ └── templates/ └── config.yaml每个 Skill 目录下必须有一个SKILL.md作为入口文件。这个文件的作用相当于给 Agent 看的说明书我通常会在里面写清楚三块内容这个技能是做什么的、什么情况下触发、具体执行步骤是什么。下面我拿一个简化版做示例。3.3 写一份可执行的 SKILL.md许多人第一次写 Skills 时容易写得很意识流比如“帮助用户高效地对文档进行深度的结构化处理”。问题是模型看完这种描述还是不知道具体怎么做。正确的写法是给出判断条件 处理步骤 产出规范。以“资料收集 Skill”为例我简化的SKILL.md如下# Skill: 资料收集 ## 描述 当用户请求涉及“找资料、整理参考、搜索背景”时使用本技能。 先判断信息缺口再根据缺口类型选择内部知识库或联网检索 最终输出一份带来源标注的资料清单。 ## 步骤 1. 拆分用户需求列出至少 3 个关键词维度。 2. 判断关键词维度是否超出当前上下文知识若是则调用检索工具。 3. 对检索结果做去重和可信度排序。 4. 输出资料清单每条包含标题、来源、核心观点、可用程度。 ## 输出格式 返回 Markdown 表格需求维度、检索关键词、可用资料、信息来源、备注。这不是我拍脑袋编的格式Claude Code 官方文档里也强调过类似原则即 Skills 文件要“自包含、结构化、可复用”。写好之后模型会把这个文件当作一种“临时技能”加载进推理上下文后面的行为就不再是自由发挥而是有章可循。3.4 把 Agent 和 Skills 部署到腾讯云本地测试通过之后我开始把 Agent 部署到腾讯云上。第一步是在服务器里建应用目录把技能文件传到指定位置。这一步大家容易踩一个坑项目文件路径里面尽量不要有中文和空格不然后面配置系统服务时经常出现查不出来的玄学问题。我习惯统一采用英文目录 下划线命名比如/home/agent/agent_skills。第二步是把 Agent 跑成后台服务。我们要的不是“用 SSH 窗口挂着跑”因为一旦窗口关闭进程就没了。建议用systemd或容器方式管理进程。这里贴一段我用systemd管理 Agent 服务的配置[Unit] DescriptionMy Agent Service Afternetwork.target [Service] Userubuntu WorkingDirectory/home/agent ExecStart/home/agent/venv/bin/python main.py Restartalways RestartSec5 [Install] WantedBymulti-user.target配置好之后执行sudo systemctl enable myagentAgent 服务就能够在后台持续运行。第三步是到域名服务商解析一个二级域名指向服务器再把域名信息填到腾讯云的 API 网关配置里这样外部请求就能通过网络访问到 Agent 能力了。这一步对新手来说像天书其实逻辑很简单服务器地址是一串难记的 IP域名就是个门牌号API 网关相当于前台。整个部署链路我整理成了一张表方便大家自查环节作用常见入口易错点云服务器跑 Agent 主程序控制台 / SSH忘记开对应端口对象存储放 Skills 文档和素材存储桶列表权限设为私有导致读取失败域名解析把 IP 映射成好记的域名DNS 解析控制台记录类型选错API 网关暴露 HTTP 接口API 网关控制台后端超时时间设太短系统服务守护 Agent 进程systemd / Docker服务退出后不会自动重启3.5 开放与安全怎么平衡相关热搜词里有“腾讯云如何开放所有端口”这种问题但我必须提醒一句千万别为了图省事把安全组规则设置成允许所有端口对所有来源开放。一旦这么干服务器基本上就是在公网上裸奔扫描器用不了几分钟就能找到你。正确做法是安全组只放行需要的端口比如 Web 服务只放行 80/443SSH 登录只放行你自己的 IP。如果你做的是内部实验还可以用密钥登录代替密码登录。我在腾讯云上一开始图方便用的密码登录结果日志里天天有陌生 IP 尝试暴力破解。后来改成密钥登录 禁用密码登录这类告警基本消失了。做 Agent 服务也是一样对外暴露的能力越多越要管好认证和鉴权。4. Skills 应该怎么写才叫“好”4.1 好 Skill 的五个可观测特征写多了之后我总结出一个好 Skills 应该具备的几个特征。首先是任务边界清晰一份 Skills 只负责一类事情不要又是文档处理又是代码生成混杂在一起模型很容易混乱。其次是触发条件明确模型得有办法判断“现在该不该用这个技能”。第三是步骤可执行不要有含糊建议而是明确的动作。第四是包含验收标准让 Agent 自己检查自己干完没干完。最后是能独立测试随时可以把某个 Skill 单独拎出来验证。我自己在做 code review 时会准备一套 Codex Skills 风格的规则文件里面会把代码里常见的坑一条条列出来。Agent 执行完代码审查就会按照规则逐项比对并输出一份问题清单。实测下来虽然比资深工程师人工审略粗糙但胜在速度快什么问题都逃不过规则扫描适合做第一道关卡。4.2 常见的三种 Skills 分类写法按任务类型来分我个人常把 Skills 分成三类。第一类是“文档型技能”功能是生成文档或内容比如写周报、写专利交底材料、写接口文档写法上最重要的是模板要详细需要给出段落结构和句式示例。第二类是“判断型技能”比如代码审查、合规审查、质量检查这种写法要把标准写成 checklist让 Agent 按清单逐项打钩并输出评判原因。第三类是“任务型技能”需要调用外部工具比如发消息、查数据库、调 API这种写法的关键是工具调用的参数必须描述准确甚至要给样例值。很多教程会把 Skills 写得特别玄。其实落实到根上Skills 就是把你脑子里的做事步骤外置成文档。以前你在公司带新人靠嘴说现在带 Agent 靠文档写。越是熟练的专家越容易忽略自己日常工作里的隐性知识写 Skills 的过程相当于强制把这些隐性知识挖出来变成显性的。4.3 如何高效测试和迭代你的 SkillsSkills 写完不是一劳永逸必须反复打磨。我常用一个笨办法准备大约 10 条覆盖正常场景、边界场景、异常场景的测试用例每次都让 Agent 跑一遍看哪些用例没过。比如我写“内容结构化”这个 Skill 时最开始它对生僻的科技类文本结构判断很差后来我在 examples 里面补了几个真实案例效果立刻改善。另一个重要技巧是让 Agent 在跑完任务后输出“执行日志”记录自己用了哪些 Skills、哪些步骤存在不确定性。这样我可以一目了然看出问题出在哪是因为触发条件没写明白还是因为步骤里有歧义。这里特别推荐一个思路把“写 Skill”本身也做成一个 Skill让它分析现有任务、生成技能初稿再由人来审查。用 AI 辅助写技能本质上就是在做提示词工程但产出物更结构化也更容易复用。5. 一些绕不开的坑和排查思路5.1 Agent 为什么经常不按 Skill 走我早期遇到最头疼的问题是明明写了 Skill 文件Agent 却当它不存在。排查下来大概率是这几类原因触发条件写得模糊模型无法把用户问题关联到技能上上下文太长Skill 内容被模型忽略了多个 Skill 互相冲突模型不知道听谁的。对应解决方案也清晰把触发关键词写完整把同一场景下激活的 Skill 数量控制在 5 个以内按优先级排序并减少无关上下文对模型判断的干扰。需要注意的是有些 Agent 框架只有在特定模式下才会加载本地 Skills比如我用的工具要求先识别用户意图属于某个 Skill 目录再动态注入文件。如果你发现自己写的 Skills 没有生效先不要怀疑模型能力而是查框架的日志看它到底有没有读取、注入对应的SKILL.md。很多问题出在路径配置或文件命名上而不是你写的内容有问题。5.2 性能慢、跑飞了的优化策略Skill 加载后本质上是给模型增加了一部分上下文所以如果你的技能包写得过于冗长每一次调用都会导致 token 消耗激增、响应变慢。我习惯把每份SKILL.md控制在 200 行以内涉及大量规则或模板的拆到引用目录里按需读取。这就好比开会你只需要叫相关的人到场而不是全公司都坐在会议室里听一个不相关的议题。当 Agent 出现输出格式不稳定时最好的办法是做“小步迭代”不要一次性让 Agent 完成一整篇报告而是先让它输出大纲再分段生成详情最后再统一排版。实测下来这种分步处理不仅能降低格式跑偏的概率也更容易定位到底是哪一步出了问题。5.3 部署中常见问题速查表把最近自己在部署过程中常遇到的问题整理成一个速查表碰到类似情况的同学可以直接照做现象可能原因排查与解决外部访问不到 Agent 服务安全组端口未放行或服务未监听检查云控制台安全组规则执行curl 127.0.0.1:端口确认本地服务存活Skills 文件读取报权限错误对象存储私有权限或本地文件属主不符在服务器上用启动用户执行确认读取路径有执行权限Agent 答非所问全局提示词与 Skills 触发条件冲突精简全局提示词让“即时反应”让位给“技能加载”输出格式乱Skill 中缺少输出模板在 Skill 的 examples 中补充一个符合预期的标准输出案例进程莫名其妙退出内存不足或未被守护用 systemd 配置Restartalways另查内存占用情况二级域名访问时证书报错未申请/未成功绑定 HTTPS 证书确认域名解析记录指向服务器公网 IP控制台上传或自动申请证书并完成绑定5.4 打磨一下全局提示词别让它“指挥”模型干杂活全局提示词和 Skills 的关系很多人一开始会搞混。打个比方全局提示词像是公司的企业文化Skills 则是具体的岗位手册。企业文化再强员工要是不知道自己具体负责哪个环节依然办不成事。所以我建议全局提示词里少写具体流程多写角色定位和核心原则把可执行的细节全部下沉到 Skills 里。我在最初写 Agent 时总忍不住在系统提示词里写“你要一步一步严谨思考”结果模型每次输出都很用力地自我证明但任务完成质量并没有提升。后来我把所有任务细节都挪到 Skills 里全局提示词只保留“你是我的全能助理优先根据已加载技能处理任务没匹配到技能时再按通用能力处理”效果反而稳定得多。好的 Agent 结构一定是很干净的大脑只做决策知识都在外部文档里动作全靠工具触达。6. 实践中的一些心得与下一个阶段扩展整个过程试下来最大的感受是Agent 开发的门槛正在快速降低但工程化的思维反而变得更加重要。以前的开发是画流程图现在的开发更接近“写说明书 配工具”。你不需要从零实现复杂的调度逻辑但你必须能想清楚业务流程里的每个环节、每个异常分支该怎么处理。Skills 机制让我能把生活与工作里很多重复的判断“外包”出去这点带来的价值比单纯追求某个大模型版本更新要高得多。沿着这个方向后面我打算继续做两个扩展第一个是把多模态素材管理做成一个 Skill让 Agent 能理解视频深度估计、图像分类等场景的输出第二个是尝试用 Agent 分析项目报告的结构自动补全专利申请中比较繁琐的背景技术与有益效果段落。前端开发 Skills、Claude Code Skills 甚至一些个人兴趣向的 Skills我也已经在本地开始测试效果惊喜。最后分享一个实用小技巧与其追求大而全的 Agent 系统不如先选准一个你每周都在重复、耗时 30 分钟以上的任务把它做成 Skill。当你真正跑通一次“从人工操作到 Agent 自动完成”的流程之后那种成就感会驱动你把更多繁琐事交给它。Agent 养成这件事没有终点今天它只会帮你整资料明天它能协助你写代码后天它可能就成了你离不开的数字同事。
Agent开发实战：用腾讯云AI Skills把提示词变成可执行的技能包
讲件我最近鼓捣了很久的事Agent 开发。前几个月我一直有两个困惑一是网上大家都在说 Agent 能自动干活可真到自己上手写的时候总觉得模型不吃指令二是光会写提示词还不够一涉及真实项目就得连部署带调接口环境全是坑。后来我索性把一套名叫“腾讯云 AI Skills”的机制翻了个底朝天拿来养自己手头的 Agent终于把“只会聊天”变成了“能按流程出活”。这篇文章不聊虚的我只讲自己验证过的操作思路和最容易踩的坑。哪怕是刚接触 Agent 的新手照下面的步骤走也能在腾讯云环境里把一个小而完整的“全能 Agent”跑起来。先说结论Agent 好不好用不看模型多聪明而看你会不会把能力拆成 Skills 喂给它。1. Agent 和 Skills 到底是啥关系1.1 Agent 不是一个能聊天的壳现在市面上大量 Demo 都把自己叫 Agent但很多本质还是“聊天机器人套了一层 CSS”。真正的 Agent 起码要具备三样东西会拆解目标、能调用工具、能根据中间结果调整策略。你可以把它理解成雇了一个实习生你给它一句“帮我搞定这件事”它得自己分解成查资料、写代码、跑测试、出报告几个环节然后逐项执行。我习惯把 Agent 分成两层底层是“大脑”也就是大模型上层是“手脚”也就是工具与流程。大脑负责理解和推理手脚负责把推理落到实际动作上。绝大多数人在底层选型上花了很多心思却忽略了上层工具编排结果就是模型能力很强但干不了实事。1.2 Skills 机制解决的就是“手脚不够用”Skills 直译过来是“技能”在 Agent 体系里它指一段结构化的能力定义包含任务描述、触发条件、执行步骤和输出格式。比如我想让 Agent 帮我写专利交底材料辅助以前得在对话框里反复提醒模型“按专利模板写”“要有技术问题、技术方案、有益效果”现在不需要。我把这套要求封装成一个 Skill 文件Agent 一旦收到相关任务就会自动加载并执行。你可以把 Skills 理解为公司里的 SOP。新员工再怎么聪明没有一套明确的流程文档也会把事做偏。Agent 也一样模型天然不会稳定遵守很多人脑中的“潜规则”你必须在 Skills 里把规则写死、写细、写可执行。1.3 为什么“Skills”成了 Agent 圈热门词最近无论是 Claude Code 的官方 Skills还是 Codex、OpenCode 等框架都在强调这种机制。原因不复杂预训练大模型的通用能力已经够用竞争焦点转移到“如何低成本地让模型适配具体业务”。微调成本高、周期长数据还难搞Skills 则完全不同它只需要你写文档把能力模块化随时加载、随时卸载。拿我自己的项目举例我用腾讯云跑 Agent 时一开始把十几个功能全写进一个大提示词里结果模型老是忘掉后面的步骤。后来我把每个功能拆成独立 Skills按需加载准确率直接提升一个台阶。从社区反馈来看这也是现在做 Agent 的最佳实践从“拼模型”转向“拼技能包”。2. 腾讯云 AI Skills 的整体设计思路2.1 选腾讯云做落地的逻辑可能有人问做 Agent 不是本地搞个大模型就行了吗实测下来本地跑的 Agent 能力非常有限尤其是要接业务数据、要长期持续运行、要对外提供服务时一台个人电脑撑不住。我在腾讯云上跑 Agent主要图三点一是环境稳定不用操心断电断网二是对象存储、域名、API 网关这些配套能力强Agent 需要对外暴露接口时特别顺手三是人工智能开发相关服务齐全应用发布链路短。这里要单独说明一下标题里的“腾讯云 AI Skills”并不只是一个技术文件更接近一套云端开发的最佳实践。核心流程是在本地把 Agent 的能力拆好然后在云端准备好运行环境把技能包传上去通过 API 网关或域名暴露服务最后让 Agent 在云端持续对外提供服务。2.2 Skills 加载的本质是“内外双循环”我自己的理解是腾讯云 AI Skills 加载体系存在两个循环。内循环发生在模型推理前系统会先看用户输入触发了哪些 Skills把对应的提示词片段注入上下文外循环发生在模型推理后Agent 需要执行具体动作时会调用云端写好的 API 工具。两个循环互相配合Agent 才能既有“思维”又有“行动”。试着把这个概念讲得更直白一点内循环像是给模型看菜谱“今天客户点了红烧肉你就按这张红烧肉的菜谱做”外循环像是让模型去拿菜刀、开火、起锅。只有菜谱没有厨具光说不练只有厨具没有菜谱乱炖一气。AI Skills 的价值就是同时解决“做什么”和“用什么做”。2.3 这套设计比传统 Bot 好在哪传统任务型 Bot 多采用“意图识别 槽位填充 固定对话流”的方式。好就好在逻辑可控坏也坏在逻辑太死。用户换一种问法模型就不知道你是不是要订机票了。而基于 Agent Skills 的设计不需要穷举所有可能提问只看用户当前任务是否命中某个 Skill。在真实工程里这意味着维护成本转移到技能文档上。传统 Bot 加一个新功能要重新设计对话流、标数据、训练意图模型Skills 方案则是写一份新文档告诉模型“遇到这类问题按这个流程走”半天就能上线。我试过用同样的服务接入不同业务场景传统 Bot 得重新搭一套而我的 Agent 只需要调整加载的 Skills 集合省了至少一半工作量。3. 动手实操把一个 Agent 从零跑起来3.1 先确定你的最小可用 Agent 范围新手最容易犯的错就想着一步到位做一个“全能 Agent”结果路线图越画越复杂最后直接放弃。我的建议是先圈一个极窄的场景把链路跑通再慢慢往上加。最近我在做的实验是让 Agent 辅助我整理技术文档并补全专利申请方向的内容拆解。这个场景很适合练手因为它不涉及太复杂的实时交互主要考察 Agent 的资料处理能力、文档结构能力和格式输出能力。我把这个 Agent 定位成“内容辅助类 Agent”初始需要四个 Skills资料收集 Skill、内容结构化 Skill、措辞审查 Skill、格式输出 Skill。每个 Skill 负责一个环节Agent 接收到任务请求后按照顺序依次加载对应 Skill 模块整个流程就自动跑起来了。3.2 准备运行环境与技能包结构我用的是比较稳妥的路线在腾讯云服务器上直接布了一套 Python 应用环境配合对象存储来存放 Agent 的技能文档。之所以选 Python不是因为其他语言不行而是后续要挂 AI 开发套件、处理文本数据时生态最省心。技能包的文件结构我参考了 Claude Code Skills 和 Codex Skills 的思路大致长这样agent-skills/ ├── skills/ │ ├── research/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── structure/ │ │ ├── SKILL.md │ │ └── examples/ │ ├── review/ │ │ ├── SKILL.md │ │ └── rules/ │ └── output/ │ ├── SKILL.md │ └── templates/ └── config.yaml每个 Skill 目录下必须有一个SKILL.md作为入口文件。这个文件的作用相当于给 Agent 看的说明书我通常会在里面写清楚三块内容这个技能是做什么的、什么情况下触发、具体执行步骤是什么。下面我拿一个简化版做示例。3.3 写一份可执行的 SKILL.md许多人第一次写 Skills 时容易写得很意识流比如“帮助用户高效地对文档进行深度的结构化处理”。问题是模型看完这种描述还是不知道具体怎么做。正确的写法是给出判断条件 处理步骤 产出规范。以“资料收集 Skill”为例我简化的SKILL.md如下# Skill: 资料收集 ## 描述 当用户请求涉及“找资料、整理参考、搜索背景”时使用本技能。 先判断信息缺口再根据缺口类型选择内部知识库或联网检索 最终输出一份带来源标注的资料清单。 ## 步骤 1. 拆分用户需求列出至少 3 个关键词维度。 2. 判断关键词维度是否超出当前上下文知识若是则调用检索工具。 3. 对检索结果做去重和可信度排序。 4. 输出资料清单每条包含标题、来源、核心观点、可用程度。 ## 输出格式 返回 Markdown 表格需求维度、检索关键词、可用资料、信息来源、备注。这不是我拍脑袋编的格式Claude Code 官方文档里也强调过类似原则即 Skills 文件要“自包含、结构化、可复用”。写好之后模型会把这个文件当作一种“临时技能”加载进推理上下文后面的行为就不再是自由发挥而是有章可循。3.4 把 Agent 和 Skills 部署到腾讯云本地测试通过之后我开始把 Agent 部署到腾讯云上。第一步是在服务器里建应用目录把技能文件传到指定位置。这一步大家容易踩一个坑项目文件路径里面尽量不要有中文和空格不然后面配置系统服务时经常出现查不出来的玄学问题。我习惯统一采用英文目录 下划线命名比如/home/agent/agent_skills。第二步是把 Agent 跑成后台服务。我们要的不是“用 SSH 窗口挂着跑”因为一旦窗口关闭进程就没了。建议用systemd或容器方式管理进程。这里贴一段我用systemd管理 Agent 服务的配置[Unit] DescriptionMy Agent Service Afternetwork.target [Service] Userubuntu WorkingDirectory/home/agent ExecStart/home/agent/venv/bin/python main.py Restartalways RestartSec5 [Install] WantedBymulti-user.target配置好之后执行sudo systemctl enable myagentAgent 服务就能够在后台持续运行。第三步是到域名服务商解析一个二级域名指向服务器再把域名信息填到腾讯云的 API 网关配置里这样外部请求就能通过网络访问到 Agent 能力了。这一步对新手来说像天书其实逻辑很简单服务器地址是一串难记的 IP域名就是个门牌号API 网关相当于前台。整个部署链路我整理成了一张表方便大家自查环节作用常见入口易错点云服务器跑 Agent 主程序控制台 / SSH忘记开对应端口对象存储放 Skills 文档和素材存储桶列表权限设为私有导致读取失败域名解析把 IP 映射成好记的域名DNS 解析控制台记录类型选错API 网关暴露 HTTP 接口API 网关控制台后端超时时间设太短系统服务守护 Agent 进程systemd / Docker服务退出后不会自动重启3.5 开放与安全怎么平衡相关热搜词里有“腾讯云如何开放所有端口”这种问题但我必须提醒一句千万别为了图省事把安全组规则设置成允许所有端口对所有来源开放。一旦这么干服务器基本上就是在公网上裸奔扫描器用不了几分钟就能找到你。正确做法是安全组只放行需要的端口比如 Web 服务只放行 80/443SSH 登录只放行你自己的 IP。如果你做的是内部实验还可以用密钥登录代替密码登录。我在腾讯云上一开始图方便用的密码登录结果日志里天天有陌生 IP 尝试暴力破解。后来改成密钥登录 禁用密码登录这类告警基本消失了。做 Agent 服务也是一样对外暴露的能力越多越要管好认证和鉴权。4. Skills 应该怎么写才叫“好”4.1 好 Skill 的五个可观测特征写多了之后我总结出一个好 Skills 应该具备的几个特征。首先是任务边界清晰一份 Skills 只负责一类事情不要又是文档处理又是代码生成混杂在一起模型很容易混乱。其次是触发条件明确模型得有办法判断“现在该不该用这个技能”。第三是步骤可执行不要有含糊建议而是明确的动作。第四是包含验收标准让 Agent 自己检查自己干完没干完。最后是能独立测试随时可以把某个 Skill 单独拎出来验证。我自己在做 code review 时会准备一套 Codex Skills 风格的规则文件里面会把代码里常见的坑一条条列出来。Agent 执行完代码审查就会按照规则逐项比对并输出一份问题清单。实测下来虽然比资深工程师人工审略粗糙但胜在速度快什么问题都逃不过规则扫描适合做第一道关卡。4.2 常见的三种 Skills 分类写法按任务类型来分我个人常把 Skills 分成三类。第一类是“文档型技能”功能是生成文档或内容比如写周报、写专利交底材料、写接口文档写法上最重要的是模板要详细需要给出段落结构和句式示例。第二类是“判断型技能”比如代码审查、合规审查、质量检查这种写法要把标准写成 checklist让 Agent 按清单逐项打钩并输出评判原因。第三类是“任务型技能”需要调用外部工具比如发消息、查数据库、调 API这种写法的关键是工具调用的参数必须描述准确甚至要给样例值。很多教程会把 Skills 写得特别玄。其实落实到根上Skills 就是把你脑子里的做事步骤外置成文档。以前你在公司带新人靠嘴说现在带 Agent 靠文档写。越是熟练的专家越容易忽略自己日常工作里的隐性知识写 Skills 的过程相当于强制把这些隐性知识挖出来变成显性的。4.3 如何高效测试和迭代你的 SkillsSkills 写完不是一劳永逸必须反复打磨。我常用一个笨办法准备大约 10 条覆盖正常场景、边界场景、异常场景的测试用例每次都让 Agent 跑一遍看哪些用例没过。比如我写“内容结构化”这个 Skill 时最开始它对生僻的科技类文本结构判断很差后来我在 examples 里面补了几个真实案例效果立刻改善。另一个重要技巧是让 Agent 在跑完任务后输出“执行日志”记录自己用了哪些 Skills、哪些步骤存在不确定性。这样我可以一目了然看出问题出在哪是因为触发条件没写明白还是因为步骤里有歧义。这里特别推荐一个思路把“写 Skill”本身也做成一个 Skill让它分析现有任务、生成技能初稿再由人来审查。用 AI 辅助写技能本质上就是在做提示词工程但产出物更结构化也更容易复用。5. 一些绕不开的坑和排查思路5.1 Agent 为什么经常不按 Skill 走我早期遇到最头疼的问题是明明写了 Skill 文件Agent 却当它不存在。排查下来大概率是这几类原因触发条件写得模糊模型无法把用户问题关联到技能上上下文太长Skill 内容被模型忽略了多个 Skill 互相冲突模型不知道听谁的。对应解决方案也清晰把触发关键词写完整把同一场景下激活的 Skill 数量控制在 5 个以内按优先级排序并减少无关上下文对模型判断的干扰。需要注意的是有些 Agent 框架只有在特定模式下才会加载本地 Skills比如我用的工具要求先识别用户意图属于某个 Skill 目录再动态注入文件。如果你发现自己写的 Skills 没有生效先不要怀疑模型能力而是查框架的日志看它到底有没有读取、注入对应的SKILL.md。很多问题出在路径配置或文件命名上而不是你写的内容有问题。5.2 性能慢、跑飞了的优化策略Skill 加载后本质上是给模型增加了一部分上下文所以如果你的技能包写得过于冗长每一次调用都会导致 token 消耗激增、响应变慢。我习惯把每份SKILL.md控制在 200 行以内涉及大量规则或模板的拆到引用目录里按需读取。这就好比开会你只需要叫相关的人到场而不是全公司都坐在会议室里听一个不相关的议题。当 Agent 出现输出格式不稳定时最好的办法是做“小步迭代”不要一次性让 Agent 完成一整篇报告而是先让它输出大纲再分段生成详情最后再统一排版。实测下来这种分步处理不仅能降低格式跑偏的概率也更容易定位到底是哪一步出了问题。5.3 部署中常见问题速查表把最近自己在部署过程中常遇到的问题整理成一个速查表碰到类似情况的同学可以直接照做现象可能原因排查与解决外部访问不到 Agent 服务安全组端口未放行或服务未监听检查云控制台安全组规则执行curl 127.0.0.1:端口确认本地服务存活Skills 文件读取报权限错误对象存储私有权限或本地文件属主不符在服务器上用启动用户执行确认读取路径有执行权限Agent 答非所问全局提示词与 Skills 触发条件冲突精简全局提示词让“即时反应”让位给“技能加载”输出格式乱Skill 中缺少输出模板在 Skill 的 examples 中补充一个符合预期的标准输出案例进程莫名其妙退出内存不足或未被守护用 systemd 配置Restartalways另查内存占用情况二级域名访问时证书报错未申请/未成功绑定 HTTPS 证书确认域名解析记录指向服务器公网 IP控制台上传或自动申请证书并完成绑定5.4 打磨一下全局提示词别让它“指挥”模型干杂活全局提示词和 Skills 的关系很多人一开始会搞混。打个比方全局提示词像是公司的企业文化Skills 则是具体的岗位手册。企业文化再强员工要是不知道自己具体负责哪个环节依然办不成事。所以我建议全局提示词里少写具体流程多写角色定位和核心原则把可执行的细节全部下沉到 Skills 里。我在最初写 Agent 时总忍不住在系统提示词里写“你要一步一步严谨思考”结果模型每次输出都很用力地自我证明但任务完成质量并没有提升。后来我把所有任务细节都挪到 Skills 里全局提示词只保留“你是我的全能助理优先根据已加载技能处理任务没匹配到技能时再按通用能力处理”效果反而稳定得多。好的 Agent 结构一定是很干净的大脑只做决策知识都在外部文档里动作全靠工具触达。6. 实践中的一些心得与下一个阶段扩展整个过程试下来最大的感受是Agent 开发的门槛正在快速降低但工程化的思维反而变得更加重要。以前的开发是画流程图现在的开发更接近“写说明书 配工具”。你不需要从零实现复杂的调度逻辑但你必须能想清楚业务流程里的每个环节、每个异常分支该怎么处理。Skills 机制让我能把生活与工作里很多重复的判断“外包”出去这点带来的价值比单纯追求某个大模型版本更新要高得多。沿着这个方向后面我打算继续做两个扩展第一个是把多模态素材管理做成一个 Skill让 Agent 能理解视频深度估计、图像分类等场景的输出第二个是尝试用 Agent 分析项目报告的结构自动补全专利申请中比较繁琐的背景技术与有益效果段落。前端开发 Skills、Claude Code Skills 甚至一些个人兴趣向的 Skills我也已经在本地开始测试效果惊喜。最后分享一个实用小技巧与其追求大而全的 Agent 系统不如先选准一个你每周都在重复、耗时 30 分钟以上的任务把它做成 Skill。当你真正跑通一次“从人工操作到 Agent 自动完成”的流程之后那种成就感会驱动你把更多繁琐事交给它。Agent 养成这件事没有终点今天它只会帮你整资料明天它能协助你写代码后天它可能就成了你离不开的数字同事。
