Skill技能系统：让AI Agent从聊天进化到干活

Skill 技能系统 — 让 Agent 从"聊天"进化到"干活"

这两年我一直在折腾各类 AI Agent，从最早的 prompt 拼接，到后来用各种框架搭自动化工作流，最深的感受就是：Agent 和聊天机器人的本质区别，不在于"会不会说话"，而在于"能不能把手上的事办完"。如果你只是让模型陪你聊人生聊理想，那用普通对话完全够；可一旦你想让它在真实环境里查资料、改文件、跑脚本、调接口，就必须给它一套"干活"的体系，否则它永远只会给你一段看起来正确、实际上没法落地的话。

这套体系，在目前主流的 Agent 框架里有个核心载体，叫Skill（技能）。Claude 生态里叫 skill，Codex 里也有类似概念，Cursor、Workbuddy、Harness 这类工具也都在围绕 Skill 做文章。你可以把 Skill 理解为 Agent 的"手"——模型负责思考怎么干，Skill 负责真正把动作执行出去。没有 Skill 的 Agent 像只读说明书的人，有了 Skill 它才变成会操作机器的操作员。这篇文章，我就从自己的实践角度，聊聊 Skill 技能系统到底是怎么设计的，怎么把一个"聊天式 Agent"改造成"能干活的工作流"。

需要说明的是，这不是某个框架的官方文档，而是我在反复试错中总结的通用套路。无论你用的是 Claude Code、Codex、自研 Harness，还是开源的 Agent 项目，下面这套思路都能直接用。当然，不同平台的 Skill 实现细节有差异，但底层逻辑是一致的。咱们先搞清楚为什么需要它，再一步步看怎么落地。

1. 为什么 Agent 需要 Skill 技能系统

1.1 从"对话"到"干活"的三道坎

想让 Agent 真正干活，你会发现它要跨过三道坎：第一是确定执行目标，聊天时你说"帮我写个域名解析脚本"，它可能直接给出代码；干活时你必须让它确认是生成代码、保存到文件、还是运行一遍并返回结果。第二是稳定调用工具，聊天时模型只要在回复里写几段代码就行，干活时它需要真正调用文件读写、命令行、HTTP 请求这些外部能力。第三是处理异常和反馈，聊天时你顺着话聊就行，干活时脚本崩了、接口变了、权限不够，它都得察觉到并调整策略。

我最初做 Agent 的时候，走的是"把所有工具塞进 system prompt"的野路子。做两个工具还行，等工具到十个以上，模型就开始"选择困难"——它经常分不清该用哪个、用了之后怎么衔接下一步。而且 prompt 越长，模型越容易忽略边缘功能，结果核心工具反而经常不被触发。Skill 系统的意义，就是把"工具+调用逻辑+使用说明"打包成一个独立单元，让 Agent 按需加载，而不是一次性背下所有说明书。

这就像让一个新员工干活，你不能把全公司的制度手册揉成一团丢给他。你得给每个岗位配上独立的操作手册和工具包——要做数据清洗，就去拿清洗工具包；要做报表，就去拿报表模板。Skill 就是这一个个"岗位工具包"。

1.2 Skill 和普通提示词的区别

很多朋友问：Skill 不就是一段特殊 prompt 吗？我的回答是：Skill 是一个自带执行逻辑和验证闭环的"可运行模块"，而普通提示词只是一段话。举个例子，你写一段提示词"帮我读取 CSV 并统计每列缺失值"，模型可能给你一段 Python 代码，但也可能直接给你文字建议，甚至告诉你"可以用 pandas 干这事"。就算它给了代码，你还要自己复制、保存、运行、看结果。而一个训练有素的数据清洗 Skill，会自己完成：找到文件、写脚本、运行、读取输出、校验结果、给出结论，甚至失败后自动换一种方式重试。

实际上，Skill 更接近传统软件开发中的"函数"或"插件"。它有清晰的输入接口、执行步骤、输出标准。在设计上，Skill 关注的不是"说什么"，而是"做什么"。没有 Skill 的 Agent 是"口嗨型"的，说什么都头头是道，一做正事就掉链子；有 Skill 的 Agent 至少能把事做出来，就算做得不完美，也会给你一个可修正的中间结果。

