你有没有过这样的体验让 Agent 帮你整理邮件、列提纲、写文案它表现得像个尽职的助手但当你让它“把上个月的销售数据拉出来按区域排个序生成一页分析摘要再按值班表分发给对应负责人”它就开始一本正经地胡说八道了。不是模型变笨了而是你缺了一层东西技能系统也就是业内常说的 Skill。这一篇是这个系列里我最有话说的主题。因为“让 Agent 从聊天进化到干活”差的从来不是模型参数而是那套把能力显式化、工程化、可复用的中间层。Skill 技能系统就是这套中间层的核心。你在热词里看到的 skill开发指南、skill和agent的区别、agent框架与编排、agent记忆、agent安全几乎所有 Agent 实战关键词最后都会汇到 Skill 这个点上来。这篇文章我会从原理讲到实战从踩坑讲到治理尽量把“让 Agent 真正干活”这件事讲透。无论你是在用 Claude、Cursor、Codex还是自己搭 Agent 框架这套方法论都适用。1. 聊天容易干活难Agent 能力跃迁的最后一公里1.1 你遇到的“看起来会、实际不会”的 Agent先说我自己的经历。早期我调试 Agent 时问它“你知道什么是 Kubernetes 吗”它能对答如流但当我让它“把这台服务器上的 Nginx 日志按状态码归类统计 Top 10 IP输出到指定目录”它先是说了一堆正确的方案然后停在第一步——因为它根本没有执行入口。这类场景你应该不陌生Agent 擅长生成文本却不擅长触发动作。原因在于大模型是语言模型它的世界以 token 为单位而不是以“文件系统”“API 接口”“数据库连接”为单位。你让它“读出这份 Excel”它如果手上没有读取 Excel 的工具就只能靠猜。于是它摆出一副“我会”的姿态给你一段写好的 pandas 代码。代码是对的但活没干。这就是聊天和干活的分界线聊天只需要输出干活需要改变现实世界的某个状态。改变状态需要能力而能力需要被显式地加载、调用、校验。Skill 技能系统就是把这个过程从“模型自由发挥”变成“按图索骥”。1.2 为什么单靠大模型上下文无法解决干活问题有人会想我多给 Agent 一点上下文提示词让它知道自己是运维专家、数据分析师不就能干活了吗还真不行。你可以把大模型的上下文想象成一个博闻强识但手脚绑住的实习生。你把所有操作手册、API 文档都塞进上下文他能看懂但他的手还是没放开。真正放开手的是工具调用能力而工具调用能力需要一个“明确的清单”——你的系统里到底有哪些可执行单元每个单元的输入输出是什么边界在哪里。Skill 就是这份清单的实体化。还有一个现实问题上下文是昂贵的。把所有可能用到的技能解释都塞进去模型推理慢、成本高、还容易互相干扰。更好的做法是平时只给 Agent 一个技能索引按需加载某个 Skill 的完整描述。这就像你手机里的应用商店——你不会把几万个 App 的功能说明都背下来你只需要在要用的时候搜索、安装、打开。1.3 Skill 的本质把能力从“隐含”变成“显式”一句话总结Skill 是把一组工具、指令、逻辑包装成一个可被 Agent 元认知识别、按需加载、可复用、可校验的能力单元。注意这个词元认知。Agent 不是普通程序它需要“知道自己有什么手段可用”。如果你的能力分散在代码深处、函数名里、注释里模型看不到就形同虚设。Skill 系统做的事情就是把能力从代码里“拉出来”写成一个模型能读懂的说明书注册进一个模型能查询的清单再暴露给一个负责决策的调度器。后面我会给一个完整的技能封装示例。在那之前先理解 Skill 系统的四个核心模块定义、注册、调度、执行。2. Skill 技能系统的四大核心模块定义、注册、调度、执行2.1 Skill 描述文档给 Agent 看的说明书任何一个合格的 Skill首先必须有一份“人类可读、模型可解析”的描述文档。目前我在实际项目中采用的规范和主流 Agent 框架的做法基本一致每个 Skill 独立目录目录下必须有 SKILL.md里面写清楚这个技能是干什么的、什么时候用、什么时候不可以用、输入参数有哪些、输出结果长什么样、依赖哪些外部系统。描述文档不要写成论文要写成电梯演讲。模型在决策时只会扫几眼所以最关键的信息必须前置技能的适用范围、触发条件、典型用例。比如“销售周报汇总技能用于读取销售明细按区域汇总生成 Markdown 周报。不适合处理退款异常”。这就是一个合格的介绍段。你以为这是写给人看的不这是写给模型看的。写得越清晰模型在意图识别阶段就越少出现“该调用却不调用”或“不该调用却瞎调用”的误判。2.2 注册中心与索引机制有了 Skill 描述下一步是注册。注册不是把文件放进某个文件夹那么简单而是要把它登记在你的 Agent 框架的技能索引中——一个机器可读的清单。这个清单至少包含技能 ID、技能名称、描述摘要、参数 Schema、入口文件、权限等级、依赖项。为什么需要技能索引因为 Agent 在每轮任务开始时不太可能逐个读完全部技能文档。更高效的做法是先扫描技能的索引列表每个技能一句话摘要让模型初筛出候选技能再按需加载候选技能的完整 SKILL.md。我们团队内部管这个过程叫“二级检索”索引级筛选、描述级确认。没有这层设计技能一多Agent 的选择时间会指数增长还会出现“明明有合适的技能却视而不见”的情况。2.3 调度决策Agent 如何知道该用哪个 Skill调度是 Skill 系统里最“智能”也最容易被误解的环节。很多人以为调度需要写复杂规则引擎实际上大部分 Agent 框架的调度就是一个“带工具选择的模型推理过程”。具体说系统把当前任务、可选 Skill 摘要注入给模型模型基于任务推断输出一个结构化结果选哪个 Skill、填什么参数。这一步天然是模糊的所以最好给模型设置约束参数必须符合 Schema、禁止选择权限之外的技能、不确定时询问用户。我强烈建议在调度层加入一个“候选集收敛”的预处理先用关键词匹配或小型分类器把几十上百个技能收敛到 3-5 个候选再让模型做精排。这样既保留了大模型的语义理解能力又把决策成本控制在一个合理范围内。实测下来收敛后调度准确率能提升 20 到 30 个百分点。2.4 执行沙箱与反馈闭环最后一个模块是执行。执行不是简单地跑一段脚本而是要解决两个问题权限边界和反馈闭环。执行沙箱决定了 Skill 能碰什么、不能碰什么。比如一个“发邮件技能”它需要访问 SMTP 服务、通信录接口但绝不应该有权限读取本地任意文件。所以每个 Skill 在注册时就要声明权限等级底层运行时根据等级分配容器、目录、网络策略。这不是多余的安全洁癖而是在真实业务环境中活下来的基本保障。反馈闭环则是让 Agent 知道“活干得怎么样了”。Skill 执行结束后需要返回结构化结果退出码、执行日志、生成物路径、关键指标摘要。Agent 拿这些信息判断任务是否完成要不要根据结果进行下一轮操作如果结果异常是重试、换 Skill 还是求助没有反馈闭环的 Skill 系统是断臂的执行完就完Agent 依然是个盲人。3. 手写一个实战 Skill从需求到封装的全过程3.1 需求界定一个销售周报汇总 Skill 的边界光讲概念容易飘下面我带大家手写一个真实的 Skill。假设场景是每周五下午运营负责人需要一份销售周报包含各区域销售额、订单量、环比变化、TOP 3 客户以及一句自动化结论。第一件事不是写代码而是界定边界。边界就是“什么归这个 Skill 管什么不归它管”。我定的边界是只负责读取固定目录下的销售明细文件完成聚合统计生成 Markdown 报告不负责发送邮件、不负责处理退款、不负责预测下周销量。边界明确后模型才不会越界发挥。3.2 技能脚本与参数定义接下来是技能主体。脚本我一般分成三层入口层、业务逻辑层、异常处理层。入口层负责参数校验业务逻辑层做数据读取和聚合异常处理层负责文件缺失、格式错误、空数据集等场景。参数 Schema 也在这里定义用 JSON Schema 格式。以周报为例参数包括数据目录路径、起始日期、截止日期、区域列表、输出路径。Schema 要写上类型、必填、默认值和说明。这既是给模型看的也是给运行时做校验用的。下面给出一个极简版的脚本结构Python 表示# skill_weekly_sales_report/main.py import argparse import json def generate_report(data_path, start_date, end_date, regions, output_path): # 核心逻辑读取数据、按区域聚合、计算环比、生成 Markdown # 这里按项目实际数据格式扩展 return {status: success, report_path: output_path, summary: {...}} def main(): parser argparse.ArgumentParser() parser.add_argument(--data-path, requiredTrue) parser.add_argument(--start-date, requiredTrue) parser.add_argument(--end-date, requiredTrue) parser.add_argument(--regions, nargs, default[]) parser.add_argument(--output-path, default./report.md) args parser.parse_args() try: result generate_report(...) json.dump(result, sys.stdout) except Exception as e: # 返回可解析的错误信息供 Agent 决策重试 sys.stderr.write(str(e)) sys.exit(1) if __name__ __main__: main()注意返回值不要用中文描述性的“成功”“失败”这种模糊字符串而是用结构化 JSONstatus、report_path、summary。Agent 拿这个结果才能做后续判断。3.3 注册接入主流 Agent 框架的技能清单写完了脚本接下来是注册。目前主流 Agent 框架的 Skill 注册方式大致相同在技能目录下创建 SKILL.md然后把目录挂载到框架的 skills 根目录。下面是我项目中周报技能 SKILL.md 的缩略版--- name: weekly_sales_report description: 生成销售周报用于按区域汇总销售额与订单量并输出结论摘要 trigger: 用户提到周报、销售汇总、区域业绩分析 params: data_path: type: string required: true description: 销售明细 CSV 目录 start_date: type: string required: true description: 开始日期YYYY-MM-DD ... permission: read_data, write_report output: Markdown 报告文件 JSON 执行摘要 --- 基于指定日期范围和区域列表读取 data_path 下的销售明细文件按区域汇总销售额、订单量、环比变化生成 Markdown 报告输出 TOP3 客户名单和自动化结论摘要。若数据缺失直接返回错误码。这里的前置元数据YAML 格式是关键。name、description、trigger、params、permission每一项都会影响调度决策质量。尤其是 trigger给模型一个“什么时候该想到我”的信号。主流框架大多提供了自动扫描 skills 目录的加载器按约定格式读取 SKILL.md生成技能索引。你的责任是让每个 Skill 的元数据写得足够清晰。3.4 联调验证让 Agent 按预期调用注册完成后最后是联调验证。我有一个固定的验证清单直接命令行调用脚本传合法参数确认输出正常。传非法的参数日期格式错、目录不存在确认错误能被结构化返回。在 Agent 对话场景里给出触发语句确认模型选择了这个 Skill。给一个模糊请求如“帮我看看这周卖得怎么样”确认模型能正确推断参数并回填默认值。给一个越权请求如“顺便把周报发给李总”确认模型没有越权而是明确指出“发送邮件不在本技能范围内”。前四项验证的是能力第五项验证的是边界感知。很多 Skill 翻车不是因为不会干活而是因为边界模糊才导致 Agent 干完活后随手瞎承诺。这个联调过程看起来简单实际上是最耗时间的环节。Agent 的调用行为有随机性同一个请求多测几次你会发现有时候它选错了技能有时候参数填得不对有时候忽略了返回结果。这些都要在联调阶段暴露并修正而不是等上线后让用户替你发现。4. 决定 Skill 成败的四个隐藏接口4.1 工具调用协议Skill 与 Agent 怎么对话第一个隐藏接口是协议。你封装出来的 Skill本质上是一个可被 Agent 触发的工具。但它和 Agent 之间怎么交互一套古老的思路是把 Skill 当函数调用Agent 生成参数运行时执行返回结果。这套思路能用但在复杂任务里很局促。真正干活的时候Agent 通常还需要中途确认、分批读取数据、多步迭代。我的建议是Skill 的入口尽量简单但内部可以拆成多个柔性步骤对外暴露“调用-结果-下一步指引”这个铁三角。也就是说每个 Skill 执行完后除了返回任务结果还应该返回“下一步可能动作的提示”。比如周报汇总完成后提示“可以对生成的 Markdown 做二次润色或者直接输出给用户但不包含邮件群发”。这就像给 Agent 递接力棒它知道你这条胳膊到哪为止。4.2 上下文记忆Skill 之间怎么避免“失忆”第二个接口是记忆节点。Agent 调用多个 Skill 完成一个复杂任务时最头疼的问题就是“失忆”——上一个 Skill 的产出到下一个 Skill 那里就没了。比如周报生成之后接着让另一个图表技能画折线图。画图技能不知道周报里算出的区域列表和销售额于是又去重新读一遍数据。这种重复劳动还是小事更大的问题是如果前后数据源不一致结果就对不上。我的解法是在 Agent 框架里维护一个共享的“任务工作单”每个 Skill 执行完成后把关键产出摘要写入该工作单。下一个 Skill 启动前框架自动注入工作单中与它相关的字段。Skill 之间不需要知道彼此的存在它们只需要知道“工作单里有我要的数据”。这比让 Skill 之间直接通信优雅得多。4.3 权限边界Skill 能碰什么不能碰什么第三个接口是权限边界这也是和 agent安全 最直接相关的部分。Skill 一旦上线就不能让它的能力毫无限制。我见过一个很典型的反面案例同事把一个“PDF 转 Word”Skill 挂到了 Agent 上配置时不小心给了它读取整个服务器数据目录的权限。结果 Agent 在处理用户请求时转头就把一份无关的合同内容读进了上下文。虽然不是大规模泄漏但这个行为本身已经触犯了数据合规底线。权限治理不能指望 Agent 自觉必须在运行时强制。具体方案每个 Skill 声明需要的最小权限框架在沙箱层做拦截任何越权调用直接拒绝并记录日志。注意权限审计日志一定要留存一旦出问题你能知道是哪一次任务、哪个 Skill、访问了什么。没有日志的权限系统等于没有权限系统。4.4 自我纠错处理执行失败与重试机制第四个接口是纠错。Agent 干活不可能一帆风顺文件找不到API 超时参数理解错。关键是失败发生后怎么办。有一个反人性的配置我特别提醒不要给 Agent 无上限的重试权。一旦某个 Skill 执行失败超过两次就该把控制权交还给用户解释发生了什么而不是永远循环“重试—失败—再重试”既浪费 token 又制造幻觉。重试策略也有讲究。不是简单的“再跑一遍”而是要让 Agent 读上次的报错原因调整参数后再跑。比如“文件不存在”和“文件格式错误”是两类完全不同的失败前者需要检查路径后者需要检查解析逻辑。所以 Skill 的异常信息一定要结构化、精确至少要让模型看到错误后知道下一步该改什么。5. 实测踩坑实录我在集成 Skill 时遇到的五个典型问题5.1 问题一Agent 反复调用同一个 Skill结果却不一样这是我调试时最先遇到的问题。同一个周报任务调了三次三次的产出在细节上竟然有差异第一次结论里写了“华东区增长”第二次却写“华东区持平”。数据没变为什么会变排查了半天发现根因在调度层的 prompt框架把整个对话历史都赋予了调度模型。前两轮产生的中间推理内容污染了第三轮的判断模型基于自己的上一条错误结论做了新结论而不是基于真实数据。解决方式是把“调度决策”和“任务执行”两种上下文隔离。调度模型只看到任务目标、技能索引、参数校验规则看不到闲聊历史。这个改动立竿见影结果稳定了很多。5.2 问题二多个 Skill 并行时互相污染有一次我把“周报汇总”和“趋势预测”并行跑结果两个报告里的数字对不上。细查之下发现两个 Skill 各读各的 CSV 文件但其中一个读到了带缓存标记的历史文件另一个读的是最新导出的数据。数据源不同结论自然打架。这个问题的根子不在 Skill 本身而在任务规划层。Agent 做并行调度时没有检查多个 Skill 对同一数据源的一致性要求。我的处理方式是在 Skill 描述里增加一个“数据版本约定”字段。凡涉及数据读取的 Skill都要声明它依赖的数据快照 ID同一任务里并行调度的 Skill必须保证快照 ID 一致。从根上堵住数据源漂移。5.3 问题三技能脚本卡死任务没有任何产出还有一次Agent 调用一个外部系统接口的 Skill等了整整六分钟任务超时什么日志都没留下。后来排查发现外部接口因为鉴权过期服务端一直返回 302 重定向客户端循环重定向直到超时。这个坑的关键在于你的 Skill 脚本里没有超时控制和重定向兜底。现在我的所有 Skill 脚本都有一个硬性约定——所有外部 HTTP 调用必须设置显式超时默认 15 秒所有网络库必须关闭自动跳转或者限制最大跳转次数。一次请求失败快速失败快速反馈而不是傻等。5.4 问题四Skill 与模型内建能力重叠时该信谁很多 Agent 框架本身就有一些内建能力比如生成文本、简单计算、查天气。当你把“天气查询 Skill”挂上去后会发现模型有时候调用 Skill有时候自己编一个天气出来。模型更喜欢用内建能力回答因为它“快、不依赖工具”但正确性没有保障。这里必须配置优先级规则凡是注册了对应 Skill 的领域一律强制走 Skill模型被禁止直接用“猜测”来回应事实型请求。实现方式很简单在系统级指令里加硬性约束“当存在天气查询 Skill 且用户意图属于该领域时必须调用该 Skill不得自行编造天气信息”。同时调度器在判定时如果技能索引中存在高相关的候选就把它作为第一选项推荐给模型。这算是一个轻量的策略控制手段。5.5 问题五恶意输入与参数注入最后说说安全。Skill 接收的参数是用户自然语言里抽取的它天然可能携带恶意内容。比如“指定输出路径”这个参数用户可以说“./reports/周报.md”也可以说“rm -rf /”。如果脚本没有做安全过滤这一句就能让整个技能脚本报废。我的防御策略有两层第一层是参数 Schema 规范第二层是运行时命令黑名单。凡是路径参数一律限制在预先声明的白名单目录内凡是命令执行类 Skill一律拒绝拼接 shell 字符串改用 subprocess 的参数数组传参。你已经配置了沙箱但这只是底线脚本内部也要把自己管紧一点。Agent 生态的安全从来都不是单点防御而是多层防线。6. 从个人脚本到团队技能库Skill 生态的进阶之路6.1 盘点主流的选择Claude Skill、Cursor Skill、Codex Skill 与自主框架聊到这里你一定好奇市面上的 Skill 实践具体长什么样。目前经常被提到的几个方向Claude 的 Agent Skills 采用 SKILL.md 描述 资源文件加载Cursor 的 skill 更侧重编辑器内操作自动化Codex 技能偏向编码任务的分解执行还有大量开源 Agent 框架自带的技能注册机制。做一个中肯对比方便你选型方向核心思路适合场景注意点Claude Skills目录化、SKILL.md 描述、按需加载通用知识型技能、文档生成、代码片段描述质量决定调用准确率Cursor Skills与编辑器深度绑定编码、重构、代码库问答迁移性一般依赖编辑器生态Codex Skills面向编码任务拆解自动编程、代码库维护更偏开发场景非通用自主框架自己定义注册/调度/沙箱生产系统定制化初期开发成本较高但可控性最强我的建议是如果你还在学习和验证阶段优先用 Claude Skills 或类似通用方案因为文档规范成熟、社区资料多。如果已经进入生产环境且需要对接内部系统一定要在自主框架上做二次封装因为你需要权限审计、数据隔离和流程审批这些生产级能力。6.2 把 Skill 变成可分享、可治理的资产独立的 Skill 很容易写难的是把它变成一份可持续治理的资产。这不只是技术问题还是协作问题。我见过不少团队的技能库整理得比烂代码库还可怕几十个 Skill 目录堆在一起描述写得不清楚没有版本号没有负责人连接口变化了都找不到是谁改的。建议团队内部推行三个约定每个 Skill 必须有 owner、每个 Skill 必须标注版本号、每次改动必须写变更记录。把这些约定固化到 Skill 模板里而不是依赖个人自觉。至于对外分享核心是把 SKILL.md 写得足够独立。技能不要依赖某个目录的绝对路径所有依赖文件都放在 Skill 目录内这样任何一个新环境只要导入目录就能用。这也是从个人脚本迈向成熟技能库的关键一步技能自身要自洽、可移植。6.3 学习路径建议从 Prompt 到 Skill 再回到业务如果你是新手我的学习路径建议分三步走。第一步别再只写 Prompt 了刻意练习写 SKILL.md逼自己把一个需求梳理成结构化的技能文档。第二步拿一个真实的小任务比如周报生成、PDF 批量改名独立完成整个 Skill 的封装、注册和联调跑通“定义—注册—调度—执行”闭环。第三步对已有的技能做治理加上版本、权限、日志然后观察 Agent 在复杂任务里的表现你会看到明显的稳定性提升。这个路径的本质是把注意力从“模型会不会”转移到“系统能不能”。你越早意识到 Agent 能力的上限很大程度上由它的工具箱决定就越能理解 Skill 系统在整个智能体生态里的位置。我也建议你持续关注 skill 开发指南类的内容和社区讨论。这个领域变化极快每个主流框架的 Skill 规范都在快速演进但核心思想是稳定的显式化、模块化、可治理。抓住这三点你就不会在未来半年的框架大战里迷失。到了一篇文章写完的时候我通常没有那种“终于讲完”的轻松感反而觉得留下了很多没讲透的细节。最后一次给个小建议当你自己的 Agent 开始稳定地完成一周的重复任务时记得录一段视频留档。那是最好的复盘材料。我个人是在调试了无数个翻车现场之后才真正理解 Skill 系统的价值。它不是什么高深技术就是把“能力”这件事变得可描述、可注册、可调度、可治理。你的 Agent 能不能从聊天进化到干活不取决于它多聪明而取决于你给它配了多少能干事、守规矩、会汇报的 Skill。