Agent Skills 是 2025 年以来 Agent 工程里最值得关注的一层抽象。它解决的问题很具体Agent 不是提示词堆砌出来的“万能答题机”复杂能力应该被拆成可复用、可测试、可单独调用的技能模块。很多同学已经知道 Agent 能规划、能调工具但真正动手写的时候提示词越来越长、工具调用不稳定、加一个新能力就要重构整个流程。这种场景下直接用 Skills 思路重新组织项目往往是效率提升最明显的一步。这篇文章不是把概念再讲一遍而是给一条能落地的路径先理清 Skills 与 Agent 的关系再给一套最小环境配置和 Skill 编写模板然后用代码审查、文档解析、自动化测试三个实战例子说明单 Agent Skills 怎么跑通最后落到多 Agent 协作、接口调用、批量任务和性能观察。整条路径按 5 小时左右来安排第一小时学概念后面四个小时都在写和调。适合阅读本文的读者有三类已经对 Agent 有概念但没写过完整项目的开发者写过简单单 Agent 但被 prompt 混乱和工具调用不稳定困扰的人以及准备在公司内部搭建 Agent 自动化流程、需要对技能做模块化复用的工程师。如果你只是随手搜一下“Agent 是什么”建议先补基础概念再回来看。1. Agent Skills 核心能力速览这里不卖关子先把 Agent Skills 的关键信息整理成一张表。很多参数取决于你选的框架和底层模型表格里能确定的写确定不能确定的会标注清楚。能力项说明概念定位将 Agent 的复杂能力拆分为可复用、可独立测试的技能模块核心价值降低 prompt 复杂度让规划与执行分离便于组合和复用常见实现形式技能描述文件 可执行代码/脚本 输入输出约束典型载体Claude Skills、OpenAI 工具定义、自建 skill 目录、LangGraph 节点开发语言Python 为主也可用 TypeScript / Go业务依赖需要 LLM 的 API 或本地推理服务是否支持 API 集成支持一般会把 Agent 封装为 HTTP 服务是否支持批量任务支持需要在任务调度层做队列和重试多 Agent 协作支持常见模式有 Supervisor 编排、对等协作硬件门槛纯 API 方案无显存压力本地推理方案需按模型规格评估适合人群有 Python 基础、想搭建可维护 Agent 项目的开发者从这张表可以看出一条主线Agent Skills 不是一个具体的模型或软件而是一种工程组织方式。同样一个“代码审查”功能可以做成 prompt 里的几行要求也可以做成一个独立的 skill包含功能描述、输入格式、执行逻辑、测试用例。后者的可维护性和可复用性会好很多这也是吴恩达团队在多次分享中强调的 Agent 能力沉淀方式。2. Skills 与 Agent 的区别很多人的第一个疑问就是Agent 和 Skill 到底什么关系这里用一个简单的类比来理解。Agent 是决策者它负责理解任务、拆解步骤、决定调用什么工具、判断结果是继续还是结束。Skill 是执行单元它封装一组明确的能力比如“审查一段 Python 代码并输出缺陷清单”“解析一份 PDF 并转成 Markdown”“在测试环境执行一条接口用例并汇总断言结果”。Agent 在合适的情况下从技能列表里选中对应 skill把参数传进去拿回结果继续下一轮决策。两者的边界可以从三个维度看维度AgentSkill职责规划、决策、调用、总结执行具体子任务可测试性端到端测试复杂可以单独写单测复用范围通常一个项目一套可在多个 Agent 任务间复用变更成本改动影响全局改动局部接口不变影响小为什么要用 Skills 而不是把所有规则都写进 Agent 的系统提示词实际开发中 prompt 一旦超过几百行问题会很快暴露模型开始忽略后面的规则、新需求改了前面某段又影响其他行为、迭代时根本不知道该动哪里。Skills 把这块拆开Agent 的系统提示词只需要维护一份简短的技能清单和调用策略每个 skill 的行为由自己的描述文件和执行代码约束。这样既减少了上下文长度也让技能本身的正确性可以通过单测保证。另一个容易混淆的点是 Skill 和 Tool 的区别。很多 Agent 框架里 Tool 是单次函数调用Skill 可以是多个步骤的组合甚至可以包含自己的提示词模板、参数校验和结果后处理。从工程角度看Skill 更像“一个有内部逻辑的微服务”Tool 更像“一个无状态的函数”。理解这一点你在设计模块边界时就不会把所有东西都塞成最小粒度的函数。3. 适用场景与使用边界先聊清楚“能用在哪”免得学完发现用错方向。Agent Skills 适合的场景包括代码生成与代码审查。把审查规则做成 skillAgent 拿到一段代码后调用返回结构化问题清单可以在 CI 里批量跑。文档处理与信息抽取。解析 PDF、Word、网页内容输出 Markdown 或 JSON适合做知识库预处理。数据分析。把“读取 CSV、做统计、生成图表”封装成数据分析 skillAgent 负责解读问题skill 负责算。自动化测试。根据接口文档生成测试用例并执行可以配合测试框架做成批量任务。客服问答与知识库检索。检索逻辑放在 skill 里Agent 只负责理解用户意图和整理回答。不适合或无把握的场景对实时性要求极高、延迟超过预期就不能用的场景Agent 多轮推理会明显放大耗时。输出必须零错误的场景。Agent 和 LLM 天然存在幻觉需要增加校验 skill 或人工复核环节。没有明确接口边界、输入输出变化极大的场景。Skill 设计越具体越好通用能力反而难维护。涉密、敏感数据场景。如果底层调用云端 LLM数据进出链路需要先做合规评估必要时用本地模型。合规边界在 Agent 项目里不是套话。涉及用户隐私、商业数据、人脸声音版权素材时必须确认数据授权使用开源模型要遵守模型许可证把 Agent 封装为对外服务时要控制访问范围和请求频率对外提供基于 Agent 生成的内容时要标注来源并做内容审核。这些边界不是代码问题但忽略它们的代价往往比 bug 还大。4. 5 小时学习路径规划标题写了“从安装到多 Agent 协作”这里把它拆成可执行的 5 小时计划。时段学习主题核心产出第 1 小时Agent 与 Skill 概念、框架选型明确要用的框架和模型接口第 2 小时环境准备、最小 skill 编写本地能跑通一个“参数输入 结果返回”的 skill第 3 小时单 Agent 集成多个 skill完成一个带代码审查 skill 的简单 Agent第 4 小时多 Agent 协作实现 Supervisor 把任务分发给两个 worker第 5 小时接口、批量任务、性能观察把 Agent 封装成 HTTP API跑一批任务并记录指标如果你已经有 Python 和基础 API 调用经验时间可能会更短。如果完全没写过 Agent第 1 小时会稍微紧张一点建议重点看概念而不是纠结框架细节。框架选择上API 调用简单的试 OpenAI 风格的 tool/function 机制需要复杂控制流的试 LangGraph 或 AutoGen 这类支持多节点编排的框架偏向微软生态的可以看 Microsoft Agent Framework。选型不是越重越好第一版能用最少的代码跑通最重要。5. 环境准备与前置条件开始写代码前请先确认本机环境。下面是一份通用检查清单具体版本号以你选的框架要求为准不要照抄。检查项操作系统Windows 10/11、macOS、Linux 均可。多 Agent 协作涉及并行进程时Linux 服务器更省心。Python推荐 3.10 及以上部分框架需要 3.11。用python --version确认。Node.js如果走 TypeScript 生态建议 18 以上。Git用来拉取框架源码、skill 模板仓库。LLM 服务准备一个 API key或在本机装好 Ollama 等本地推理工具。API 方案要关注成本和限流本地方案要关注显存和磁盘。依赖管理建议用 venv 或 conda 创建独立虚拟环境避免污染系统 Python。磁盘空间纯 API 方案几百 MB 就够本地 7B~14B 模型需要 10GB 以上更大模型按实际规格评估。网络访问依赖安装和模型下载需要稳定的网络环境。创建虚拟环境的通用命令# 创建并激活虚拟环境具体 Python 版本按本机实际情况调整 python -m venv .agent-skills-env source .agent-skills-env/bin/activate # Windows 下使用 .agent-skills-env\Scripts\activate pip install --upgrade pip依赖安装是新手最容易卡住的地方。建议只装框架要求的依赖不要一次性把网上教程里的包全部装进去。装一个包后先导入测试再装下一个。如果出现依赖冲突优先看项目文档里写的版本范围而不是盲目升级到最新版。6. 最小 Skill 编写与调试一个可维护的 Skill 至少要包含三部分技能描述、执行代码、测试用例。先看技能描述它决定 Agent 什么时候调用这个 skill再看执行代码它决定调用后能不能稳定输出最后是测试用例它决定改动时会不会打破旧行为。一个 skill 的描述文件通常长这样这里以“代码审查”为例{ name: code_reviewer, description: 审查一段 Python 代码并输出问题清单。当用户要求审查代码、检查代码质量或给出改进建议时调用。不适用于代码生成和运行调试。, parameters: { code: { type: string, description: 需要审查的完整代码 }, strict: { type: boolean, description: 是否启用严格模式默认 false } } }对应的执行代码可以先用一个最简单的 Python 类实现# 通用 Skill 实现模板具体基类接口按所选框架调整 class CodeReviewerSkill: def __init__(self): self.name code_reviewer self.description 审查 Python 代码并输出问题清单 def execute(self, code: str, strict: bool False) - dict: issues [] # 示例检查规则实际项目请替换为真实规则或调用 Lint 工具 if TODO in code: issues.append({type: warning, message: 存在未完成的 TODO 标记}) if eval( in code: issues.append({type: error, message: 不应在生产代码中使用 eval}) if strict and len(code.splitlines()) 50: issues.append({type: suggestion, message: 函数体过长建议拆分子函数}) return {issues: issues, issue_count: len(issues)}这个示例故意做得非常简单目的是演示 Skill 的输入输出结构输入是一段代码和可选参数输出是一个结构化字典包含问题清单和数量。真实的代码审查 skill 可以在这个基础上调用 pylint、ruff 等工具并把它们的输出转成统一格式。写完 skill 后立即补一个测试脚本# 单元测试模板验证 skill 的返回值是否符合预期 def test_code_reviewer(): skill CodeReviewerSkill() result skill.execute(def add(a, b):\n return a b) assert result[issue_count] 0 result2 skill.execute(value eval(input())) assert result2[issue_count] 1 if __name__ __main__: test_code_reviewer() print(skill 测试通过)调试时如果发现 skill 没有被 Agent 调用优先检查 description它应该写清楚“什么时候调用、什么时候不调用”而不是写一堆实现细节。很多框架里 Agent 是通过描述匹配技能的描述不清晰模型就会跳过你辛辛苦苦写的功能。7. Skills 实战三个可复现的例子单 Agent Skills 的典型开发方式可以归纳为三步定义任务边界、编写 skill 模块、把 skill 注册进 Agent 的技能清单。下面三个例子建议按顺序做第一个最简单第三个偏工程化。7.1 代码审查 Skill场景用户提交代码片段Agent 调用代码审查 skill输出结构化问题清单。输入示例一段包含eval和未捕获异常的 Python 函数。操作步骤按上一节的 JSON 文件定义参数结构。实现execute内部调用 ruff 或 pylint把结果转换为 issues 列表。把 skill 注册到 Agent 的可用技能列表。让 Agent 运行任务“审查以下代码并给出优先级建议”。预期结果Agent 返回 JSON 格式的问题列表每条包含类型、行号、建议。判断成功的标准不是模型认不认同而是输出结构稳定、每条建议与代码真实匹配。如果出现幻觉式建议检查是否是模型把 skill 输出和自身知识混合了通常进一步收紧 skill 内部逻辑、减少 prompt 自由度可以改善。7.2 文档解析 Skill场景给 Agent 一个 PDF 或图片路径由解析 skill 完成文字抽取再由 Agent 整理为 Markdown。输入示例一份包含标题、表格和图文的 PDF。操作步骤文档解析 skill 内部调用 OCR 或 PDF 解析库。输出统一为 pages 数组每页包含 text 和 blocks。Agent 拿到 pages 后按需重组为 Markdown。对解析失败的页面记录错误不中断整个批次。预期结果PDF 文本被完整抽取表格在 Markdown 中尽量保持行列关系。因为不同解析库对复杂排版的处理差异很大建议先用 3 到 5 份真实文档测试再决定是否批量。判断成功的标准是抽取内容可读、无大面积乱码、表格结构基本完整。7.3 自动化测试 Skill场景根据接口描述生成并执行测试用例返回通过/失败汇总。输入示例一个 HTTP 接口的 OpenAPI 摘要和一份测试要求。操作步骤自动化测试 skill 读取接口定义生成一组请求用例。逐条执行请求记录状态码和响应时间。按配置的断言规则判断通过或失败。输出汇总报告。预期结果能列出每一条用例的执行状态失败用例带请求和响应摘要。这个 skill 很适合放进 CI 做回归但要注意执行环境要与被测环境隔离避免测试数据污染生产。判断成功的标准是结果可复现、失败信息可定位。三个例子做完你应该已经理解 Agent Skills 的核心模式Agent 负责“决定做什么”skill 负责“稳定地做”。下一阶段再去接触多 Agent 协作就顺理成章了。8. 多 Agent 协作实战多 Agent 协作不是多写几个 Agent 然后互相喊话而是设计一套清晰的职责划分和信息交换规则。最常见的两种模式Supervisor 模式一个主管 Agent 负责任务规划把子任务分发给多个专职 worker Agent汇总结果后再输出最终结论。对等协作模式多个 Agent 各自负责一段通过共享消息队列或知识库交换中间结果。对于大多数业务场景从 Supervisor 模式开始更稳。下面的伪代码展示了核心思路具体类名和调度 API 需要按所选框架替换# 多 Agent 协作模板Supervisor 分发任务 class Supervisor: def __init__(self, workers: dict): self.workers workers self.max_rounds 5 def handle(self, task: str) - str: current task for _ in range(self.max_rounds): # 主管决定下一步调用哪个 worker plan self.plan(current) if plan[done]: return self.answer(current) worker self.workers[plan[worker]] current worker.run(plan[payload]) raise RuntimeError(超过最大协作轮次任务终止)多 Agent 协作经常遇到三类问题。第一类是消息格式不统一。A Agent 返回的是 MarkdownB Agent 期待的是 JSON协作就越传越乱。解决方案是在项目里定义统一消息结构比如固定{sender, task_type, payload, timestamp}所有 Agent 只认这个接口。第二类是上下文爆炸。每个 Agent 把前面对话全带进下一轮token 成本飙升最后模型还会迷失重点。方案是按需传递摘要而不是完整历史或者用一个共享的知识库存储中间产物Agent 只取与当前任务最相关的部分。第三类是死循环。A 调 B、B 调 A永远停不下来。除了最外层加轮次限制最好在消息里带round字段或者在编排器层面做调用计数。出现 “agent execution terminated due to error” 这类中断时不要只看最后一行报错先查是不是协作消息格式、未捕获异常还是超时导致的。9. 接口 API 调用与批量任务把 Agent Skills 封装成 HTTP API是接入业务系统最直接的方式。整体思路是启动一个服务进程监听指定端口接收包含任务描述和 skill 参数列表的请求返回结构化结果。一个通用调用接口设计如下POST /agent/run Content-Type: application/json请求体{ task: 审查以下 Python 代码并给出问题清单, skills: [code_reviewer], input: def add(a, b):\n return a b, max_rounds: 5 }用 curl 快速验证curl -X POST http://127.0.0.1:8000/agent/run \ -H Content-Type: application/json \ -d {task: 审查以下 Python 代码并给出问题清单, skills: [code_reviewer], input: def add(a, b):\n return a b, max_rounds: 5}Python 的 requests 调用示例import requests url http://127.0.0.1:8000/agent/run payload { task: 审查以下 Python 代码并给出问题清单, skills: [code_reviewer], input: value eval(input()), max_rounds: 5, } try: resp requests.post(url, jsonpayload, timeout120) resp.raise_for_status() print(resp.json()) except requests.exceptions.Timeout: print(请求超时检查 Agent 脚本或增大 timeout) except requests.exceptions.ConnectionError: print(连接失败确认服务已启动且端口正确)真实项目的接口字段要以你封装的 Agent 服务为准上面这份属于可修改的通用格式引入新项目时先确认参数名和返回结构。批量任务方面可以按“目录遍历 循环调用 失败重试”来实现。比如把待处理文件放在./inputs每个文件生成一个任务执行日志写入./logs# 批量任务执行模板 import logging import time from pathlib import Path logging.basicConfig(levellogging.INFO, filename./logs/batch.log) INPUT_DIR Path(./inputs) input_files list(INPUT_DIR.glob(*.txt)) for index, file in enumerate(input_files, start1): content file.read_text(encodingutf-8) try: result agent_run(task处理该文件内容, inputcontent) out_path Path(./outputs) / f{file.stem}.json out_path.write_text(result, encodingutf-8) logging.info(第 %d 个任务完成: %s, index, file.name) except Exception as exc: logging.error(第 %d 个任务失败: %s, 错误: %s, index, file.name, exc) time.sleep(1)批量任务的关键不在并发而在可控每批先跑 1 条验证输入输出结构再跑全量失败任务要自动重试还是人工介入要提前设计日志必须包含输入文件、耗时、结果摘要。如果任务量大建议引入任务队列组件避免直接用 Python 的for循环跑几千个请求因为中间任何一个异常都可能让整个脚本中断。10. 资源占用与性能观察Agent Skills 的资源占用有两个完全不同的维度取决于你用云端 API 还是本地模型。用云端 API 时主要观察三个指标Token 消耗总输入 总输出 token。多 Agent 协作中上下文传递会把 token 快速放大。延迟一次任务从提交到返回的耗时。LLM 每轮推理都占时间skill 数量多、代理轮次多延迟就高。限流API 提供商对并发和每分钟请求数有限制。批量任务触发限流后需要做指数退避重试。用本地模型推理时还要额外看显存占用模型权重、KV cache、多轮上下文都会占显存具体数值取决于模型参数量和量化方式需按本机实测。CPU/内存文档解析、OCR、文件格式转换等 skill 即使不跑模型也会消耗 CPU 和内存。磁盘 IO批量读取大文件、保存中间结果时磁盘速度可能成为瓶颈。更稳妥的判断是在你的目标机器上跑一条最小任务记录响应时间和资源占用再逐步增加上下文长度和并发量找出拐点。不要照搬别人的显存数字不同模型、不同量化、不同推理框架的差异很大。性能优化建议给 Agent 设置最大轮次避免无意义地继续推理。上下文只保留必要内容多用摘要和引用不要全量粘贴历史。Skill 内部尽量使用确定性代码减少不必要的 LLM 二次生成。批量任务按批次提交控制并发数先保稳定再提速度。高频调用的 skill 接口可以在服务层做结果缓存。11. Agent Skills 常见问题与排查方法实际开发中遇到问题不可怕可怕的是没有排查思路。下面把最常见的问题整理成表。问题现象可能原因排查方式解决方案skill 一直没有被调用描述不清或技能未被注册查看 Agent 日志中技能匹配结果优化 description 或检查注册列表调用后返回结构乱输入参数不匹配打印 skill 收到的原始参数用 JSON Schema 校验入参agent execution terminated due to error代码异常、超时或模型返回异常查看完整堆栈和上下文增加异常捕获、降低单轮复杂度多 Agent 协作死循环缺少轮次限制检查编排器日志调用链加 max_rounds 和调用计数上下文 token 超限多轮对话全量传递查看 token 统计精简上下文、用摘要替代历史API 批量任务卡住限流或单任务超时查看响应状态码加超时、重试和退避输出质量不稳定Skill 边界太大或提示词不清晰对比多次输出样例缩小 skill 范围、补充约束显存不足本地模型太大或上下文过长查看推理服务日志换小模型、量化、降低 max tokens依赖安装失败版本冲突看 pip 报错按项目文档锁定版本排查时先看日志再看输入输出最后才怀疑模型不行。很多“模型不聪明”的情况实际是任务描述有歧义或 skill 输入输出不匹配。12. 最佳实践与使用建议项目从“能跑”到“能维护”需要建立几套习惯。第一每个 skill 必须有独立测试。Skill 是执行单元完全可以用单元测试保证基本正确性。测试覆盖正常输入和异常输入改动时先跑测试再上线。第二skill 的描述文件要写清楚适用与不适用场景。描述不是给用户看的是给 Agent 选路时看的。一个“什么时候不该调用”的说明能省掉大量无效调用。第三保留一套最小可运行配置。哪怕项目已经很大也要维护一个 skill 数量最少、模型参数最小的 demo 版本用于验证框架升级、依赖变更和新环境部署。第四批量任务要加日志和重试。每条任务记录输入文件、开始时间、结束时间、结果摘要或错误信息失败任务先重试一次仍然失败就写入 failure 列表不静默吞掉。第五接口服务要限制访问范围。如果 Agent API 暴露在公司内网也要校验调用方身份、限制请求频率避免被其他系统误刷。第六涉及人脸、声音、版权素材时确认授权。Agent 可以生成代码、文章、图片、声音但生成能力和商用授权是两回事。发布或商用前做效果复核必要时加来源声明。第七学会用小步快跑的方式升级技能。每次只改一个 skill观察效果避免多个改动混在一起无法定位回归。13. 总结与下一步Agent Skills 最值得尝试的点是它能把混乱的 Agent 开发拆成一个个可测试的执行单元。第一个要验证的功能可以是一个最简单的“输入文本、返回结构化结果”的 skill——先跑通描述、执行、测试的小闭环再扩展到代码审查、文档解析、自动化测试最后才考虑多 Agent 协作。最容易踩的三个坑集中在描述不清晰、上下文膨胀和缺少轮次限制。描述不清晰导致 skill 不生效上下文膨胀导致 token 成本失控缺少轮次限制导致多 Agent 协作死循环。这三类问题在项目一开始就用统一的接口规范和调度约束做防御比后期修 bug 性价比高得多。下一步可以沿着三条方向继续一是把常用能力沉淀为 skill 库形成团队内部的技能复用机制二是尝试把 agent 接入现有业务系统通过 API 提供稳定服务三是做更细的性能与成本监控让每一次 Agent 调用都可衡量、可优化。建议把本文的示例代码保存下来搭建一个最小项目跑一遍再逐步往里面加自己的场景。