另外，Skill 也为不同场景提供了隔离性。你可以在同一个 Agent 里同时挂载"数据处理"和"自然语言转 SQL"两个技能，它们各自维护自己的上下文、文件和依赖，互不干扰。这比把几十个功能混在一个 Prompt 里强太多——至少改一个功能不用重写整个 Prompt，也不会因为新增技能导致旧技能失效。

2. Skill 技能系统的核心组成

2.1 触发与匹配：Agent 怎么知道该用哪个 Skill

在大部分框架里，Agent 不会每时每刻都在调用所有 Skill，它要先判断"当前该用哪个"。这里的核心机制是基于 Skill 的描述和与当前任务的语义匹配。每个 Skill 都应该有一个简洁但信息充分的说明字段，它像函数签名一样告诉 Agent：这个技能是干什么的、适合什么场景、需要什么前置条件。

我踩过的坑是：描述写得太口语化，模型匹配不到。比如你写"处理一下数据"，模型可能不知道是该用"数据清洗"还是"数据可视化"。后来我改成"当用户需要加载CSV/Excel并统计缺失值、重复值、基本分布时使用，可输出字段报告和图表"。这样训练后，命中率立刻上来了。所以描述的重点不是文艺，而是让模型能在任务描述和技能描述之间建立明确映射。

还有的框架采用"关键词触发"或"路由模型"机制，比如定义好 trigger phrase，命中关键词就强制走某个 Skill。这种方式适合意图特别清晰的任务，比如"抓取网页"可以直接触发爬虫 Skill。但如果任务有歧义，靠关键词容易误伤。我一般用的是"语义相似度优先，关键词兜底"的混合策略——先让 Agent 自行判断，如果匹配置信度低就再看有没有关键词命中。另外，Skill 的加载顺序也会影响匹配效率，高频技能靠前放，低级错误能少很多。

2.2 执行流程：从"决策"到"动作"的状态机

一个成熟的 Skill 不应该只是"调用一个 API 然后返回结果"，因为真实世界的任务往往是多步骤的。比如你要做一个"网页摘要"技能，执行流程是：抓取网页 -> 清洗HTML -> 截取正文 -> 调用模型概括 -> 整理输出。如果这个流程没有状态管理，一旦中间某一步崩溃，Agent 不知道从哪继续，只能从头跑一遍——这既浪费 token，又容易引入新错误。

所以好的 Skill 系统会内置一个轻量级状态机。状态包括：pending（待执行）、running（执行中）、waiting_input（等待补充信息）、succeeded（成功）、failed（失败）。Agent 每次执行 Skill 时，会把当前状态和执行进度记录下来，失败时可以从断点重试。我在自研 Harness 的时候只做了最简单的"步骤标记"，状态存在 JSON 文件里，效果已经很显著：重试成本降了一半左右。

另外，执行过程中的日志也很重要。Agent 为什么失败？是代码语法错误、网络超时、还是模型输出格式不对？每步日志都要保留。这不仅是排查的依据，也是后续优化 Skill 的一手资料。我见过不少团队只关心最终结果，日志全丢，最后问题出现了只能干瞪眼。所以设计 Skill 时，记得为每一步写清楚输入、输出、耗时、错误信息。

2.3 输入输出契约：让 Skill 变成可复用的"函数"

写过程序的都懂接口契约的重要性。Skill 也是一样，它应该有明确的输入参数和输出格式。比如一个"发邮件"技能，输入应该是收件人、主题、正文、附件路径；输出应该是发送成功与否、邮件 ID 或错误信息。如果你的 Skill 输入是模糊的"给张三发一封介绍我们产品的邮件"，那就没法稳定复用了——模型每次都要猜，猜错了整条链路就断了。

我的经验是把输入参数分成必填项和可选项，在 Skill 描述里明确标注。比如爬虫技能，必填是 URL，选填是最大抓取深度、延迟、请求头。这样模型在调用时就会知道哪些信息需要向用户确认，哪些可以从上下文里推断。有时候用户没说 URL，Agent 就得反问；这比它自作主张抓一个错误的网页要靠谱。

输出格式也要固定。我一般都用 JSON 结构返回，因为后续 Skill 或 Agent 主流程能直接用 key 取值，避免解析自然语言的不可靠性。例如统计类技能统一输出{ "total": 100, "missing": 5, "columns": ["a","b"] }，主流程拿到就能渲染成报告或继续做下一步。这不是学院派建议，而是被生产环境毒打后的教训——自然语言输出在跨 Skill 调用时十有八九会翻车。

3. 如何从零编写一个可用的 Skill

