如果你正在开发 AI Agent或者刚接触智能体开发大概率会经常听到一个词Agent Skills。尤其是吴恩达的 Agent Skills 教程公开之后整个 AI 开发圈对“技能”这个概念的热情一下子被点燃了。但说实话网上讲 Agent 架构、Agent 框架、多 Agent 协作的资料很多真正能把 Agent Skills 从安装、配置到实战讲透的内容却不多。要么只讲概念不动手要么代码一贴就完事完全没有解释每一步为什么这样做。这篇文章会围绕 Agent Skills 这个主题完整拆解一套可以从零上手的实战流程。内容包括Agent 与 Agent Skills 的概念边界、环境准备与安装步骤、Skill 的定义与配置方式、一个完整的 Agent Skills 实战案例、多 Agent 协作的实现思路以及常见报错的排查方法。无论你是刚开始接触智能体开发的新手还是已经在做 Agent 项目的开发者都可以在文章中找到可以直接落地的内容。1. 为什么 Agent 突然需要 “Skills”1.1 从 Prompt 到 Agent 的演进过去的 AI 应用开发本质上是在“写提示词”。你给模型一段精心编写的 Prompt模型按照你的要求完成文本生成、代码补全、内容总结等任务。这种方式确实有效但存在一个天然边界语言模型无法执行真实世界里的操作。比如你让模型“把这份文件上传到服务器”模型无法自己完成因为它不具备调用 API 的能力。你让模型“查询数据库里最近一周的订单数据”模型无法直接连数据库它只能生成一段查询 SQL然后由人工去执行。Agent 的出现改变了这个问题。它的核心特点是模型不仅负责理解任务还负责规划任务、调用工具、执行动作并根据执行结果决定下一步操作。所以 Agent 不是单纯的“聊天机器人”而是一个能自主行动的任务执行系统。1.2 Agent Skills 解决了什么问题Agent 能调用工具以后新的问题又出现了如何让 Agent 学会一个完整的、流程化的能力举个例子。你希望 Agent 能帮你写一份周报这个任务不是“调用一个函数”那么简单它需要收集本周的代码提交记录汇总每个模块的改动类型分析是否有风险项按固定模板生成周报文本把周报发送到指定邮箱。如果只是给 Agent 暴露一个“发送邮件”的函数它完成不了整个流程。真正合理的做法是把这个完整的流程封装成一个“技能”。Agent Skills 就是让 Agent 具备某项完整能力的功能单元它是一套可以被 Agent 调用的、结构化的能力封装而不仅仅是一个函数。打个比方函数像是一个螺丝刀你告诉 Agent“用螺丝刀拧那颗螺丝”Skill 像一个“换轮胎工具箱”里面包含了千斤顶、扳手、备用轮胎并且有操作步骤Agent 拿到这个工具箱后可以按照既定流程完成换轮胎这件事。1.3 直观学习路径参考如果你希望系统化掌握 Agent Skills除了阅读本文之外也可以参考一套我整理过的学习路径从 Agent 基础概念理解 → 框架安装 → 单个 Skill 编写与调试 → 多 Skill 组合 → 多 Agent 协作这样的顺序可以帮你少走很多弯路。本文的章节安排也按照这个路径展开。2. 前置概念Agent、Skill、Workflow 的区别在进入实战之前有必要先把几个高频概念理清楚。很多初学者卡住不是代码写不出来而是概念边界没搞清楚。2.1 Agent 是什么Agent智能体是一个能感知环境、做出决策并执行动作的软件系统。在 AI 开发语境下Agent 通常指LLM 大模型 规划决策模块 工具调用模块 记忆模块Agent 收到用户需求后会先拆解任务然后决定调用什么工具、按什么顺序执行最后把结果整合成答案返回给用户。2.2 Skill 是什么Skill技能是 Agent 可以调用的“能力单元”。它通常包含组成部分作用技能描述告诉 Agent 这个技能是做什么的适合什么场景触发条件什么情况下 Agent 应该调用这个技能参数定义调用技能时需要的输入参数执行逻辑技能内部的具体实现代码或流程输出格式技能执行完后的返回结果结构Skill 和普通函数的区别在于Skill 是面向 Agent 设计的它有完整的“自我说明”Agent 通过理解说明来决定是否调用、怎么调用。而普通函数是面向开发者设计的由代码主动调用。2.3 Workflow 是什么Workflow 是多个步骤的编排流程。Skill 可以理解为一个独立能力Workflow 则是把这些能力按照业务逻辑串联起来。举个例子用户输入需求 ↓ Agent 判断需要哪些 Skill ↓ 按顺序调用 Skill A → Skill B → Skill C ↓ 汇总结果返回用户这就是一个 Workflow。Skill 是积木Workflow 是搭积木的方式。2.4 关键区别表格维度AgentSkillWorkflow本质智能体系统能力封装单元流程编排核心关注点决策与规划单个能力的执行多步骤的串联是否包含模型是不一定不一定能否独立运行能不能需要被调用不能需要被触发典型例子AutoGPT、Manus“周报生成技能”“风险告警→工单创建→邮件通知”在实际开发中这三个概念经常一起出现但它们各自解决的问题完全不同。理解清楚后再去看 Agent Skills 的安装和开发思路会更清晰。3. 环境准备与最小项目骨架这一节开始进入实操。我们以目前社区使用较多、资料也比较丰富的 Python 技术栈为例搭建一个支持 Agent Skills 的最小项目环境。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3.1 环境清单操作系统Windows 10/11、macOS、Linux 均可Python建议 3.10 及以上版本包管理工具pip 或 poetryAgent 框架以开源框架为主你可以选择适合自己项目的框架大模型 API需要准备一个可用的 LLM API Key例如 OpenAI 兼容接口或国内大模型平台的 API开发工具VS Code 或 PyCharm建议打开终端面板方便运行命令。3.2 创建项目目录在命令行中执行mkdir agent-skills-demo cd agent-skills-demo python -m venv venv创建虚拟环境是一个值得从一开始就养成的习惯。每个项目都有自己独立的依赖环境不会因为不同项目使用了不同版本的库而互相干扰。激活虚拟环境Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活后命令行前面会出现(venv)前缀说明你已经在虚拟环境中了。3.3 安装依赖pip install openai pip install agent-framework这里说明一下agent-framework只是一个泛指具体包名取决于你选择的 Agent 框架。不同框架在 Skill 的编写方式上有细微差别但底层原理是相通的。本文示例代码基于假设的框架 API核心思路可以直接迁移到其他框架上。3.4 项目结构建议的项目结构如下agent-skills-demo/ ├── venv/ # 虚拟环境 ├── skills/ # 技能目录 │ ├── __init__.py │ ├── weekly_report.py # 周报技能 │ ├── data_query.py # 数据查询技能 │ └── email_sender.py # 邮件发送技能 ├── agents/ # Agent 定义 │ ├── __init__.py │ └── main_agent.py # 主 Agent ├── workflows/ # 工作流编排 │ └── report_workflow.py # 报告生成工作流 ├── config.py # 配置文件 └── main.py # 入口文件这样的目录设计核心思路是按能力维度拆分文件。Skill 放到自己的目录Agent 定义单独放Workflow 单独放后续扩展时不需要改太多既有代码。4. Agent Skills 的核心设计方式在写代码之前我们需要先理解 Skill 的设计方法。一个设计良好的 Skill需要遵循几个原则职责单一、描述清晰、参数明确、输出结构化。4.1 Skill 的基本结构一个 Skill 通常包含以下关键字段{ name: weekly_report, description: 根据本周的代码提交记录生成结构化周报, parameters: { type: object, properties: { start_date: {type: string, description: 开始日期}, end_date: {type: string, description: 结束日期}, project: {type: string, description: 项目名称} }, required: [start_date, end_date, project] }, returns: { type: object, properties: { report: {type: string, description: 生成的周报内容}, commits_count: {type: integer, description: 提交次数} } } }4.2 为什么描述字段特别重要Agent 调用 Skill 并不是靠硬编码而是靠“理解描述”来决策的。也就是说Agent 看到你的 Skill 描述后会判断当前用户需求是否匹配这个技能。如果描述写得模糊Agent 就可能在需要调用的时候不调用不需要的时候乱调用。好的描述示例当用户需要生成本周工作汇报、周报、项目进展总结时使用本技能。输入参数为起始日期、结束日期和项目名称。输出为结构化周报文本。差的描述示例周报功能。4.3 Skill 实现代码的推荐模式每个 Skill 建议封装为一个类实现两个核心方法can_handle判断任务是否匹配本技能execute执行技能逻辑返回结果。class WeeklyReportSkill: name weekly_report description 根据代码提交记录生成周报 def can_handle(self, task: str) - bool: keywords [周报, 周汇报, weekly report] return any(k in task.lower() for k in keywords) def execute(self, start_date: str, end_date: str, project: str) - dict: # 模拟获取代码提交记录 commits self._fetch_commits(start_date, end_date, project) # 生成周报 report self._build_report(commits) return {report: report, commits_count: len(commits)}这种封装方式的优点是Skill 的内部逻辑与 Agent 的调用逻辑解耦。你在 Skill 内部可以随意改实现细节只要保持execute的输入输出稳定Agent 就不需要改动。5. 实战一从零编写一个可复用的 Skill为了让你更直观地理解这里实现一个“代码提交统计技能”。它模拟从 Git 仓库读取提交记录并生成统计信息。这个技能在真实项目中非常常见而且逻辑清晰适合作为第一个上手案例。5.1 实现 Skill 代码文件路径skills/git_stats.pyimport subprocess from datetime import datetime class GitStatsSkill: name git_stats description 统计指定时间段内的 Git 提交记录按提交者分组汇总适用于项目进展统计、绩效评估数据准备等场景。 def can_handle(self, task: str) - bool: keywords [提交记录, git, 代码统计, 提交次数] return any(k in task.lower() for k in keywords) def execute(self, repo_path: str, start_date: str, end_date: str) - dict: 统计 Git 仓库提交记录 :param repo_path: 本地仓库路径 :param start_date: 开始日期格式 YYYY-MM-DD :param end_date: 结束日期格式 YYYY-MM-DD :return: 统计数据 try: cmd [ git, -C, repo_path, log, f--since{start_date}, f--until{end_date}, --prettyformat:%an|%s, ] result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) lines result.stdout.strip().splitlines() stats {total: len(lines), by_author: {}} for line in lines: if not line: continue parts line.split(|) author parts[0] commit_msg parts[1] if len(parts) 1 else stats[by_author].setdefault(author, []).append(commit_msg) return {status: success, data: stats} except subprocess.CalledProcessError as e: return {status: error, message: str(e)}5.2 在 Agent 中注册 Skill文件路径agents/main_agent.pyfrom skills.git_stats import GitStatsSkill class MainAgent: def __init__(self): self.skills [] self.register_skill(GitStatsSkill()) def register_skill(self, skill_instance): 注册一个技能到 Agent self.skills.append(skill_instance) def find_matching_skill(self, task: str): 根据任务描述找到匹配的技能 for skill in self.skills: if skill.can_handle(task): return skill return None def handle(self, task: str): 处理用户请求 skill self.find_matching_skill(task) if not skill: return 抱歉我没有找到可以处理该请求的技能。 # 实际项目中这里会通过 LLM 识别参数并调用 execute return skill.execute( repo_path/path/to/your/project, start_date2025-01-01, end_date2025-01-31, )5.3 运行测试文件路径main.pyfrom agents.main_agent import MainAgent if __name__ __main__: agent MainAgent() result agent.handle(帮我统计一下最近一个月的代码提交记录) print(result)运行python main.py预期输出{status: success, data: {total: 23, by_author: {Alice: [修复登录 bug, 优化接口性能], Bob: [新增用户注册功能]}}}到这里你已经完成了第一个完整的 Agent Skill 开发闭环定义了技能 → 注册到 Agent → 根据任务匹配技能 → 执行并返回结果。这是后面所有高级玩法的基础。6. 实战二多 Agent 协作与 Skill 编排单个 Agent 能处理的任务有限。在实际项目中一个完整的业务流程通常由多个 Agent 协作完成每个 Agent 负责自己擅长的那部分并且可以调用不同的 Skill。6.1 多 Agent 协作的典型场景以“自动生成项目周报并发送邮件”为例这个流程可以拆分为数据分析 Agent调用 Git 统计 Skill获取代码提交数据内容生成 Agent调用周报生成 Skill把数据整理成结构化文本邮件发送 Agent调用邮件发送 Skill把周报内容发送给指定收件人。三个 Agent 各司其职通过一个协调者串联起来。这里的关键在于数据在 Agent 之间传递时需要格式统一。如果数据分析 Agent 返回的是一个 JSON内容生成 Agent 必须能正确解析这个 JSON否则协作就会断裂。6.2 编写协作流程文件路径workflows/report_workflow.pyimport json from agents.main_agent import MainAgent from skills.git_stats import GitStatsSkill from skills.weekly_report import WeeklyReportSkill from skills.email_sender import EmailSenderSkill class ReportWorkflow: 周报生成与发送工作流 def __init__(self): # 创建多个 Agent分别负责不同环节 self.data_agent MainAgent() self.data_agent.register_skill(GitStatsSkill()) self.content_agent MainAgent() self.content_agent.register_skill(WeeklyReportSkill()) self.send_agent MainAgent() self.send_agent.register_skill(EmailSenderSkill()) def run(self, repo_path: str, start_date: str, end_date: str, to_email: str): # 第一步收集数据 data_result self.data_agent.handle(统计代码提交记录) if data_result[status] ! success: return {status: failed, step: data_collection, error: data_result} # 第二步生成周报 report_result self.content_agent.handle(根据以下数据生成周报) # 实际项目中这里会把 data_result 作为参数传给内容生成 Agent # 第三步发送邮件 send_result self.send_agent.handle(发送周报邮件到指定地址) # 实际项目中这里会把 report_result 作为参数传给发送 Agent return {status: success, data: data_result}6.3 多 Agent 协作的注意点多 Agent 协作并不是“Agent 越多越好”。每一个额外的 Agent 都会带来通信开销和错误传播风险。在实际工程中应该遵循最小协作原则能用一个 Agent 完成的任务不要拆成两个只有任务边界确实清晰、每个环节需要不同技能时才值得拆分。另外多 Agent 协作中最常出现的问题是数据在不同 Agent 之间传递时丢失或格式错误。建议在每个 Agent 之间定义清晰的接口协议并用 JSON Schema 做校验。这样即使某个 Agent 的输出发生变化也能在入口处尽早发现异常。7. 常见问题与排查思路在编写 Agent Skills 的过程中几乎每个人都会遇到一些相似的问题。把高频问题整理成表格方便你排查问题现象常见原因解决思路Agent 不调用 Skill直接瞎回答Skill 描述信息不够明确Agent 无法判断任务匹配检查 description 字段补充触发条件和典型场景调用了错误的 Skillcan_handle 方法关键词过于宽泛细化关键词增加排除条件Skill 执行时报错参数缺失LLM 未能正确抽取参数参数定义中增加更详细的字段描述和示例值多个 Skill 描述相似Agent 混淆技能之间职责重叠合并技能或明确区分各自适用场景返回结果不稳定格式经常变化没有对输出做强约束使用结构化输出协议并在返回前做校验Agent 无限循环调用同一个 Skill缺少终止条件或最大调用次数限制设置调用次数上限并监控调用链大模型返回超时单次推理时间太长或网络不稳定缩小输入上下文优化 Skill 内部逻辑环境安装依赖冲突项目依赖与其他包版本不兼容使用虚拟环境锁定依赖版本7.1 典型的 “Agent execution terminated due to error” 问题在开发 Agent 时你可能会遇到一个很常见的错误提示agent execution terminated due to error。这个报错的含义是 Agent 在执行过程中发生了致命错误执行被中断。常见原因包括Skill 内部抛出了未捕获的异常Agent 循环调用达到上限后被强制终止大模型返回了 Agent 无法解析的格式某个子 Agent 返回了空结果导致后续环节空指针。排查时建议先打开详细的日志模式把 Agent 每一步的输入输出都打印出来定位是“哪一步”出了问题再针对性地修复。8. 工程化落地建议把 Agent Skills 从 Demo 搬到生产环境需要额外考虑很多因素。这里分享几条比较实用的工程建议。8.1 Skill 命名与目录规范Skill 的命名要能直接表达职责。推荐使用“动词对象”的格式例如fetch_weather、send_email、generate_report。避免使用模糊的通用名称如utils、helper、tool。每个 Skill 放在独立文件中文件名与 Skill 名称保持一致。这样当项目变大时你可以快速定位某个技能的代码位置。8.2 统一输入输出格式所有 Skill 的返回值建议统一使用如下结构{ status: success | error, data: ..., message: 错误信息仅在 error 时有值 }这种设计的好处是Agent 的调用方可以通过统一入口判断执行结果不需要为每个 Skill 单独写异常处理。8.3 日志与可观测性生产环境中的 Agent 系统日志是救命稻草。建议至少记录以下信息每次 Skill 调用的参数和返回值调用耗时Agent 的决策链路为什么选择了这个 Skill错误堆栈。8.4 安全边界Agent 能调用 Skill意味着它能执行代码、触达外部系统。这带来一个重要的安全问题Skill 的权限范围必须明确控制。在设计 Skill 时要严格遵循最小权限原则。比如邮件发送 Skill不应该同时具备读取所有联系人的权限数据库查询 Skill应该只暴露必需的字段禁止执行 DELETE 或 DROP 操作。对于任何涉及修改、删除、写入外部系统的 Skill必须增加人工确认环节或操作前审查机制。8.5 测试策略Skill 的测试不同于普通函数的测试。不仅要测试“输入正确时输出是否正确”还要测试“Agent 是否能正确触发这个 Skill”。建议建立两类测试单元测试验证 Skill 内部逻辑集成测试模拟用户请求验证 Agent 是否能正确选择并组合调用多个 Skill。9. 总结与学习路线Agent Skills 是 AI Agent 开发中的一个重要能力单元它让 Agent 不再只是“会聊天的模型”而是一个可以真实执行任务的智能系统。本文从概念入手讲解了 Agent 与 Skill 的区别并通过两个实战案例帮助你掌握单 Skill 开发与多 Agent 协作的实现方法。如果你打算继续深入学习建议按照下面的路径推进先巩固单 Agent 单 Skill 的开发确保你能独立完成从环境搭建到技能发布的完整流程再尝试多 Skill 组合让 Agent 能根据任务动态选择多个技能最后研究多 Agent 协作把一个复杂业务流程拆解为多个 Agent 的分工协作在此基础上补充工程化能力日志、监控、测试、权限控制、灰度发布。方法论层面的参考可以多看吴恩达的 Agent Skills 教程和公开分享工程实践方面则需要动手做一两个完整的项目才能真正掌握。这里想提醒的是不要陷入概念研究里出不来回。Agent 开发是一个实践性极强的领域你花两天时间看完十个框架的文档不如花两小时把本文的实战代码跑通一遍。如果你在实践过程中遇到问题欢迎通过评论或私信交流。后面我还会继续更新 Agent Skills 在不同框架中的实现方式、多 Agent 协作模式、企业级落地案例等内容。如果这篇文章对你有帮助可以收藏备用也欢迎转发给正在学习 Agent 开发的朋友。附录本文涉及的关键术语速查术语含义Agent智能体能感知、决策、执行任务的 AI 系统Agent Skills面向 Agent 设计的技能封装单元Workflow工作流多步骤任务的编排LLM大语言模型Fine-tuning微调使用业务数据进一步训练模型RAG检索增强生成结合外部知识库的生成方式Function Calling函数调用让模型输出结构化调用指令的能力