先说一个可能让不少人意外的事实：2025 年真正让 Agent 开发往前迈一大步的，不是某个新模型，也不是更长的上下文窗口，而是一套看起来有点“朴实”的规范——Agent Skills。
吴恩达的 Agent Skills 教程出来后，很多人才意识到，过去几个月里我们折腾提示词、调试工具调用、反复跟模型解释“你是一个擅长处理 Excel 的助手”，走了多少弯路。我自己的体感也是如此：Agent 的能力上限，很多时候不是被模型决定的，而是被我们给它准备的“工作手册”决定的。这篇就围绕 Agent Skills，从概念到代码，从单次跑通到工程化落地，把整套东西讲透。
1. 先搞清楚 Agent Skills 到底解决了什么
很多人第一次看到 Agent Skills，第一反应是：这不就是把提示词拆成几个文件吗？跟 system prompt 有什么区别？跟 MCP 又是什么关系？如果带着这个疑问去读教程，很容易只学了个目录结构，却理解不了它真正改变的东西。
1.1 提示词是“说明书”，Agent Skills 是“新员工培训包”
传统方式里，你想让 Agent 完成一类任务，通常会在 system prompt 里写上一大段描述：你是数据分析师，你要处理 CSV，你要注意编码，你要先看前几行再决定策略……这种方式不是不行，但它有三个很明显的毛病。
第一个问题是耦合。所有任务描述、工具说明、输出要求全塞在一个 prompt 里，一旦任务变多，prompt 会越来越长，模型注意力会被稀释，关键指令反而容易被忽略。第二个问题是不可复用。你这次写了一段“处理 CSV 的专家提示词”，下次另一个项目想用，只能复制粘贴，还得手工修改里面的路径和细节。第三个问题是最隐蔽的——提示词只是文字，它没有配套的执行脚本、校验逻辑、示例文件和失败处理。模型“知道”该怎么做，和“真的能”把一件事做对，中间还差着一整套工程支撑。
Agent Skills 的思路是把“技能的说明书”和“技能的执行工具”打包在一起。一个 Skill 不只是告诉模型“你应该怎么做”，还提供了脚本、模板、示例、校验规则，模型可以在需要时按目录去查找和调用。这就像你给新员工的不再是一张写满职责的纸条，而是一套带操作手册、工具包、样例和检查清单的入职培训包。
1.2 和 MCP 不是替代关系，而是分工不同
讨论 Agent Skills 时绕不开 MCP。很多人误以为两者是竞争关系，实际落地中它们更像不同层级的分工。
MCP 解决的是“Agent 如何调用外部工具和数据源”的连接问题。它是一套标准协议，让模型可以访问数据库、文件系统、API、浏览器之类的资源。Agent Skills 解决的是“Agent 如何高质量完成一类任务”的方法问题。它侧重的不是连接，而是任务执行过程中的策略、步骤、约束和工具配套。
放在工程视角里，MCP 更像是给 Agent 接上了手和眼睛，Skills 更像是给 Agent 装上了一套“肌肉记忆”。一个技能内部完全可以调用 MCP 提供的工具，两者不冲突。理解了这层关系，你就知道为什么很多项目里它们是同时存在的。
1.3 真正有价值的是“可复用的工作流封装”
如果只把 Agent Skills 理解成“更规范的提示词管理”，还是低估了它。它真正有价值的地方，是把一次性的任务处理，升级成了可复用、可分发、可版本管理的工作流单元。
打个比方。以前让 Agent 处理 Excel 报表，你需要每次重新描述任务，每次都要提醒它注意合并单元格、注意空值、注意日期格式。有了 Skill 之后，你把这些规则、脚本和样例打包成一个技能目录，以后不管哪个项目、哪次对话，只要告诉 Agent “使用 excel_report_skill”，它就会自动去加载相应目录里的说明和工具，按照预先定义的流程执行。
这个变化看起来只是工程上的整理，但它带来了两个深层影响。第一，任务执行的稳定性大幅提升，因为关键步骤被固化了，不再依赖模型的临场发挥。第二，技能可以跨项目复用和迭代，你改进一次技能，所有使用它的场景同时受益。这才是 Agent 开发真正走向工程化的一个信号。
2. 从目录结构到最小实战：手把手写一个 Skill
理解了概念之后，最该做的事情就是动手。我见过太多人学完理论之后卡在第一步：不知道一个 Skill 文件系统到底长什么样，不知道模型是怎么找到并使用这些技能的。下面用一个非常具体的例子，带你从零搭一个可用技能。
2.1 官方规范里的技能目录到底怎么组织
不同平台的 Agent Skills 目录规范会有些差异，但整体的设计思路大体一致。以目前传播较广的 Anthropic Claude Skills 规范为例，一个技能通常是一个独立目录，里面包含说明文件和配套资源：
excel-report-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze_excel.py │ └── generate_report.py ├── assets/ │ ├── sample_input.xlsx │ ├── sample_output.md │ └── rules.json └── references/ ├── title_format.md └── error_handling.md核心文件是SKILL.md，它相当于这份技能的说明书。模型在决定是否使用某技能时，会先阅读这个文件，然后根据里面的指引决定下一步行动。scripts目录存放可执行脚本，assets目录放示例和数据文件，references目录放补充参考文档。
注意：目录名称和文件名都不是随便取的。模型是靠文件路径和命名来理解技能结构的，所以目录名要语义化，尽量用英文小写加连字符，避免空格和中文路径。
2.2 SKILL.md 的写作质量，直接决定技能上限
SKILL.md是技能的大脑，它的写作质量直接决定 Agent 能不能正确使用这个技能。根据社区实践和 Anthropic 官方指引，一份合格的SKILL.md至少包含以下核心结构：
--- name: excel-report-skill description: 分析 Excel 数据并生成结构化报告。当用户需要处理 XLSX 表格、统计报表、数据汇总时使用。 --- # Excel 报表分析技能 ## 适用场景 - 用户提供 `.xlsx` 或 `.csv` 文件 - 需要对表格数据进行清洗、统计和汇总 - 需要输出 Markdown 或 HTML 格式的分析报告 ## 处理流程 1. 先确认文件存在且格式正确 2. 调用 scripts/analyze_excel.py 读取数据概览 3. 检查缺失值和异常值 4. 生成统计摘要 5. 按 requirements 输出最终报告 ## 使用约束 - 输入文件必须是 xlsx 或 csv - 输出报告使用中文 - 不要在未确认数据质量前直接输出结论 ## 常用脚本 - analyze_excel.py: 读取表格并输出字段统计 - generate_report.py: 根据分析结果生成 Markdown 报告很多初学者会把description写得很模糊，比如“处理 Excel”。这样写的后果是模型不知道该在什么时候调用这个技能。更好的写法是明确触发条件、输入类型、任务类型，甚至可以写上“当用户说‘分析一下这个表格’‘统计一下数据’时优先使用”。
2.3 一个能跑通的 Python Skill 实战
理论说了这么多，不如直接来看一个能运行的技能示例。下面的例子是一个可以把 JSON 数据转成 CSV 的技能，逻辑虽然简单，但完整呈现了一个技能的各个组成部分。
先看SKILL.md的设计：
--- name: json2csv-skill description: 将 JSON 数据文件转换为 CSV 格式。当用户需要把 JSON 转为表格、导入 Excel、处理数据导出时使用。 --- # JSON 转 CSV 技能 ## 前置条件 - 输入必须是有效的 JSON 文件或 JSON 字符串 - 如果 JSON 是嵌套结构，先压平再转换 ## 执行步骤 1. 读取 JSON 文件 2. 检查是否为数组类型 3. 调用 scripts/json2csv.py 执行转换 4. 检查生成的 CSV 文件 5. 返回文件路径 ## 输出要求 - CSV 使用 UTF-8 编码 - 第一行为字段名 - 内容包含中文时不要使用 Excel 默认的 ANSI 编码然后是配套的转换脚本：
# scripts/json2csv.py import json import csv import sys from pathlib import Path def flatten_json(data, prefix=""): """将嵌套 JSON 压平成单层结构""" items = {} for key, value in data.items(): new_key = f"{prefix}.{key}" if prefix else key if isinstance(value, dict): items.update(flatten_json(value, new_key)) else: items[new_key] = value return items def convert(input_path, output_path): with open(input_path, "r", encoding="utf-8") as f: data = json.load(f) if isinstance(data, list): rows = [flatten_json(item) for item in data] elif isinstance(data, dict): rows = [flatten_json(data)] else: raise ValueError("输入 JSON 必须是对象或数组") fieldnames = list(dict.fromkeys(k for row in rows for k in row.keys())) with open(output_path, "w", encoding="utf-8-sig", newline="") as f: writer = csv.DictWriter(f, fieldnames=fieldnames) writer.writeheader() writer.writerows(rows) print(f"转换完成: {output_path}") if __name__ == "__main__": input_file = sys.argv[1] output_file = sys.argv[2] convert(input_file, output_file)这个脚本本身不难，但它体现了 Skill 工程中一个关键理念：能写成代码的规则，就不要只写在提示词里。比如“输出 UTF-8 编码”这条要求，如果靠提示词约束，模型可能哪天就忘了；但写进脚本之后，无论模型怎么调用，输出的编码都是固定的。
2.4 最小验证流程：先跑通，再谈优化
技能写完之后，不要急着把它丢进复杂的 Agent 项目里，先做最小验证。我常用的验证流程是：
- 准备一个小的测试输入文件，比如 10 行 JSON 数据。
- 直接命令行运行脚本，确认脚本本身没有 bug。
- 把技能目录放到 Agent 能扫描到的技能文件夹里。
- 用一句自然语言指令测试：“帮我把 data.json 转成 CSV”。
- 检查输出文件的编码、字段顺序、特殊字符是否正常。
只有这个过程跑通了，才能说明你的技能确实可以被模型正确识别和调用。如果这一步没通过，问题大概率不在脚本，而在SKILL.md的描述不够清晰，模型没有正确理解技能的使用条件。
3. 从入门到实战，你需要躲开的五个坑
在真正用过一段时间之后，我对 Agent Skills 的感触更复杂了一些。它确实好用，但远远不是“写个目录结构就能万事大吉”的东西。下面这几个坑，几乎每个进入实战阶段的人都会遇到。
3.1 描述写得太抽象，模型根本不知道什么时候该用
这是最普遍的问题。很多人在description里写“提供数据转换能力”，但模型面对一个真实任务时，根本无法把“数据转换”和用户的“帮我导一下表格”关联起来。
解决策略是：写下至少三个具体触发场景。比如“当用户提到导出 Excel、把数据整理成表格、处理 CSV 文件时使用”。给你的 Skill 一个越清晰的触发边界，模型就越容易在正确的时机调用它。
3.2 把太多逻辑塞进提示词，而不是代码里
新手写 Skill 时，最容易犯的错误就是把所有步骤都写在SKILL.md里，让模型“自己看着办”。比如你写“转换时要注意处理嵌套结构、注意空值、注意编码”，模型可能会做，但结果不稳定。
更可靠的做法是：把能确定性执行的逻辑写进脚本，让代码来保证正确率。提示词只负责决策层面的事情——判断该不该用这个技能、用哪个脚本、怎么解读结果。规则越靠近代码，执行越稳定。
3.3 忽略技能执行的“幂等性”
幂等性这个概念听起来很工程化，但它对 Agent Skills 非常关键。简单说，同一个输入，你跑一次和跑十次，应该得到一致的结果。如果脚本依赖外部环境状态（比如某个临时文件、某个全局变量、或某个顺序），就可能在重复执行时出现问题。
写技能脚本时，尽量保证它是无状态的。所有的中间结果都写到明确指定的临时目录，每次执行都重新读取原始输入，不要依赖上一次运行的残留文件。
3.4 不考虑脚本报错后模型怎么恢复
你在本地测试脚本时一切正常，但到了 Agent 环境里，可能因为路径不对、权限不够、依赖缺失等各种原因报错。这时候模型会怎么处理？它可能会反复重试同一个错误，也可能胡编一个成功结果。
好的 Skill 设计要在SKILL.md里明确写出错误处理方式：
- 脚本返回非零退出码时，先查看 stderr 输出。
- 根据错误类型决定是修正输入还是放弃任务。
- 不得伪造成功输出。
- 实在无法解决时，明确告诉用户失败原因。
3.5 完全照搬网上的技能，不根据自己的场景修剪
网上已经有不少 Skill 模板和仓库，直接拿过来用很方便，但很少有完全贴合你场景的现成技能。文本处理的技能可能需要调整输出语言，数据类技能可能需要修改日期格式，代码生成类技能可能需要定制代码风格。
我的建议是：先找一个场景最接近的模板跑通，然后按自己的需求把脚本和描述逐步改掉，直到它真正变成“你的技能”。这个过程中你会更清楚每一步是干什么的，后续调优也不至于一头雾水。
4. 进阶：从单技能到技能体系，Agent 开发的分水岭
跑通单个技能之后，很多人会进入一个兴奋期：写了好几个技能，感觉 Agent 什么都能干了。但用一段时间后会发现，技能变多了以后，管理复杂度快速上升，甚至模型会不知道该选哪个技能。这里才是 Agent Skills 真正考验工程能力的地方。
4.1 技能要独立自治，但也要能协作
单个技能最好只负责一个职责域，不要做“万能技能”。比如你可以有excel-report-skill、json2csv-skill、log-analyzer-skill、code-review-skill，每个技能之间保持独立。
但真实任务往往是跨域的。用户可能先让你分析 Excel，再让你把分析结果转成 CSV，最后还要生成一个 Markdown 报告。这时就需要技能之间能协作。实现协作的方式有两种：
- 一种是在
SKILL.md里声明“本技能处理完成后，可调用 json2csv-skill 导出结果”。 - 另一种是模型根据上下文自行串联多个技能，这要求每个技能的
description写得足够清晰，让模型知道什么时候该切换。
从工程角度看，前者更可靠，后者更灵活。实际项目里两者都会用到。
4.2 技能版本管理和回归测试
代码要版本管理，技能同样需要。尤其当你开始团队协作时，如果没有版本管理，很难知道某个技能的行为变化是哪个版本引入的。
推荐的做法是：把每个技能目录放进独立的 Git 仓库，或者至少在一个 monorepo 里按目录隔离。每次修改技能后更新SKILL.md里的版本号，并记录 changelog。如果技能包含脚本，还应该配套一份简单的回归测试，至少覆盖最常见的输入情况。
回归测试的思路很简单：把固定的样本输入和预期输出保存下来，每次改动技能后跑一遍，确保原有功能没被破坏。这个步骤在你不断迭代技能时会节省大量时间。
4.3 从“技能集合”到“技能编排”
当技能数量上了两位数，更高级的用法是引入编排层。编排层可以是一段工作流代码，也可以是一个专门负责“路由器”的 Agent，它根据用户请求决定调用哪个技能，以及技能之间的先后顺序。
这个阶段，Agent 开发的性质已经变了。你不再写“怎么让模型把一件事做对”，而是写“怎么让多个技能在正确的时间被正确触发”。这件事做得好，整个系统的能力边界就不是由单次调用的质量决定的，而是由技能库的覆盖面决定的。
4.4 技能执行日志与可观测性
最后一块拼图是日志。没有日志的 Agent 系统，出了问题几乎没法排查。每个技能执行时至少要记录以下几类信息：
- 触发条件：模型为什么选择了这个技能。
- 输入摘要：输入文件或关键参数。
- 执行结果：成功还是失败，输出文件路径。
- 耗时和资源占用：判断是否有性能问题。
有了日志之后，你才能回答那个最让人头疼的问题：“为什么刚才那次任务输出结果不对？”没有日志，你只能靠猜；有了日志，你能定位到具体是哪个技能、哪一步、处理了哪个输入时出了问题。
5. 常见问题排查：按这个顺序找问题，别瞎试
不管技能写得多好，实际运行时总会遇到问题。下面是我总结的一套排查链路，按顺序走，大多数问题都能定位到根因。
5.1 先看技能有没有被触发
碰到 Agent 没有按预期使用某个技能时，第一件事不是检查脚本，而是确认技能有没有被激活。
需要检查的地方：
SKILL.md的description是否覆盖了用户的实际表述。- 技能目录是否在 Agent 配置的扫描范围内。
- 技能文件是否有读取权限。
- 模型平台是否有开启技能功能。
如果用户说“帮我把这个数据导出来”，而你的技能描述里只有“处理 CSV”，模型没触发它非常正常。这种情况不需要改代码，只要补充触发场景描述即可。
5.2 再确认输入真的没问题
技能被触发后，如果输出异常，优先检查输入。常见问题包括：
- 文件路径包含中文或空格，导致脚本读取失败。
- 输入编码不是 UTF-8，读取后出现乱码。
- 数据结构跟
SKILL.md里描述的假设不一致。 - 数据量过大，脚本长时间未响应。
这一步的核心思想是：先确认输入边界，再怀疑代码逻辑。很多脚本本身没有 bug，是输入不符合预期才出了问题。
5.3 然后查环境和依赖
如果输入正常但脚本报错，下一个排查重点是环境差异。本地跑得好好的，换到 Agent 环境就挂了，原因通常出在：
- Python 或 Node.js 版本不一致。
- 第三方依赖没安装。
- 环境变量缺失。
- 脚本权限不可执行。
- 网络受限，脚本需要访问 API 或下载资源。
打日志是最好的排查方式。在你怀疑的每一步加上输出，看程序实际走到了哪里。
5.4 最后才考虑模型对技能的使用策略
如果脚本和输入都没问题，但输出还是不对，问题可能出在模型对技能的使用策略上。比如模型只读了SKILL.md，却没有实际调用脚本，全靠“想象”生成结果。
这种情况通常没办法靠改脚本解决，你需要调整SKILL.md的措辞，增加更明确的强制约束：
## 强制要求 - 必须执行 scripts/ 目录下的脚本，不得仅凭描述猜测输出。 - 脚本执行失败时，必须报告错误信息，不得伪造结果。模型的行为模式，很多时候是被说明文档的表达方式塑造的。你写得越像“硬性规定”，它就越不会跳步。
5.5 验证修复是否真的生效
每次修复后，不要只测一次就完事。至少用三个不同的输入去验证，包括正常输入、边界输入和异常输入。如果三个场景都能正确处理，才算真正修好了。
如果这条排查链路走完，问题仍然存在，大概率是技能本身的设计跟任务类型不匹配。这时候不是继续打补丁，而是回到第一步，重新审视这个技能到底该不该存在、边界该画在哪里。
6. 什么场景该用 Agent Skills，什么场景不该用
Agent Skills 不是一个万能药。它适合很多场景，但也有明显不适用的情况。搞清楚边界，比你多写十个技能更有价值。
6.1 更适合用技能封装的场景
我实际使用下来，适合技能封装的场景有三个特征：任务流程相对固定、有确定性操作可以沉淀、会被重复使用。
典型例子：
- 数据处理类任务。CSV、Excel、JSON 之间的格式转换，数据清洗，字段统计。
- 文档生成类任务。按固定模板生成周报、日报、会议纪要。
- 代码处理类任务。代码规范检查、单元测试生成、依赖分析。
- 日志分析类任务。读取日志文件、提取错误信息、生成摘要。
这些任务的共同点是“路径明确”。你把流程固化进技能后，Agent 只需要按部就班执行，稳定性会非常高。
6.2 不建议硬套技能的场景
反过来，如果任务本身高度开放、需要多轮探索、依赖大量临时判断，就不太适合硬塞进技能里。强行封装的结果往往是技能里的规则写得很泛，模型反而被约束得发挥不好。
不太适合的典型场景：
- 开放式头脑风暴或文案创意生成。这类任务需要发散，不太依赖固定步骤。
- 需要大量个性化互动的任务。每个用户的需求差异太大，写进技能的描述和脚本很快就会过时。
- 需要实时联网查询且行为路径无法预测的任务。此时更应该用 MCP 工具或普通对话，而不是技能封装。
一个简单的判断标准是：如果你发现自己为了写一个技能，要把所有可能的例外情况都列一遍，那大概率这个场景不适合技能化。
6.3 从学习到生产，建议按这个路径走
如果读者朋友想系统掌握 Agent Skills，我不建议直接去啃大项目源码，更推荐按下面这个路径循序渐进：
- 照抄一个官方示例技能，原样跑通。
- 修改它的描述和参数，让它适配你手头的小任务。
- 从零写一个自己的技能，涵盖说明文档、脚本和示例。
- 把三到五个技能放进同一个 Agent 项目，观察模型如何选择与串联。
- 补上日志、版本管理、回归测试，把技能体系工程化。
走到第四步，你已经超过了绝大多数停留在“概念了解”层面的人。走到第五步，你就具备了把 Agent Skills 落地到真实生产环境的能力。
7. 真正的分水岭：不是“会用”，而是“会设计”
聊到这里，应该能得出一个更完整的判断了。Agent Skills 的入门门槛真的不高，看懂目录结构、写一个简单脚本，一个下午就能学会。但这门技术的真正难点，从来不在“怎么写”，而在“怎么设计”。
设计一个技能，你需要想清楚：这个任务的关键路径是什么？哪些环节必须由确定性代码保证？哪些环节需要模型自主判断？触发边界画在哪里？错误情况下应该怎么兜底？这些问题没有标准答案，只能靠具体场景和持续迭代去回答。
我和一些开发者交流下来，发现一个共识：Agent Skills 把关注点从“模型能做什么”转移到了“我们希望 Agent 以多高的确定性完成什么”。这种思维转变，其实是把 Agent 从一个“聪明但随机”的对话工具，变成一套“有流程、有约束、有质量保障”的工程系统。这才是 Agent Skills 真正的意义。
如果你现在正准备入坑，我的建议很简单：不要停留在看教程的阶段，挑一个你平时最常让 Agent 干的重复性任务，把它做成一 个技能，放到真实项目里跑一周。这一周里你会遇到各种问题，但每解决一个，你理解的深度就会上一个台阶。
所有关于 Agent 的宏大叙事，最后都要落到一件具体任务的稳定执行上。