3.1 定义功能边界与触发描述

动手写 Skill 的第一个动作不是打开编辑器，而是想清楚它的功能边界。边界太窄，比如"只能统计 CSV 行数"，实用性低；边界太宽，比如"处理所有数据文件"，Agent 使用时反而分类困难。我常用的判断标准是：一个 Skill 应该能在 3 步之内讲清它做什么。"从本地 CSV 加载数据，检查缺失值和重复值，输出一个 JSON 总结"——这就是一个边界清晰的技能。

边界定好后，写触发描述。这里有个技巧：不要用空泛的词，像"数据质量分析"可能不如"数据质量检查/清洗/统计"具体。描述里要带上任务动词 + 数据对象 + 输出物类型。举个例子：当用户要求对本地表格数据（CSV/Excel）进行质量检查、缺失值统计、重复值检测时使用。输入为文件路径，输出为JSON格式的统计数据表。这样的描述，模型在意图识别时命中率极高。

另外，考虑多个触发场景也很重要。同一个技能可以在不同语境下被调用。比如"计算某个周期内销售额"和"对比两周数据差异"用的可能是同一个数据聚合技能。所以描述里可以多列几个同义场景，但注意别写成毫无边际的小说。我会在描述里加一个"similar_tasks"字段，专门放常见触发说法，这招实测很有效。

3.2 编写可执行的任务清单与工具调用逻辑

定义完边界和描述，下面就是写真正的执行逻辑了。有两种主流实现方式：一种是自然语言步骤清单，Agent 自己读着步骤去调用工具；另一种是预编译脚本/函数，Skill 直接绑定一段 Python 或 Node 代码，Agent 只需要传参。我建议根据任务的稳定性来选择：如果任务是高度标准化的，比如"文件格式转换""Web 请求"，直接用代码实现，速度和成功率都更好；如果任务需要模型做上下文判断，比如"从一堆日志里找出可疑行为"，那就用自然语言指导 + 中间工具配合。

自然语言版的执行步骤要写得非常具体，不能让模型自由发挥。例如"清洗公司销售数据"这个 Skill 的步骤可以是：先调用list_files找到目标文件，然后用read_csv读取前 50 行做抽样检查，接着调用run_python执行预先定义好的清洗代码，最后生成报告。每一步都要写明用什么工具、输入什么变量、期望得到什么结果。

而脚本版的 Skill 则要重点关注依赖管理。我在写爬虫 Skill 时，会默认在技能目录里放一个requirements.txt，启动时检查装没装好。有的框架支持隔离环境，比如每个 Skill 用独立 venv，这能避免依赖冲突。对于脚本，我还习惯把所有输出集中到一个output/文件夹，方便后续调试和检查。

3.3 Skill 的测试与迭代：上线前必须做三件事

写完 Skill 不是万事大吉，测试是重中之重。我的流程分三步。第一步是单指令验证，只让 Agent 执行一个 Skill 的简单任务，比如"读取 test.csv 并统计缺失值"，检查每一步的日志和输出。第二步是边界值验证，故意给空文件、超大文件、错误编码文件、带恶意代码的文件，看 Skill 是否优雅报错而不是崩溃。第三步是组合流程验证，让 Agent 连续调用多个 Skill，比如先抓网页再用摘要技能，确认两个 Skill 之间的数据格式能互相兼容。

我把踩过的坑总结成了表格，放在 4.3 节后面，但这里要先强调两个容易忽略的地方。第一是**"幻影成功"**——脚本执行完了但实际没有达到预期，比如爬虫返回 200 却是验证码页面。我的解决办法是在 Skill 里增加校验环节，用正则检查返回内容是否包含目标信息，没有就标记失败。第二是token 耗尽导致半途而废，长任务尤其常见。我的做法是让 Skill 在执行到关键里程碑时，强制把中间结果落盘，这样即使对话超时，也能从落盘文件继续恢复，而不是全部重来。

4. 实战：让 Agent 执行一个典型的"干活"任务

4.1 任务示例：抓取多个网页并生成结构化摘要

我先选一个很有代表性的任务，带大家完整走一遍：**让 Agent 从指定的五个新闻页面抓取正文，去掉导航和广告，每篇生成 200 字摘要，最后汇总成一个 Markdown 表格。**这个任务涉及网络请求、HTML 解析、自然语言生成、文件输出，典型的"全能型小项目"。如果没有 Skill，Agent 大概率会给你一段爬虫代码，然后让你自己跑。如果有了完善的 Skill，它应该能一条龙搞定。

