2026年之前很多人在学 Agent 的时候会遇到一个很现实的问题Prompt 写了一大堆效果却时好时坏想复用一个能力却发现只能复制粘贴想在团队里共享一个“会分析 CSV 的 Agent”最后往往变成了在对话里反复解释规则。吴恩达在 DeepLearning.AI 上提出的Agent Skills概念正好回答了这个问题。它不是一个新的编程框架也不是一套复杂的协议而是一种让大语言模型“按需获得专项能力”的组织方式。本文会从概念、原理、手写实战、进阶优化到工程化落地完整拆解 Agent Skills 的来龙去脉。如果你之前看过吴恩达的机器学习课程、深度学习笔记或者《面向开发者的提示词工程》那么对这位老师的教学风格应该不陌生不堆术语用最直白的方式讲清楚原理再带着你做一遍。这篇文章也会按照这个思路来保证你有基础能看懂有经验能直接落地。1. Agent Skills 到底是什么1.1 先从 Agent 开发的痛点说起在接触 Agent Skills 之前很多人对 Agent 开发的理解是把 API 接好写一段长长的 system prompt然后让模型自己“思考”和“调用工具”。这种方式在小 demo 里看着不错但只要业务稍微复杂一点问题就全出来了Prompt 越来越长为了让模型完成一件事你可能要在 system prompt 里塞几十条规则模型有时候会顾此失彼。能力无法复用A 项目里写好的“CSV 分析逻辑”到了 B 项目想再用只能重新复制一遍然后根据新需求再改一通。质量不稳定模型对同一件事的理解会因为上下文长度、问题表述的差异而出现完全不同的表现。团队协作困难想让同事也知道你的 Agent“会什么”只能靠口头描述或文档但文档和实际行为经常对不上。这些问题的根源是我们一直在试图用“一段话”去描述“一项能力”而能力本身应该是可以被结构化地定义、存储和调用的。1.2 Agent Skills 的核心思想Agent Skills 这个概念可以简单理解为把一项能力封装成一个“技能包”里面既包含自然语言的指令教模型怎么用这个技能也包含代码和数据文件让模型真正具备执行能力。举个例子。传统的做法是你在 prompt 里写当你遇到 CSV 文件时你需要先读取文件头然后分析每一列的数据类型再计算平均值、最大值、最小值……这样做的问题很明显模型不见得每次都按照你的要求去做而且如果分析逻辑很复杂prompt 根本写不下。而使用 Agent Skills 的做法是创建一个csv_analyzer文件夹里面放一个SKILL.md用自然语言描述这个技能是做什么的、什么时候调用、输出什么格式再放一个csv_analyzer.py把真正的分析逻辑写在代码里模型只需要学会“什么时候调用这个技能”以及“怎么调用”具体的细节交给代码。从这个角度来看Agent Skills 的本质是把模型不擅长的确定性逻辑交给代码把模型擅长的意图理解和任务规划留给自己。1.3 Agent Skills 与 Prompt、Workflow、Agent 的区别很多初学者容易把 Agent Skills 和 Prompt、Workflow、Agent 这几个概念混淆。它们之间的边界可以这样理解概念定义特点Prompt给模型的指令文本属于输入的一部分无逻辑、无状态Agent Skills一组指令 代码 数据封装成可复用的技能有明确的输入输出可被动态加载Workflow固定顺序的流程编排步骤确定通常不支持灵活决策Agent基于大模型自主决策、调用工具、完成任务有记忆、有规划、可调用多个技能用做饭来类比Prompt 就是“菜谱上的文字说明”Agent Skills 是“已经切好配好的半成品菜包”Workflow 是“固定的做菜步骤正着执行就行”Agent 是“一个能看菜谱、能拿菜包、能根据情况调整火候的厨师”。这个比喻对后续理解很有帮助。2. Agent Skills 的构成与核心原理拆解2.1 核心三件套SKILL.md、指令与技能文件一个标准的 Agent Skill通常由三个部分构成。第一部分技能描述文件SKILL.md这是一个 Markdown 文件用自然语言描述这个技能的用途是什么在什么情况下应该使用这个技能输入需要什么数据输出应该是什么格式有什么限制和注意点。SKILL.md 的核心作用是“教模型理解技能”所以它不需要写具体实现代码而是要写清楚调用条件和调用方式。第二部分技能指令Instruction这部分通常也是自然语言但更偏向于“指导模型如何调用技能、如何处理输出”。例如如果用户的要求不明确应该先问哪个问题如果分析结果出现异常应该怎么处理输出的报告应该包含哪几个部分。有些实现中指令会被直接写在 SKILL.md 里有些则单独拆成 instruction.md。关键点在于指令是给模型看的不是给代码看的。第三部分技能执行文件Skill Files这部分是真正的代码和资源文件可以是Python 脚本Shell 脚本特定领域的配置文件模板文件静态数据字典。这些文件的作用是当模型决定调用该技能时由 Agent 框架或模型本身执行这些代码从而完成具体任务。2.2 自然语言接口与技能路由Agent Skills 最有意思的设计是它使用“自然语言接口”来做技能路由。传统开发中如果系统要支持多种功能我们会定义 REST API 接口比如/api/csv/analyze、/api/chart/generate然后由后端代码根据路由规则调用对应逻辑。Agent Skills 的思路不太一样。它的接口定义是用自然语言写在 SKILL.md 里的而“路由器”变成了大语言模型本身。当用户输入一个问题时Agent 框架会把用户的请求和当前已加载的所有技能描述一起交给模型让模型判断当前用户的需求应该调用哪个技能举个例子用户帮我分析一下这份销售数据的月度趋势。 可用技能 1. csv_analyzer分析 CSV 文件输出统计报告 2. chart_generator根据表格数据生成图表 3. sql_queryer查询数据库并返回结果 模型判断应该调用 csv_analyzer因为用户提到了“分析”和“数据”。这种设计的好处很明显新增一个技能不需要改路由代码只要在技能目录下增加文件夹即可模型对自然语言的理解能力天然支持模糊匹配和语义判断技能之间可以非常灵活地组合。当然这也是 Agent Skills 的一个风险点如果模型判断错误可能会调用错误的技能。所以 SKILL.md 中的描述质量直接决定了整个系统的准确率。2.3 Agent Skills 与 RAG、Fine-tuning 的边界很多人在学习 Agent Skills 时会不自觉地和 RAG检索增强生成、Fine-tuning微调做对比。这三者解决的问题并不相同。技术解决什么问题适合场景RAG注入外部知识让模型回答不知道的问题私有知识库问答、文档处理Fine-tuning修改模型的行为模式和输出风格特定领域术语、固定输出格式Agent Skills赋予模型一项可执行的能力数据分析、API 调用、自动化操作再简化一点RAG 是让模型“知道更多”Fine-tuning 是让模型“更听话”Agent Skills 是让模型“会干活”。三者并不互斥实际项目中完全可以在一个 Agent 里同时使用 RAG 做知识注入用 Fine-tuning 优化输出风格用 Agent Skills 扩展执行能力。3. 环境准备与开发基础3.1 开发环境与工具Agent Skills 本身不是某个特定框架的专属概念所以环境准备比较简单。本文示例基于以下环境操作系统Windows 10/11、macOS、Linux 均可语言版本Python 3.9 及以上大模型 API任意支持函数调用Function Calling或工具调用Tool Use的模型均可密钥需要准备一个可用的 LLM API Key。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你用的是 OpenAI 的 API可以参考下面的安装命令pip install openai如果你用的是其他兼容 OpenAI 协议的接口例如国内的大模型服务通常只需要修改 base_url 和 api_key 即可。3.2 基本概念Function Calling 与工具调用在深入 Agent Skills 之前有必要先理解 Function Calling。Function Calling 是 OpenAI 等大模型服务在 2023 年推出的能力。它的核心逻辑是开发者预先声明一组“函数”包括函数名、参数说明和函数描述用户输入问题后模型不直接输出答案而是输出“需要调用哪个函数参数是什么”开发者根据模型的输出在本地执行真实函数把执行结果返回给模型模型再基于结果生成最终回答。Agent Skills 在某种程度上可以理解为 Function Calling 的自然语言版本。区别在于Function Calling 是结构化的 JSON 声明而 Agent Skills 使用 Markdown 文件描述能力边界更灵活也更便于扩展。下面演示一个最简单的函数调用示例# 文件路径examples/function_calling_demo.py from openai import OpenAI client OpenAI( api_key你的API密钥, base_urlhttps://api.openai.com/v1 ) tools [ { type: function, function: { name: get_weather, description: 获取指定城市的天气信息, parameters: { type: object, properties: { city: { type: string, description: 城市名例如北京 } }, required: [city] } } } ] response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 北京今天天气怎么样}], toolstools, tool_choiceauto ) print(response.choices[0].message)运行后模型通常会返回一个 tool_calls 对象里面包含函数名get_weather和参数{city: 北京}。开发者拿到这些信息后再去执行真实的天气查询逻辑。3.3 搭建一个最小实验项目为了直观理解 Agent Skills我们不需要一上来就引入重型框架。可以先搭建一个最小项目用最简单的方式模拟“模型判断 代码执行”的链路。项目结构如下agent_skills_demo/ ├── main.py ├── skills/ │ └── csv_analyzer/ │ ├── SKILL.md │ └── csv_analyzer.py └── data/ └── sales_data.csv这个结构非常简洁但已经具备了 Agent Skills 的全部核心要素。后面第 4 节会逐步填充每个文件的代码。4. 手写一个 Agent Skill完整实战4.1 需求分析与技能设计现在来做一个具体的实战案例。业务背景你经常需要分析销售数据希望有一个 Agent 能自动读取 CSV 文件并生成统计报告。报告内容包括总行数和总销售额每月销售额汇总销售额最高的月份数据的基本统计信息均值、最大、最小。如果用传统 Prompt 方案模型需要自己读 CSV、自己计算很容易算错。如果使用 Agent Skills计算逻辑全部交给 Python 代码模型只需要决定何时调用、怎么解读结果即可。这个技能的设计思路技能名称csv_analyzer技能职责读取 CSV 文件输出统计报告适用场景用户要求分析 CSV 数据、汇总数据、查看统计数据时输入数据用户提供的 CSV 文件路径输出格式JSON 格式的统计结果4.2 创建技能目录结构首先创建目录结构mkdir -p agent_skills_demo/skills/csv_analyzer mkdir -p agent_skills_demo/data cd agent_skills_demo然后生成一份示例销售数据# 文件路径generate_data.py import csv import random from datetime import datetime, timedelta start_date datetime(2025, 1, 1) with open(data/sales_data.csv, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([date, amount]) for i in range(365): day start_date timedelta(daysi) amount random.randint(1000, 20000) writer.writerow([day.strftime(%Y-%m-%d), amount])运行这个脚本python generate_data.py运行后data/sales_data.csv中会生成一年 365 天的模拟销售数据包含date和amount两列。4.3 编写 SKILL.mdSKILL.md 是整个技能的灵魂写得好不好直接决定模型能不能正确调用。# CSV 数据分析技能 ## 技能描述 本技能用于读取 CSV 文件并生成统计报告。当用户提供 CSV 文件路径并希望分析数据时使用。 ## 适用场景 - 用户要求“分析这个 CSV 文件” - 用户希望统计销售数据、汇总数据、查看趋势 - 用户想知道数据的总数、均值、最大值、最小值 ## 不适用场景 - 用户要求修改 CSV 内容请使用 csv_editor 技能 - 用户要求生成图表请使用 chart_generator 技能 ## 输入参数 - file_path: CSV 文件路径必选 ## 输出格式 返回 JSON包含以下字段 - total_rows: 总行数不含表头 - total_amount: 销售总额 - monthly_summary: 每月销售额列表 - best_month: 销售额最高的月份 - statistics: 基础统计信息 ## 注意事项 - 如果 CSV 文件不存在或无法解析请先向用户确认文件路径 - 如果 CSV 中没有 amount 列请自动识别第一列作为数值列这个 SKILL.md 的写法有几个要点场景描述足够具体模型能根据描述快速匹配用户意图明确不适用场景避免模型在需要其他技能时误调用定义输入输出格式让模型知道调用后能得到什么、需要返回什么写清注意事项提升模型在异常场景下的处理能力。4.4 编写技能执行代码下面是技能的实际执行逻辑# 文件路径skills/csv_analyzer/csv_analyzer.py import csv import json from collections import defaultdict from pathlib import Path def analyze_csv(file_path: str) - dict: 读取 CSV 文件并生成统计报告。 file_path Path(file_path) if not file_path.exists(): return {error: f文件不存在: {file_path}} with open(file_path, r, encodingutf-8) as f: reader csv.DictReader(f) rows list(reader) if not rows: return {error: CSV 文件为空} # 自动识别日期列和数值列 date_col None amount_col None for col in rows[0].keys(): col_lower col.lower() if date in col_lower or time in col_lower: date_col col if amount in col_lower or sales in col_lower or value in col_lower: amount_col col if amount_col is None: # 如果没有找到常见列名默认使用第二列 amount_col list(rows[0].keys())[-1] total_rows len(rows) total_amount 0 monthly_summary defaultdict(float) amounts [] for row in rows: try: val float(row[amount_col]) except (ValueError, TypeError): continue total_amount val amounts.append(val) if date_col: month row[date_col][:7] monthly_summary[month] val amounts.sort() n len(amounts) mean_value sum(amounts) / n if n 0 else 0 max_value amounts[-1] if n 0 else 0 min_value amounts[0] if n 0 else 0 best_month max(monthly_summary, keymonthly_summary.get) if monthly_summary else None statistics { mean: round(mean_value, 2), max: max_value, min: min_value, count: n } result { total_rows: total_rows, total_amount: round(total_amount, 2), monthly_summary: dict(monthly_summary), best_month: best_month, statistics: statistics } return result if __name__ __main__: # 方便单独测试 data analyze_csv(../../data/sales_data.csv) print(json.dumps(data, ensure_asciiFalse, indent2))单独运行测试cd agent_skills_demo/skills/csv_analyzer python csv_analyzer.py预期输出类似{ total_rows: 365, total_amount: 3765432.0, monthly_summary: { 2025-01: 265432.0, 2025-02: 289012.0 }, best_month: 2025-11, statistics: { mean: 10316.25, max: 19988.0, min: 1002.0, count: 365 } }4.5 接入 Agent 并测试接下来把技能接入一个简单的 Agent 主程序。# 文件路径main.py import json from openai import OpenAI client OpenAI( api_key你的API密钥, base_urlhttps://api.openai.com/v1 ) # 模拟从文件读取技能描述 SKILL_DESCRIPTION 技能名称: csv_analyzer 用途: 读取 CSV 文件并生成统计报告 适用场景: 用户要求分析 CSV 数据、统计销售数据、查看数据汇总时 输入: file_path (CSV 文件路径) 输出: JSON 格式的统计结果 def invoke_skill(skill_name: str, params: dict): 根据技能名称调用对应逻辑 if skill_name csv_analyzer: from skills.csv_analyzer.csv_analyzer import analyze_csv return analyze_csv(params.get(file_path, )) return {error: 未知技能} def run_agent(user_message: str): # 第一步让模型判断是否需要调用技能 response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: f你是技能路由助手。以下是可用技能\n{SKILL_DESCRIPTION}\n如果用户需求匹配某个技能请输出JSON格式的调用结果包含skill_name和params。如果不匹配直接回答用户。}, {role: user, content: user_message} ], response_format{type: json_object} ) content response.choices[0].message.content try: parsed json.loads(content) except json.JSONDecodeError: print(模型回复, content) return if skill_name in parsed: print(f调用技能{parsed[skill_name]}) result invoke_skill(parsed[skill_name], parsed.get(params, {})) # 第二步把技能结果反馈给模型生成最终回答 final_response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是数据分析助手请根据给定的统计数据生成简洁的中文报告。}, {role: user, content: f用户的问题是{user_message}\n技能执行结果是{json.dumps(result, ensure_asciiFalse)}} ] ) print(final_response.choices[0].message.content) else: print(模型回复, content) if __name__ __main__: run_agent(分析 data/sales_data.csv 文件告诉我总销售额和最好的月份)运行主程序python main.py预期效果是程序先调用模型判断用户意图模型识别出需要调用csv_analyzer随后执行 Python 代码完成统计最后把结果返回给模型生成中文报告。4.6 结果说明从上面的案例可以看到Agent Skills 的调用链路是用户提出需求模型根据 SKILL.md 中的描述判断该调用哪个技能框架执行技能代码得到结构化结果模型基于结构化结果生成最终自然语言回答。这样设计的好处是所有计算逻辑都在代码中完成模型只负责语义理解和结果润色大大降低了模型“算错数”的概率。5. 进阶技能组合、反思与多 Agent 协作5.1 多个 Skill 如何组合单个技能只是一个起点实际项目中往往需要多个技能协作。例如用户的完整需求是“分析销售数据然后画一个月度趋势折线图。”这个需求涉及两个技能csv_analyzer先分析数据得到月度汇总chart_generator根据月度汇总生成折线图。在 Agent Skills 的架构中模型会分步调用多个技能。这里的关键在于前一个技能的输出要能作为后一个技能的输入。为了支持这种组合建议让每个技能的输出保持结构化。如果csv_analyzer输出的 JSON 中包含monthly_summary字段chart_generator就可以直接读取这个字段生成图表。这种设计模式相当于把技能做成了“可插拔函数”通过数据契约进行组合。5.2 添加反思机制模型在调用技能时偶尔会出现误判。这时可以引入一个简单的反思循环模型先调用一个技能检查技能返回的结果是否符合预期如果不符合让模型重新判断或换一个技能。例如def run_agent_with_reflection(user_message: str, max_retries3): for attempt in range(max_retries): result invoke_skill_for(user_message) if is_result_valid(result): return generate_final_answer(user_message, result) user_message f上次结果不符合预期请重新分析{user_message}参考结果为{result} return 抱歉无法完成分析反思机制不是必须的但在技能较多、任务复杂的场景下能显著提高整体成功率。5.3 与多 Agent 框架的衔接Agent Skills 并不排斥现有的多 Agent 框架例如 AutoGen、LangGraph、CrewAI 等。它们的定位不同多 Agent 框架解决的是“多个 Agent 如何协作、如何编排”的问题Agent Skills 解决的是“单个 Agent 如何具备某项能力”的问题。所以你可以把 Agent Skills 当作一个模块嵌入到更大的 Agent 架构中。比如在 LangGraph 中一个节点专门负责路由任务给不同技能另一个节点负责执行技能并返回结果。这种组合方式在实际项目中非常常见。6. 常见问题与排查思路6.1 高频问题表问题现象常见原因解决思路模型没有调用技能直接回答问题SKILL.md 中的描述不够具体模型没意识到应该调用技能优化技能描述增加触发词和典型场景示例模型调用了错误的技能多个技能描述有重叠模型无法区分明确每个技能的不适用场景缩小技能边界技能执行时报错Python 代码依赖未安装或文件路径不对检查依赖使用绝对路径或相对于项目根目录的路径模型对技能结果解读错误技能输出的 JSON 结构不规则把输出改成固定字段并在 SKILL.md 中写明字段含义API 请求超时技能执行时间太长超过模型 API 的响应限制把耗时任务改成异步或分步执行模型在没有文件路径时也调用技能缺少输入参数校验在技能代码中检查必填参数缺失时返回明确的错误提示6.2 排查清单遇到 Agent Skills 不按预期工作按下面的顺序排查先单独测试技能代码不经过模型直接调用 Python 脚本确认代码本身没有问题。检查 SKILL.md 描述标注技能描述是否足够具体读者是否知道在什么场景下调用。查看模型返回的原始内容有时候模型不是没调用技能而是输出了错误格式的 JSON。确认参数传递是否正确模型输出的参数名要和技能代码中的参数名完全一致。打印日志在技能执行的入口和出口分别打印日志确认是哪一步出了问题。7. Agent Skills 的最佳实践与工程化建议7.1 编写高质量 SKILL.md 的原则写一份好的 SKILL.md比写代码更考验思考能力。结合吴恩达在课程中的讲解可以总结出几个关键原则。第一用场景定义技能而不是用功能定义技能。不好的写法是本技能用于 CSV 文件分析。好的写法是当用户提供 CSV 文件并询问销售总额、月度趋势、数据统计时使用本技能。目的就是让意图匹配更容易。第二要明确边界。描述里加上“不适用场景”能显著降低误调用率。第三示例优先。能在描述里给出一个输入输出示例模型的理解会好很多。## 示例 用户输入: 分析 data/sales_data.csv 的月度销售趋势 技能输出: {monthly_summary: {2025-01: 265432.0}}7.2 版本管理与依赖控制随着技能数量增加你一定会遇到版本问题某个技能更新后其他依赖它的技能行为发生了改变。建议每个 Skill 文件夹中都维护一个版本号例如在 SKILL.md 的 metadata 中加入--- name: csv_analyzer version: 1.2.0 last_updated: 2026-01-20 ---同时如果多个技能共用某些代码尽量抽成公共模块不要在每个技能里复制一份。7.3 安全与权限边界Agent Skills 的本质是让大模型具备执行代码的能力这天然带有安全风险。在实际生产环境中必须注意以下几点。最小权限原则技能代码运行的账号只应该有完成该任务所需的权限不要使用管理员或 root 权限。文件路径白名单不要让技能读取任意路径尤其是涉及服务器内部敏感文件时。输入校验用户的输入不可信技能代码必须自行校验参数类型、路径合法性、数据格式。日志脱敏技能执行过程中可能涉及用户敏感数据日志里要打码或只输出摘要不要明文输出完整数据。变更前备份凡是涉及数据库更新、文件覆盖、配置变更的测试在开发环境先验证生产环境操作必须备份并经过审批。这些内容在实验环境下可以简化但一旦进入企业级应用每一条都可能影响安全底线。7.4 测试与评估Agent Skills 的测试不能只测代码逻辑还要测“模型是否会正确调用技能”。推荐引入一个简单的评估集用户问题期望调用的技能期望输出内容分析这个 CSV 文件csv_analyzer统计 JSON把数据画成柱状图chart_generator图表文件帮我查一下数据库sql_queryer查询结果每次修改 SKILL.md 后跑一遍评估集观察模型调用技能的准确率。这是 Agent Skills 工程化中最重要的一步。8. 总结与学习路线这篇文章从 Agent 开发的痛点出发拆解了 Agent Skills 的核心概念并通过一个 CSV 分析实战案例完整演示了从技能设计、SKILL.md 编写、代码实现到模型路由的全流程。到这一步你应该掌握的关键能力包括理解 Agent Skills 与 Prompt、Workflow、Agent 的区别能独立编写一个 SKILL.md 描述文件能把一个具体任务封装成可复用的技能能通过自然语言接口实现技能路由和多技能组合能定位和解决 Agent Skills 调用过程中的常见问题。下一步可以考虑的方向是把一个现成的 Python 脚本改造成 Agent Skill在 LangChain 或 LangGraph 中整合自定义技能给技能加上评估集量化分析调用准确率学习吴恩达在 DeepLearning.AI 上关于 Agent 和提示词工程的公开课程建立更完整的认知体系。动手永远是学 AI 的最佳路径。建议你先拿手边的一个小脚本把它封装成一个技能然后看模型能不能在合适的时机调用它。这个过程跑通一次Agent Skills 对你来说就不再只是概念了。