Agent Skills 实战指南：从概念到工程落地，让大模型按需获取专项能力

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 是“一个能看菜谱、能拿菜包、能根据情况调整火候的厨师”。

这个比喻对后续理解很有帮助。

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 是让模型“会干活”。

三者并不互斥，实际项目中完全可以在一个 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 年推出的能力。它的核心逻辑是：

1. 开发者预先声明一组“函数”，包括函数名、参数说明和函数描述；
2. 用户输入问题后，模型不直接输出答案，而是输出“需要调用哪个函数，参数是什么”；
3. 开发者根据模型的输出，在本地执行真实函数；
4. 把执行结果返回给模型，模型再基于结果生成最终回答。

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_url="https://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( model="gpt-4o-mini", messages=[{"role": "user", "content": "北京今天天气怎么样？"}], tools=tools, tool_choice="auto" ) 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="", encoding="utf-8") as f: writer = csv.writer(f) writer.writerow(["date", "amount"]) for i in range(365): day = start_date + timedelta(days=i) 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.md

SKILL.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 的写法有几个要点：

1. 场景描述足够具体，模型能根据描述快速匹配用户意图；
2. 明确不适用场景，避免模型在需要其他技能时误调用；
3. 定义输入输出格式，让模型知道调用后能得到什么、需要返回什么；
4. 写清注意事项，提升模型在异常场景下的处理能力。

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", encoding="utf-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, key=monthly_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_ascii=False, indent=2))

单独运行测试：

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_url="https://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( model="gpt-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( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是数据分析助手，请根据给定的统计数据生成简洁的中文报告。"}, {"role": "user", "content": f"用户的问题是：{user_message}\n技能执行结果是：{json.dumps(result, ensure_ascii=False)}"} ] ) 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 的调用链路是：

1. 用户提出需求；
2. 模型根据 SKILL.md 中的描述判断该调用哪个技能；
3. 框架执行技能代码，得到结构化结果；
4. 模型基于结构化结果生成最终自然语言回答。

这样设计的好处是：所有计算逻辑都在代码中完成，模型只负责语义理解和结果润色，大大降低了模型“算错数”的概率。

5. 进阶：技能组合、反思与多 Agent 协作

5.1 多个 Skill 如何组合

单个技能只是一个起点，实际项目中往往需要多个技能协作。

例如，用户的完整需求是：“分析销售数据，然后画一个月度趋势折线图。”

这个需求涉及两个技能：

• csv_analyzer：先分析数据，得到月度汇总；
• chart_generator：根据月度汇总生成折线图。

在 Agent Skills 的架构中，模型会分步调用多个技能。这里的关键在于：前一个技能的输出，要能作为后一个技能的输入。

为了支持这种组合，建议让每个技能的输出保持结构化。如果csv_analyzer输出的 JSON 中包含monthly_summary字段，chart_generator就可以直接读取这个字段生成图表。

这种设计模式相当于把技能做成了“可插拔函数”，通过数据契约进行组合。

5.2 添加反思机制

模型在调用技能时，偶尔会出现误判。这时可以引入一个简单的反思循环：

1. 模型先调用一个技能；
2. 检查技能返回的结果是否符合预期；
3. 如果不符合，让模型重新判断或换一个技能。

例如：

def run_agent_with_reflection(user_message: str, max_retries=3): 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 高频问题表

6.2 排查清单

遇到 Agent Skills 不按预期工作，按下面的顺序排查：

1. 先单独测试技能代码：不经过模型，直接调用 Python 脚本，确认代码本身没有问题。
2. 检查 SKILL.md 描述：标注技能描述是否足够具体，读者是否知道在什么场景下调用。
3. 查看模型返回的原始内容：有时候模型不是没调用技能，而是输出了错误格式的 JSON。
4. 确认参数传递是否正确：模型输出的参数名要和技能代码中的参数名完全一致。
5. 打印日志：在技能执行的入口和出口分别打印日志，确认是哪一步出了问题。

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 的测试不能只测代码逻辑，还要测“模型是否会正确调用技能”。

推荐引入一个简单的评估集：

每次修改 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 对你来说就不再只是概念了。