我按第 3 节的套路来设计两个 Skill：web_fetch和html_extract。web_fetch负责下载页面并保存到本地，输入是 URL，输出是文件路径；html_extract负责从本地 HTML 提取正文，输入是文件路径和正文长度需求，输出是纯文本。然后还有一个summarizer技能——这部分会调用模型自身的摘要能力，所以可以做成自然语言步骤，不一定要写死代码。这样三个技能组合在一起，就能完整跑通。

这种拆法的好处是职责单一。web_fetch不需要知道摘要怎么生成，html_extract不关心网页是怎么来的。出了问题时，我能立刻定位到是哪一层出了问题，是网络不通、正文解析失败、还是摘要格式不对。这就是模块化的价值——你不需要从头把所有代码都看一遍。

4.2 实现过程：定义、编码、挂载三步走

第一步，定义web_fetch的 skill 元信息：

name: web_fetch description: 下载指定URL指向的网页内容并存储为本地HTML文件。输入必须提供完整的http/https链接，输出为本地文件绝对路径。适用于需要分析网页内容、提取信息、生成摘要之前的预抓取步骤。 input: url: 必填，字符串 timeout: 选填，默认15秒 output: file_path: 本地HTML文件路径 status_code: HTTP状态码

第二步，编写执行逻辑。我用的框架支持 Python 脚本，所以核心代码如下（这是最小实现，实际生产我还会加随机 User-Agent 和重试机制）：

import requests, sys, uuid url = args["url"] timeout = args.get("timeout", 15) save_dir = os.path.join(os.getcwd(), "output", "pages") os.makedirs(save_dir, exist_ok=True) resp = requests.get(url, timeout=timeout, headers={"User-Agent": "Mozilla/5.0"}) resp.encoding = resp.apparent_encoding file_path = os.path.join(save_dir, f"{uuid.uuid4().hex}.html") with open(file_path, "w", encoding="utf-8") as f: f.write(resp.text) result = { "file_path": file_path, "status_code": resp.status_code, "content_length": len(resp.text) }

注意我把保存路径放在项目目录的output/下，而不是任意目录，这能避免 Agent 把文件写到奇怪的位置。很多框架默认允许 Agent 访问整个文件系统，这是一把双刃剑——一定要给 Skill 限定好读写范围，否则技能越写多越容易出安全事故。

第三步，把 Skill 挂载到 Agent。我通常用 YAML 配置文件统一管理：

skills: - web_fetch - html_extract - summarizer

挂载之后，我会让 Agent 先描述一下自己的技能列表，确认它能正确感知到这些技能的存在。有时候模型会忽略某些技能，这大概率是描述写得不够清楚，或者是技能之间的描述冲突了。

4.3 运行效果复盘：从翻车到稳定

第一次跑的时候果然翻车了。Agent 老实调用了web_fetch，但后面它没有直接接着用html_extract，而是试图自己用 Python 代码去解析网页，结果因为编码问题报错了。我分析了日志，发现原因是html_extract的描述里没有明确指出"该技能应该与 web_fetch 的输出路径配合使用"。于是我在描述里加上一句"输入字段 file_path 通常由 web_fetch 技能生成，可直接传入"。改完再跑，链路通了，三个技能按顺序执行完，最终输出了 Markdown 表格。

这个教训很有代表性：Skill 的描述不仅影响意图匹配，还影响技能之间的衔接。你写的每个技能都像文档里的一张参数表，后续技能要能识别前序技能输出的字段名。如果你在web_fetch里把输出字段叫file_path，在html_extract里输入也叫file_path，那么 Agent 就能很自然地串起来。如果你起了一堆不同名字，它就要做额外的对齐判断，模型毕竟不是程序，判断一多就出错。

最终运行效果让我满意的是：整个过程 Agent 都没有让我动手复制代码或改路径，它自己发现了页面里有一段 HTML 是乱码，于是重新调用了一次html_extract，指定了 UTF-8 编码去解析。这种自主迭代修复的能力，正是 Skill 系统带来的核心价值——它给了 Agent 一个"执行-检查-纠错"的闭环。

5. 常见问题与避坑指南

5.1 Skill 不生效：百分之八十是描述问题

很多朋友跟我反映，Skill 明明挂载了，但 Agent 就是不用。我一般让他们先自查三件事：描述里有没有说清楚"输入是什么、输出是什么、什么时候用"；有没有跟其他技能撞车；还有技能描述是否和用户问题的措辞差异太大。如果这些都调整了还是不行，就在调试模式里看看 Agent 实际拿到了哪些 Skill 的元信息，有时候是框架因上下文长度被截断，把后面的技能裁掉了。

这里有一个我常用的技巧：在触发描述里加上负面示例，比如"当用户仅咨询新闻内容而不需要保存网页时，不要使用web_fetch"。这能显著降低误调用率。模型对"不要做什么"的理解往往比对"要做什么"更直接。

5.2 多技能协作时怎么避免串台

当 Agent 有多个 Skill 时，另外一个高频问题是"串台"——调用了技能 A，却传了技能 B 的参数。我在 2.2 节提到过输入输出契约，这里再补充一招：让技能的输出字段带上技能名前缀。比如web_fetch输出web_fetch.file_path，html_extract输入html_extract.file_path。虽然字段多了字，但模型不容易弄混。我见过生产环境中因为字段名都是result导致全流程崩溃的案例，加前缀后基本绝迹。

另外，如果一个 Agent 同时需要依赖顺序执行多个 Skill，可以写一个编排脚本（或者叫 pipeline），而不是直接让模型自由发挥。编排脚本里明确指定先调哪个、再调哪个、如何传递参数，模型只在脚本无法覆盖的异常分支里介入。这种"能自动化就自动化"的思路，让整个系统的稳定性提高了一个量级。

5.3 安全与权限：别让 Skill 变成脱缰野马

Skill 系统给了 Agent 很大的能力，也意味着更大的风险。我强烈建议给每种 Skill 配置最小权限。例如web_fetch只需要网络访问和写入指定 output 目录的权限，那就不要让它有直接删除文件的权限；直接执行 shell 命令的技能，更要严格控制输入参数，防止注入。我在脚本里还会做一层校验，比如 URL 必须以 http/https 开头、文件路径必须在 allowed 目录下。这不是过度设计，而是被现实教过的——模型会出于"善意"执行一些危险操作，比如尝试删除临时文件，结果删错了地方。

在安全这块，我给自己定了几条规矩：第一，所有 Skill 可执行的命令必须列入白名单；第二，任何外部输入都要校验再拼接；第三，输出数据如果不涉及必要隐私，尽可能脱敏。对于企业级项目，建议再加一层人工审批机制，高危操作必须人确认后 Skill 才会继续。千万别觉得这些麻烦，Agent 越能干，越需要缰绳。

5.4 常见报错速查表

为了节省大家排查时间，我把这两年处理过的问题整理成了表格。

表格里的每一行我都实际碰到过。尤其是"执行成功但结果不符预期"，这是最隐蔽的坑。比如爬虫返回了 200，但页面其实被重定向到了登录页；统计代码跑完没有报错，但读的文件是旧版本。所以无论用什么框架，Skill 内部一定要有结果自检，不要信任"没报错"就等于"做对了"。

5.5 关于 Skill 生态的个人体会

最近一段时间，Claude、Codex、Cursor 都在大力推广自己的 Skill 生态，很多做 Agent 工具的团队也都在往这个方向靠。我觉得 Skill 更像是 Agent 时代的"插件协议"，谁能让用户以最小的成本把想法变成可复用的技能，谁就能在生态里占据位置。对开发者来说，现在掌握 Skill 的设计方法，就等于提前拿到了下一批生产力工具的钥匙。

但也要提醒一句：Skill 不是越多越好。技能多了，模型匹配的负担会加重，误用率提高。我个人的经验是，一个垂直领域的 Agent 挂载 5 到 10 个精心打磨的 Skill 就够了，超过 15 个就要考虑分层。比如把通用工具和领域工具分开，或者按照任务流程建立不同层级的 Skill 目录。保持技能库的"小而精"，远比"大而全"重要。

最后分享一个我今天还在用的小技巧：给 Skill 写文档的时候，把"用一段话介绍这个技能是干什么的"这一项，让 AI 反向生成三个不同详略程度的版本——一个极简版（用于 Agent 快速匹配）、一个标准版（用于人阅读）、一个详细版（用于多技能协作时的参考）。你在为 Agent 写技能，也是在为未来的自己留操作手册。这一点点额外的投入，可以省下后面无数次调试的工夫。