各位读者朋友大家好。最近 AI Agent 相关的概念越来越密集尤其是 “Agent Skills”这个词在技术社区和招聘 JD 里出现频率明显上升。但很多刚接触的朋友会困惑它和 Tools、Function Call 有什么区别是新的框架吗需要写很复杂的代码吗这篇文章准备用尽量易懂的方式把 Agent Skills 从“概念”到“使用”再到“自己造一个”的完整过程拆开讲清楚。不需要你有非常深的机器学习基础只要会一点 Python能看懂 JSON 或 YAML跟着动手半小时就能跑通一个属于自己的 Skill。如果你想在简历上增加一项有含金量的 AI 工程能力或者想给现有 Agent 应用增加可复用能力这篇内容会很有帮助。我们先把目标定小一点理解核心概念掌握调用方式学会编写和注册一个自定义 Skill最后形成一个“会用到会造”的正向闭环。1. Agent Skills 到底是什么1.1 一句话理解 Agent Skills简单来说Agent Skills 就是给 AI Agent 预先准备的一组“可复用能力包”。这里的“能力”可以是某个领域的专业知识、一套操作流程、一段可执行工具代码、一组提示词模板也可以是一个结构化的技能描述文件。在早期的 Agent 开发中我们把能力拆成一个个独立的 Tool比如“查询天气”“发送邮件”“查询数据库”。Agent 需要的时候会通过工具调用去触发这些功能。这当然可行但存在一个明显问题工具之间是孤立的缺少上下文关联每次都需要在 Prompt 里写得非常详细Agent 才能知道什么场景该用哪个工具。Agent Skills 的做法是把更完整、更结构化的能力打包起来。一个 Skill 里面既包含“这个技能是干什么的”也包含“怎么用”“有什么限制”“需要什么参数”“有哪些步骤”。Agent 可以在运行过程中动态发现、加载并调用这些技能而不是每次都在系统提示词里手动塞一堆指令。1.2 它解决的核心痛点在没有 Agent Skills 之前大家做 Agent 应用时经常遇到三类麻烦第一系统提示词越来越长。一个复杂的 Agent 可能涉及十几个工具每个工具的描述、参数、注意事项都塞进 Prompt 里Token 成本高而且模型对关键信息的注意力会被稀释。第二能力复用很难。你在一个项目里写好了“PDF 报告分析”的能力换一个项目要么复制粘贴要么重新实现一遍维护成本极高。第三模型“知道但做不到”。大模型本身知道很多知识但在具体执行时需要非常精确的步骤和工具配合。如果没有结构化的技能指导模型容易凭借“记忆”自由发挥输出结果不稳定。Agent Skills 通过独立的技能文件把“知识、流程、工具、限制条件”打包起来让 Agent 在需要时动态调用。这样系统提示词保持精简能力可以跨项目复用模型执行时也有更明确的规范可循。1.3 Agent Skills 和 Tools、Workflows 的区别很多初学者容易把 Agent Skills、Tools、Workflows 混为一谈这里做一个简单对比。概念核心特点典型例子类比理解Tools单个可执行动作没有复杂流程搜索、发邮件、获取天气一把螺丝刀Workflows固定流程由开发者预先编排好数据清洗流水线、审批流程一条流水线Agent Skills可复用能力包包含描述、步骤、代码、约束从 PDF 提取结构化数据、对销售数据做归因分析一套工具箱 说明书Tools 强调的是“动作”Workflows 强调的是“流程”Agent Skills 强调的是“能力包”。一个 Skill 内部可以包含多个步骤也可以调用多个工具甚至还能嵌套其他 Skill。这种设计让 Agent 从“会调用工具”进化到“掌握专业技能”意义是不一样的。Tools 解决问题的粒度更小而 Agent Skills 更像是为某一类任务准备的标准化解决方案。2. Agent Skills 的典型应用场景2.1 企业知识库与文档处理场景这是目前落地最多的一类场景。企业积累了海量 PDF、Word、PPT 文档过去靠人工阅读整理效率太低靠普通聊天机器人又经常答非所问。基于 Agent Skills可以设计一个“文档深度解析”技能包。它包含文档格式识别、目录抽取、关键段落定位、摘要生成、重点信息抽取等多个环节。Agent 接收到用户指令后自动加载这个技能按照内置流程逐步处理文档最后输出结构化结果。相比传统 RAG检索增强生成方案Skill 的优势在于可以把“解析—抽取—归档”的完整工作流固化下来并且根据文档类型自动调整策略而不是简单地做一次向量检索。2.2 数据分析与报表生成数据分析类任务非常适合用 Agent Skills 来实现。举一个实际业务场景运营同学想快速看一下上周各渠道的投放效果并生成一份周报。一个“投放数据分析”技能可以包含以下内容数据源读取规则、核心指标口径定义如 ROI、转化率、获客成本、常见的对比分析方法、图表生成规范、报告输出模板。Agent 加载这个技能后能自动完成从取数、清洗、分析到报告生成的完整流程而且每次输出的口径保持一致。这种场景下Agent 不只是会调用 SQL 工具而是真正“懂”数据分析和报告规范这背后就是 Skill 在起作用。2.3 代码生成与工程辅助在软件开发场景中Agent Skills 也能发挥很大的作用。比如把一个团队的代码规范、目录结构、接口设计原则、常用开发框架的注意事项打包成一个“项目开发助手”技能。新成员加入项目时Agent 可以基于这个技能快速生成符合团队规范的代码骨架老成员写代码时Agent 也能按照技能要求进行代码审查指出不符合项目规范的地方。有意思的是这个场景已经超出了传统的“自动补全代码”范畴更接近“按照团队标准生产代码”。如果你负责团队的基础设施建设这种思路值得尝试。2.4 人文社科研究辅助的延伸最近有讨论提到“Agent Skills 赋能人文社科混合研究方法论文写作”这个方向很值得关注。人文社科研究中有大量工作涉及文献综述、资料爬梳、混合研究方法设计、问卷整理、访谈编码、内容分析等。传统方法是靠研究者手动完成耗时且容易遗漏。如果用 Agent Skills 来支撑可以让 Agent 掌握“文献检索与分析”“访谈文本编码”“内容分析框架应用”等技能帮研究者做前期的资料整理和分析工作。需要强调Agent 是辅助工具不能替代研究者的独立思考、理论框架构建和学术判断。但合理使用 Agent Skills确实能显著减轻机械性劳动的负担让研究者把更多精力放在核心问题上。3. 环境准备与平台选择3.1 先选一个能跑通的环境学习 Agent Skills最重要的一步是有一个可以实际运行的环境。市面上支持 Agent Skills 的平台和框架越来越多Anthropic 的 Claude 生态、各类开源 Agent 框架以及某些低代码平台都开始支持类似概念。这里不强制要求你使用某一家产品。我的建议是如果你平时已经在用某个 Agent 开发框架优先选择当前框架支持的技能扩展机制如果你是从零开始可以先从支持 Skill 格式的开源框架入手。文中示例采用“通用技能包格式 核心脚本”的方式呈现重点演示思路不绑定特定平台。你在实际落地时按所使用的框架文档调整文件结构和配置格式即可。3.2 开发环境准备虽然每个平台对 Skill 的具体实现不同但大部分都需要一个基础开发环境。建议准备以下内容Python 3.9 或更高版本用于编写技能脚本和执行本地测试。一个支持 Markdown 和 YAML 的编辑器VS Code 足够。你有权限访问的 Agent 运行环境可以是本地启动的服务也可以是某个云端平台。Git 用于版本管理方便回滚技能文件的修改记录。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3.3 示例项目结构一个典型的 Agent Skills 项目目录结构大致如下agent-skills-tutorial/ ├── skills/ │ ├── csv-analyzer/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── analyze_csv.py │ └── meeting-summarizer/ │ ├── SKILL.md │ └── scripts/ │ └── summarize.py ├── agent-config/ │ └── agent.yaml └── README.mdskills目录下每个子目录就是一个独立技能。每个技能目录里包含一个SKILL.md描述文件以及相关的脚本和资源。这样的结构清晰、可维护也方便后续扩展。4. 会用的第一步理解 Skill 的组成与加载机制4.1 SKILL.md 是什么SKILL.md是 Agent Skills 的核心元数据文件也可以理解为技能的“说明书”。它描述了这个技能是做什么的、什么场景下使用、如何使用、有哪些注意事项。以 Claude Agent Skills 的格式为例一个SKILL.md通常包含两部分YAML 格式的 frontmatter元信息区和 Markdown 格式的正文使用说明区。下面是一个简化的结构--- name: csv_analyzer description: 分析 CSV 数据文件生成统计摘要和分布情况。 --- # CSV 数据分析技能 ## 适用场景 适用于用户提供 CSV 文件需要了解数据概况、统计特征、异常值等场景。 ## 工作流程 1. 读取 CSV 文件识别表头和数据类型。 2. 计算数值列的基本统计量均值、中位数、标准差等。 3. 检查缺失值和异常值。 4. 输出分析报告。 ## 注意事项 - 仅支持 UTF-8 编码的 CSV 文件。 - 大文件超过 100MB需要分块处理。 - 不修改原始数据文件分析结果单独输出。这段内容看起来很简单但它直接决定了 Agent 什么时候会使用这个技能、以及怎么使用。描述写得越清晰Agent 的调用准确率就越高。4.2 Agent 如何发现和调用 Skill很多平台的 Agent 会在每次对话开始时根据用户请求和当前上下文动态决定是否需要加载某个技能。它并不是把全部技能都塞进上下文而是先读取技能清单通常包含技能名称和一句话描述再选择最匹配的技能加载详细内容。可以理解为清单是“技能索引”SKILL.md是“详细操作手册”。Agent 先查索引再决定要不要看手册。这种机制的好处是省 Token效率高而且技能数量可以做得很大不用担心中文上下文过长影响效果。缺点也有如果技能描述写得不准确Agent 可能错过匹配或者加载了错误技能。所以编写技能描述时要把关键触发词、适用场景写得尽量准确。4.3 调用参数与返回结果Skill 在被调用时通常会接收一些输入参数。这些参数可以是用户请求中包含的信息也可以是 Agent 在执行过程中生成的信息。继续以csv_analyzer为例可能的输入参数包括file_pathCSV 文件路径。analysis_type分析类型取值为summary、distribution、outlier等。输出的结果建议遵循统一的结构例如{ status: success, file_name: sales_data.csv, row_count: 1520, column_count: 8, summary: { total_revenue: 152000.5, avg_order_value: 100.0, max_order_value: 500.0 }, missing_values: { customer_name: 3 } }统一输出格式带来的好处非常实际。第一Agent 可以稳定解析结果并生成后续回答第二多个技能串联时上下游数据结构能对齐第三日志和排错更直观。5. 深入理解 Skill 的核心机制5.1 Skill 描述是调用准确率的关键很多刚开始写技能的朋友会忽略一个细节真正决定技能有没有用的很多时候不是脚本多复杂而是description写得好不好。大模型在判断调用哪个技能时主要依赖技能描述与当前任务的语义匹配程度。如果描述含糊比如只写“处理数据”Agent 就不知道它到底能处理什么数据、适合什么场景。建议描述中包含这些要素技能的目标任务。输入数据的类型和格式。输出结果的形式。典型的触发场景。下面做一组对比。模糊描述description: 分析数据。清晰描述description: 分析 CSV 格式的销售数据返回总销售额、订单数、平均订单金额等统计指标。当用户提到销售报表、订单明细、业绩汇总时使用该技能。后者的触发准确率显然会高很多。5.2 Skill 内部的步骤拆解一个专业的 Skill 不是一句话就能说清的它内部应该有流程。这些流程可以指导 Agent 按步骤执行避免跳步或遗漏关键环节。例如一个“PDF 发票信息抽取”技能内部流程可能是识别 PDF 文件格式和页数。提取文本内容。根据发票版式定位关键字段发票号码、税额、金额、购买方。校验字段完整性。输出 JSON 结构的数据。每一步都清晰罗列后Agent 执行起来就有章法。即使中间某一步失败也能准确定位到是哪一环节出了问题。这里需要提醒Agent 本质上仍然是概率模型即使有明确步骤也可能出现偏差。因此技能步骤设计得越具体、越可验证越好。如果是需要精确计算的任务建议把计算逻辑封装在代码脚本里而不是让模型在对话里手算。5.3 代码脚本与 Prompt 的分工在 Agent Skills 中代码脚本和 Prompt 各有分工。代码脚本负责精确、可重复的执行逻辑比如文件解析、数据计算、 API 调用、结果格式化。Prompt/文档负责指导模型理解任务背景、决策分支、质量标准和注意事项。举个例子在“CSV 分析”技能中读取文件、统计计算交给 Python 脚本处理这部分不能容忍幻觉而“根据统计结果给出一段业务解读”则交给模型完成这部分适合发挥大模型的总结和推理能力。把两者分开既能保证准确性又能保留模型的理解能力。这也是 Agent Skills 设计上比较聪明的一点。5.4 版本管理与依赖隔离随着技能数量增加版本管理会成为实际问题。每个 Skill 建议独立管理版本号记录变更内容。一个技能的内部脚本如果引用了第三方库应该在其目录下描述清楚依赖关系。比如csv-analyzer技能用到pandas和numpy那么技能目录下可以放一个requirements.txtpandas2.0.3 numpy1.24.3这样技能迁移到其他环境时可以快速完成依赖安装减少“在我电脑上能跑”的情况。6. 完整实战从零造一个 Agent Skill前面讲的都是概念和机制接下来进入最关键的部分——自己动手造一个能用的 Skill。我们以“会议记录质量打分与改进建议”为例。常见痛点团队开会后会议纪要质量参差不齐有的缺乏结论有的没有行动项。我们做一个技能输入会议纪要文本输出质量评分、缺失项检查结果和改进建议。6.1 确定技能目标技能名称meeting_minutes_reviewer技能目标评估一段会议纪要的完整度识别缺失的关键要素给出改进建议。适用场景用户粘贴会议纪要或要求检查会议记录是否合格。6.2 设计技能输出格式为了让结果稳定先定义一个输出格式{ status: success, score: 85, dimensions: { objectives: {score: 90, comment: 目标清晰明确}, decisions: {score: 70, comment: 缺少明确结论}, action_items: {score: 60, comment: 行动项负责人缺失} }, suggestions: [ 建议补充结论和决策依据, 每个行动项需要明确负责人和截止时间 ] }定义好输出结构后续脚本和 Agent 提示词都围绕这个结构来写整个技能会非常规范。6.3 编写核心脚本脚本不承担打分逻辑只负责把原始文本转换成结构化数据。比较合理的分工是用规则脚本做基础检查比如是否包含“结论”“行动项”等关键词把结构化结果交给 Agent 做综合评分和解释。scripts/review_meeting_minutes.pyimport json import sys import re def extract_sections(text: str) - dict: 基于常见会议纪要关键词初步判断文本覆盖了哪些部分。 sections { objectives: False, decisions: False, action_items: False } if re.search(r[目议][标题]|objective|goal|议题, text, re.I): sections[objectives] True if re.search(r结论|决定|决策|decision|conclusion, text, re.I): sections[decisions] True if re.search(r行动项|负责人|截止|action item|TODO|owner, text, re.I): sections[action_items] True return sections def main(): # 从标准输入读取文本 text sys.stdin.read() if not text.strip(): print(json.dumps({error: empty input})) return sections extract_sections(text) output { status: success, section_check: sections, text_length: len(text.strip()) } print(json.dumps(output, ensure_asciiFalse, indent2)) if __name__ __main__: main()这个脚本做的事情很简单读取文本按关键词初步判断文本包含哪几个标准模块。得分和最终结论由 Agent 在读取脚本输出后综合判断。这种分工比较稳妥。在 Linux 或 macOS 下运行时可以用管道方式传入文本echo 本次会议讨论了新版本上线计划结论是下周二发布行动项由张三负责编写发布检查清单截止时间周五。 | python3 scripts/review_meeting_minutes.py输出示例{ status: success, section_check: { objectives: false, decisions: true, action_items: true }, text_length: 58 }如果识别的 section 和实际文本有偏差可以通过调整正则或者补充同义词来改进。6.4 编写 SKILL.md脚本写好后需要把它“包装”成一个真正的 Skill。创建skills/meeting-minutes-reviewer/SKILL.md--- name: meeting_minutes_reviewer description: 审查会议纪要的完整度和质量识别是否包含会议目标、明确结论和可执行行动项并给出改进建议。当用户询问会议纪要质量、检查会议记录、改进会议纪要时使用。 --- # 会议纪要质量审查技能 ## 任务目标 评估一段会议纪要的完整度并给出可操作的改进建议。 ## 执行流程 1. 使用 scripts/review_meeting_minutes.py 对输入文本做基础结构检查。 2. 结合脚本输出的 section_check 结果分析缺失的要素。 3. 对以下三个维度分别打分分数范围 0-100 - objectives会议目标是否清晰。 - decisions是否包含明确的结论或决策。 - action_items是否包含行动项、负责人和截止时间。 4. 给出总分三个维度的加权平均。 5. 输出建议至少包含 2 条改进建议。 ## 评分参考 - 90 分以上结构完整可以直接作为正式会议纪要。 - 70-89 分整体可用但存在部分缺失。 - 70 分以下建议重新整理后再发布。 ## 注意事项 - 如果输入为空或过于简短直接返回提示信息停止后续步骤。 - 不修改原始会议纪要内容。 - 评分结果仅供辅助参考不替代人工判断。这段SKILL.md从“任务目标”“执行流程”“评分标准”“注意事项”四个方面进行了约束Agent 加载后能比较稳定地执行任务。6.5 注册技能到 Agent不同平台的注册方式不同。有些平台会扫描skills目录下的所有子目录有些需要在配置文件中显式声明。在配置文件agent-config/agent.yaml中注册技能agent: name: meeting-assistant skills: - name: meeting_minutes_reviewer path: ../skills/meeting-minutes-reviewer enabled: trueenabled字段表示技能是否启用。生产环境建议默认关闭新技能经过测试后再开启避免新技能影响线上 Agent 的行为。6.6 运行与验证启动 Agent 后可以输入下面这段内容测试我们今天讨论了下个季度的产品规划初步定下来三个方向。然后讨论了资源分配技术团队比较紧张。暂时就这些。预期 Agent 的反馈可能类似objectives70 分提及了产品规划但没有给出具体的成功标准。decisions50 分讨论了方向但没有明确拍板。action_items30 分没有行动项和负责人。改进建议补充明确的目标和成功指标列出下一步行动项并指定负责人和截止时间。如果测试结果偏差较大先检查SKILL.md中的流程描述是否足够清晰再检查脚本的正则是否覆盖了目标文本。7. 进阶让多个 Skill 协同工作7.1 为什么需要组合单个 Skill 只能解决一个单点任务但真实场景往往是复合型的。比如“读一份会议纪要写成项目周报再发给项目群”就需要至少三个能力会议纪要理解、周报生成、消息发送。如果把这几个能力拆成独立的 SkillAgent 可以先调用会议纪要解析 Skill再调用周报生成 Skill最后调用消息发送工具。这个过程中的编排逻辑既可以由 Agent 自主完成也可以由开发者在技能文本中写清楚。7.2 设计可衔接的输出要让 Skill 能顺利组合关键是输出格式要“好衔接”。如果一个技能输出很自由下一个技能解析时就会很吃力。建议每个 Skill 在输出时带上必要的数据标识。例如会议纪要审查技能的输出可以增加一个meeting_id字段{ meeting_id: MT-2025-001, score: 85, ... }后续其他技能或工作流可以根据这个 ID 关联数据形成完整的处理链路。7.3 失败降级与上下文保留多技能协同还有一个需要考虑的问题如果中间某个技能失败整个流程该怎么处理。常见的做法是降级策略。例如会议纪要审查时如果脚本执行失败可以先让 Agent 直接基于原始文本给出一个非结构化的评估同时明确告知用户“部分检查未完成”。这种降级策略能提升用户体验也能保留问题现场方便排查。无论哪个平台都应避免“失败后静默吞掉错误”的情况——用户看到的回答可能不完整但没有任何提示这种体验最差。8. 常见问题与排查思路无论你是在本地测试还是已经部署到了线上都可能遇到一些共性问题。下面列几个高频率场景。问题现象常见原因解决思路Agent 从不调用某个技能技能名称和描述写得不够清晰或与任务不匹配改写 description补充触发词和典型场景技能被调用但输出不稳定SKILL.md 中流程不够具体模型自由发挥空间大细化执行步骤增加输出格式要求脚本执行报错依赖缺失、路径不对、输入数据格式不对检查 requirements.txt使用绝对路径测试脚本输入技能目录加载失败目录结构不符合平台要求对照平台文档检查目录层级和文件命名启用了新技能后老功能异常技能之间的描述存在重叠Agent 选错技能调整 description区分边界暂时禁用新技能测试上下文变长、Token 成本上升技能文件内容过多Agent 频繁加载多个技能精简 SKILL.md将详细逻辑放入脚本缩小技能正文排查时有一个比较实用的习惯给每个技能添加运行日志。日志至少包含“是否被加载”“执行了哪几步”“输出结果摘要”“是否有异常”。有了日志很多看似奇怪的问题都能迅速定位。9. 最佳实践与工程建议9.1 技能编写规范命名用简短小写字母加下划线如csv_analyzer、meeting_minutes_reviewer。每个技能目录中必须有SKILL.md。description控制在 100 字左右必须包含触发场景。技能内脚本统一放在scripts/子目录。输出格式优先使用 JSON字段命名统一使用小写加下划线。9.2 权限与安全边界这是很容易被忽略的部分。技能如果涉及文件读取、网络请求、数据库查询等操作一定要明确最小权限原则。具体来说技能只能访问它明确需要的文件路径。涉及网络请求时配置合法且经过审批的接口凭证。禁止在技能描述中硬编码生产环境的密钥。涉及数据库时使用只读账号禁止 Skill 执行 DDL 和 DELETE 操作。任何可能产生数据变更的操作都要经过人工确认。这一点在生产环境尤其重要。一个技能如果权限过大一旦被恶意 Prompt 利用可能造成比想象中更严重的后果。安全永远要放在功能前面。9.3 测试与灰度发布技能上线前建议准备至少一类基准测试集。例如对会议纪要审查技能准备三份正常会议纪要、三份不完整纪要、一份空白文本观察技能输出是否稳定。正式更新技能时不要直接替换线上版本。可以先将新技能以不同名称部署灰度运行一段时间确认输出质量后再做切换。如果发现异常可以快速回滚到旧版本。9.4 性能与成本意识Agent Skills 虽然能减少重复编写 Prompt但如果技能写得太冗长每次加载都会增加 Token 消耗。建议只保留必要内容把大量细节放入脚本。另外技能数量增多后平台在每次请求时都可能扫描技能清单。如果技能数量达到几十个建议给技能增加分组或标签缩小匹配范围降低延迟。9.5 记录与复盘把每个技能的调整都记录下来包括调整原因、调整前后效果对比、上线时间。这个习惯短期内看不出价值但积累几个月后你会拥有一份非常宝贵的技能优化数据库几乎可以把“经验”变成团队资产。10. 总结与下一步学习建议到这里我们从概念、机制、实战、排查到最佳实践完整走了一遍 Agent Skills。回顾一下核心收获Agent Skills 不是一个新的框架而是对 Agent 能力的一种结构化组织方式。它把知识、流程、脚本、约束打包成一个可复用单元让 Agent 按需加载。用好一个技能重点在于写好 description 和执行流程。造一个技能核心是设计清晰稳定的输入输出并把精确计算放到代码脚本里把理解和决策留给模型。在生产环境落地权限、安全、日志、灰度发布这些工程细节比炫技更重要。如果你还想继续深入建议按下面的顺序来先把你日常工作中最高频的三个任务各做一个 Skill验证基本流程。然后尝试让两个 Skill 组合完成一个复合任务比如“解析会议纪要 → 生成待办事项”。再研究一下你所用平台的 Skill 调度机制看看是否有自定义调用优先级、分组加载等能力。最后把技能的形成、测试、发布流程逐步规范化形成一套团队内部的技能开发规范。Agent Skills 这个概念还在快速进化不同平台的具体格式和机制也会持续变化。但“把能力结构化、可复用、可编排”的思路是未来很长一段时间都适用的核心设计思想。现在动手做一个自己的技能哪怕很小也比停留在概念上更有价值。如果这篇文章对你有帮助可以收藏备用。也欢迎在评论区聊聊你正在思考的 Agent 场景大家一起少走弯路。 Agent Skills从概念到实战：构建可复用的AI能力包
各位读者朋友大家好。最近 AI Agent 相关的概念越来越密集尤其是 “Agent Skills”这个词在技术社区和招聘 JD 里出现频率明显上升。但很多刚接触的朋友会困惑它和 Tools、Function Call 有什么区别是新的框架吗需要写很复杂的代码吗这篇文章准备用尽量易懂的方式把 Agent Skills 从“概念”到“使用”再到“自己造一个”的完整过程拆开讲清楚。不需要你有非常深的机器学习基础只要会一点 Python能看懂 JSON 或 YAML跟着动手半小时就能跑通一个属于自己的 Skill。如果你想在简历上增加一项有含金量的 AI 工程能力或者想给现有 Agent 应用增加可复用能力这篇内容会很有帮助。我们先把目标定小一点理解核心概念掌握调用方式学会编写和注册一个自定义 Skill最后形成一个“会用到会造”的正向闭环。1. Agent Skills 到底是什么1.1 一句话理解 Agent Skills简单来说Agent Skills 就是给 AI Agent 预先准备的一组“可复用能力包”。这里的“能力”可以是某个领域的专业知识、一套操作流程、一段可执行工具代码、一组提示词模板也可以是一个结构化的技能描述文件。在早期的 Agent 开发中我们把能力拆成一个个独立的 Tool比如“查询天气”“发送邮件”“查询数据库”。Agent 需要的时候会通过工具调用去触发这些功能。这当然可行但存在一个明显问题工具之间是孤立的缺少上下文关联每次都需要在 Prompt 里写得非常详细Agent 才能知道什么场景该用哪个工具。Agent Skills 的做法是把更完整、更结构化的能力打包起来。一个 Skill 里面既包含“这个技能是干什么的”也包含“怎么用”“有什么限制”“需要什么参数”“有哪些步骤”。Agent 可以在运行过程中动态发现、加载并调用这些技能而不是每次都在系统提示词里手动塞一堆指令。1.2 它解决的核心痛点在没有 Agent Skills 之前大家做 Agent 应用时经常遇到三类麻烦第一系统提示词越来越长。一个复杂的 Agent 可能涉及十几个工具每个工具的描述、参数、注意事项都塞进 Prompt 里Token 成本高而且模型对关键信息的注意力会被稀释。第二能力复用很难。你在一个项目里写好了“PDF 报告分析”的能力换一个项目要么复制粘贴要么重新实现一遍维护成本极高。第三模型“知道但做不到”。大模型本身知道很多知识但在具体执行时需要非常精确的步骤和工具配合。如果没有结构化的技能指导模型容易凭借“记忆”自由发挥输出结果不稳定。Agent Skills 通过独立的技能文件把“知识、流程、工具、限制条件”打包起来让 Agent 在需要时动态调用。这样系统提示词保持精简能力可以跨项目复用模型执行时也有更明确的规范可循。1.3 Agent Skills 和 Tools、Workflows 的区别很多初学者容易把 Agent Skills、Tools、Workflows 混为一谈这里做一个简单对比。概念核心特点典型例子类比理解Tools单个可执行动作没有复杂流程搜索、发邮件、获取天气一把螺丝刀Workflows固定流程由开发者预先编排好数据清洗流水线、审批流程一条流水线Agent Skills可复用能力包包含描述、步骤、代码、约束从 PDF 提取结构化数据、对销售数据做归因分析一套工具箱 说明书Tools 强调的是“动作”Workflows 强调的是“流程”Agent Skills 强调的是“能力包”。一个 Skill 内部可以包含多个步骤也可以调用多个工具甚至还能嵌套其他 Skill。这种设计让 Agent 从“会调用工具”进化到“掌握专业技能”意义是不一样的。Tools 解决问题的粒度更小而 Agent Skills 更像是为某一类任务准备的标准化解决方案。2. Agent Skills 的典型应用场景2.1 企业知识库与文档处理场景这是目前落地最多的一类场景。企业积累了海量 PDF、Word、PPT 文档过去靠人工阅读整理效率太低靠普通聊天机器人又经常答非所问。基于 Agent Skills可以设计一个“文档深度解析”技能包。它包含文档格式识别、目录抽取、关键段落定位、摘要生成、重点信息抽取等多个环节。Agent 接收到用户指令后自动加载这个技能按照内置流程逐步处理文档最后输出结构化结果。相比传统 RAG检索增强生成方案Skill 的优势在于可以把“解析—抽取—归档”的完整工作流固化下来并且根据文档类型自动调整策略而不是简单地做一次向量检索。2.2 数据分析与报表生成数据分析类任务非常适合用 Agent Skills 来实现。举一个实际业务场景运营同学想快速看一下上周各渠道的投放效果并生成一份周报。一个“投放数据分析”技能可以包含以下内容数据源读取规则、核心指标口径定义如 ROI、转化率、获客成本、常见的对比分析方法、图表生成规范、报告输出模板。Agent 加载这个技能后能自动完成从取数、清洗、分析到报告生成的完整流程而且每次输出的口径保持一致。这种场景下Agent 不只是会调用 SQL 工具而是真正“懂”数据分析和报告规范这背后就是 Skill 在起作用。2.3 代码生成与工程辅助在软件开发场景中Agent Skills 也能发挥很大的作用。比如把一个团队的代码规范、目录结构、接口设计原则、常用开发框架的注意事项打包成一个“项目开发助手”技能。新成员加入项目时Agent 可以基于这个技能快速生成符合团队规范的代码骨架老成员写代码时Agent 也能按照技能要求进行代码审查指出不符合项目规范的地方。有意思的是这个场景已经超出了传统的“自动补全代码”范畴更接近“按照团队标准生产代码”。如果你负责团队的基础设施建设这种思路值得尝试。2.4 人文社科研究辅助的延伸最近有讨论提到“Agent Skills 赋能人文社科混合研究方法论文写作”这个方向很值得关注。人文社科研究中有大量工作涉及文献综述、资料爬梳、混合研究方法设计、问卷整理、访谈编码、内容分析等。传统方法是靠研究者手动完成耗时且容易遗漏。如果用 Agent Skills 来支撑可以让 Agent 掌握“文献检索与分析”“访谈文本编码”“内容分析框架应用”等技能帮研究者做前期的资料整理和分析工作。需要强调Agent 是辅助工具不能替代研究者的独立思考、理论框架构建和学术判断。但合理使用 Agent Skills确实能显著减轻机械性劳动的负担让研究者把更多精力放在核心问题上。3. 环境准备与平台选择3.1 先选一个能跑通的环境学习 Agent Skills最重要的一步是有一个可以实际运行的环境。市面上支持 Agent Skills 的平台和框架越来越多Anthropic 的 Claude 生态、各类开源 Agent 框架以及某些低代码平台都开始支持类似概念。这里不强制要求你使用某一家产品。我的建议是如果你平时已经在用某个 Agent 开发框架优先选择当前框架支持的技能扩展机制如果你是从零开始可以先从支持 Skill 格式的开源框架入手。文中示例采用“通用技能包格式 核心脚本”的方式呈现重点演示思路不绑定特定平台。你在实际落地时按所使用的框架文档调整文件结构和配置格式即可。3.2 开发环境准备虽然每个平台对 Skill 的具体实现不同但大部分都需要一个基础开发环境。建议准备以下内容Python 3.9 或更高版本用于编写技能脚本和执行本地测试。一个支持 Markdown 和 YAML 的编辑器VS Code 足够。你有权限访问的 Agent 运行环境可以是本地启动的服务也可以是某个云端平台。Git 用于版本管理方便回滚技能文件的修改记录。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3.3 示例项目结构一个典型的 Agent Skills 项目目录结构大致如下agent-skills-tutorial/ ├── skills/ │ ├── csv-analyzer/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── analyze_csv.py │ └── meeting-summarizer/ │ ├── SKILL.md │ └── scripts/ │ └── summarize.py ├── agent-config/ │ └── agent.yaml └── README.mdskills目录下每个子目录就是一个独立技能。每个技能目录里包含一个SKILL.md描述文件以及相关的脚本和资源。这样的结构清晰、可维护也方便后续扩展。4. 会用的第一步理解 Skill 的组成与加载机制4.1 SKILL.md 是什么SKILL.md是 Agent Skills 的核心元数据文件也可以理解为技能的“说明书”。它描述了这个技能是做什么的、什么场景下使用、如何使用、有哪些注意事项。以 Claude Agent Skills 的格式为例一个SKILL.md通常包含两部分YAML 格式的 frontmatter元信息区和 Markdown 格式的正文使用说明区。下面是一个简化的结构--- name: csv_analyzer description: 分析 CSV 数据文件生成统计摘要和分布情况。 --- # CSV 数据分析技能 ## 适用场景 适用于用户提供 CSV 文件需要了解数据概况、统计特征、异常值等场景。 ## 工作流程 1. 读取 CSV 文件识别表头和数据类型。 2. 计算数值列的基本统计量均值、中位数、标准差等。 3. 检查缺失值和异常值。 4. 输出分析报告。 ## 注意事项 - 仅支持 UTF-8 编码的 CSV 文件。 - 大文件超过 100MB需要分块处理。 - 不修改原始数据文件分析结果单独输出。这段内容看起来很简单但它直接决定了 Agent 什么时候会使用这个技能、以及怎么使用。描述写得越清晰Agent 的调用准确率就越高。4.2 Agent 如何发现和调用 Skill很多平台的 Agent 会在每次对话开始时根据用户请求和当前上下文动态决定是否需要加载某个技能。它并不是把全部技能都塞进上下文而是先读取技能清单通常包含技能名称和一句话描述再选择最匹配的技能加载详细内容。可以理解为清单是“技能索引”SKILL.md是“详细操作手册”。Agent 先查索引再决定要不要看手册。这种机制的好处是省 Token效率高而且技能数量可以做得很大不用担心中文上下文过长影响效果。缺点也有如果技能描述写得不准确Agent 可能错过匹配或者加载了错误技能。所以编写技能描述时要把关键触发词、适用场景写得尽量准确。4.3 调用参数与返回结果Skill 在被调用时通常会接收一些输入参数。这些参数可以是用户请求中包含的信息也可以是 Agent 在执行过程中生成的信息。继续以csv_analyzer为例可能的输入参数包括file_pathCSV 文件路径。analysis_type分析类型取值为summary、distribution、outlier等。输出的结果建议遵循统一的结构例如{ status: success, file_name: sales_data.csv, row_count: 1520, column_count: 8, summary: { total_revenue: 152000.5, avg_order_value: 100.0, max_order_value: 500.0 }, missing_values: { customer_name: 3 } }统一输出格式带来的好处非常实际。第一Agent 可以稳定解析结果并生成后续回答第二多个技能串联时上下游数据结构能对齐第三日志和排错更直观。5. 深入理解 Skill 的核心机制5.1 Skill 描述是调用准确率的关键很多刚开始写技能的朋友会忽略一个细节真正决定技能有没有用的很多时候不是脚本多复杂而是description写得好不好。大模型在判断调用哪个技能时主要依赖技能描述与当前任务的语义匹配程度。如果描述含糊比如只写“处理数据”Agent 就不知道它到底能处理什么数据、适合什么场景。建议描述中包含这些要素技能的目标任务。输入数据的类型和格式。输出结果的形式。典型的触发场景。下面做一组对比。模糊描述description: 分析数据。清晰描述description: 分析 CSV 格式的销售数据返回总销售额、订单数、平均订单金额等统计指标。当用户提到销售报表、订单明细、业绩汇总时使用该技能。后者的触发准确率显然会高很多。5.2 Skill 内部的步骤拆解一个专业的 Skill 不是一句话就能说清的它内部应该有流程。这些流程可以指导 Agent 按步骤执行避免跳步或遗漏关键环节。例如一个“PDF 发票信息抽取”技能内部流程可能是识别 PDF 文件格式和页数。提取文本内容。根据发票版式定位关键字段发票号码、税额、金额、购买方。校验字段完整性。输出 JSON 结构的数据。每一步都清晰罗列后Agent 执行起来就有章法。即使中间某一步失败也能准确定位到是哪一环节出了问题。这里需要提醒Agent 本质上仍然是概率模型即使有明确步骤也可能出现偏差。因此技能步骤设计得越具体、越可验证越好。如果是需要精确计算的任务建议把计算逻辑封装在代码脚本里而不是让模型在对话里手算。5.3 代码脚本与 Prompt 的分工在 Agent Skills 中代码脚本和 Prompt 各有分工。代码脚本负责精确、可重复的执行逻辑比如文件解析、数据计算、 API 调用、结果格式化。Prompt/文档负责指导模型理解任务背景、决策分支、质量标准和注意事项。举个例子在“CSV 分析”技能中读取文件、统计计算交给 Python 脚本处理这部分不能容忍幻觉而“根据统计结果给出一段业务解读”则交给模型完成这部分适合发挥大模型的总结和推理能力。把两者分开既能保证准确性又能保留模型的理解能力。这也是 Agent Skills 设计上比较聪明的一点。5.4 版本管理与依赖隔离随着技能数量增加版本管理会成为实际问题。每个 Skill 建议独立管理版本号记录变更内容。一个技能的内部脚本如果引用了第三方库应该在其目录下描述清楚依赖关系。比如csv-analyzer技能用到pandas和numpy那么技能目录下可以放一个requirements.txtpandas2.0.3 numpy1.24.3这样技能迁移到其他环境时可以快速完成依赖安装减少“在我电脑上能跑”的情况。6. 完整实战从零造一个 Agent Skill前面讲的都是概念和机制接下来进入最关键的部分——自己动手造一个能用的 Skill。我们以“会议记录质量打分与改进建议”为例。常见痛点团队开会后会议纪要质量参差不齐有的缺乏结论有的没有行动项。我们做一个技能输入会议纪要文本输出质量评分、缺失项检查结果和改进建议。6.1 确定技能目标技能名称meeting_minutes_reviewer技能目标评估一段会议纪要的完整度识别缺失的关键要素给出改进建议。适用场景用户粘贴会议纪要或要求检查会议记录是否合格。6.2 设计技能输出格式为了让结果稳定先定义一个输出格式{ status: success, score: 85, dimensions: { objectives: {score: 90, comment: 目标清晰明确}, decisions: {score: 70, comment: 缺少明确结论}, action_items: {score: 60, comment: 行动项负责人缺失} }, suggestions: [ 建议补充结论和决策依据, 每个行动项需要明确负责人和截止时间 ] }定义好输出结构后续脚本和 Agent 提示词都围绕这个结构来写整个技能会非常规范。6.3 编写核心脚本脚本不承担打分逻辑只负责把原始文本转换成结构化数据。比较合理的分工是用规则脚本做基础检查比如是否包含“结论”“行动项”等关键词把结构化结果交给 Agent 做综合评分和解释。scripts/review_meeting_minutes.pyimport json import sys import re def extract_sections(text: str) - dict: 基于常见会议纪要关键词初步判断文本覆盖了哪些部分。 sections { objectives: False, decisions: False, action_items: False } if re.search(r[目议][标题]|objective|goal|议题, text, re.I): sections[objectives] True if re.search(r结论|决定|决策|decision|conclusion, text, re.I): sections[decisions] True if re.search(r行动项|负责人|截止|action item|TODO|owner, text, re.I): sections[action_items] True return sections def main(): # 从标准输入读取文本 text sys.stdin.read() if not text.strip(): print(json.dumps({error: empty input})) return sections extract_sections(text) output { status: success, section_check: sections, text_length: len(text.strip()) } print(json.dumps(output, ensure_asciiFalse, indent2)) if __name__ __main__: main()这个脚本做的事情很简单读取文本按关键词初步判断文本包含哪几个标准模块。得分和最终结论由 Agent 在读取脚本输出后综合判断。这种分工比较稳妥。在 Linux 或 macOS 下运行时可以用管道方式传入文本echo 本次会议讨论了新版本上线计划结论是下周二发布行动项由张三负责编写发布检查清单截止时间周五。 | python3 scripts/review_meeting_minutes.py输出示例{ status: success, section_check: { objectives: false, decisions: true, action_items: true }, text_length: 58 }如果识别的 section 和实际文本有偏差可以通过调整正则或者补充同义词来改进。6.4 编写 SKILL.md脚本写好后需要把它“包装”成一个真正的 Skill。创建skills/meeting-minutes-reviewer/SKILL.md--- name: meeting_minutes_reviewer description: 审查会议纪要的完整度和质量识别是否包含会议目标、明确结论和可执行行动项并给出改进建议。当用户询问会议纪要质量、检查会议记录、改进会议纪要时使用。 --- # 会议纪要质量审查技能 ## 任务目标 评估一段会议纪要的完整度并给出可操作的改进建议。 ## 执行流程 1. 使用 scripts/review_meeting_minutes.py 对输入文本做基础结构检查。 2. 结合脚本输出的 section_check 结果分析缺失的要素。 3. 对以下三个维度分别打分分数范围 0-100 - objectives会议目标是否清晰。 - decisions是否包含明确的结论或决策。 - action_items是否包含行动项、负责人和截止时间。 4. 给出总分三个维度的加权平均。 5. 输出建议至少包含 2 条改进建议。 ## 评分参考 - 90 分以上结构完整可以直接作为正式会议纪要。 - 70-89 分整体可用但存在部分缺失。 - 70 分以下建议重新整理后再发布。 ## 注意事项 - 如果输入为空或过于简短直接返回提示信息停止后续步骤。 - 不修改原始会议纪要内容。 - 评分结果仅供辅助参考不替代人工判断。这段SKILL.md从“任务目标”“执行流程”“评分标准”“注意事项”四个方面进行了约束Agent 加载后能比较稳定地执行任务。6.5 注册技能到 Agent不同平台的注册方式不同。有些平台会扫描skills目录下的所有子目录有些需要在配置文件中显式声明。在配置文件agent-config/agent.yaml中注册技能agent: name: meeting-assistant skills: - name: meeting_minutes_reviewer path: ../skills/meeting-minutes-reviewer enabled: trueenabled字段表示技能是否启用。生产环境建议默认关闭新技能经过测试后再开启避免新技能影响线上 Agent 的行为。6.6 运行与验证启动 Agent 后可以输入下面这段内容测试我们今天讨论了下个季度的产品规划初步定下来三个方向。然后讨论了资源分配技术团队比较紧张。暂时就这些。预期 Agent 的反馈可能类似objectives70 分提及了产品规划但没有给出具体的成功标准。decisions50 分讨论了方向但没有明确拍板。action_items30 分没有行动项和负责人。改进建议补充明确的目标和成功指标列出下一步行动项并指定负责人和截止时间。如果测试结果偏差较大先检查SKILL.md中的流程描述是否足够清晰再检查脚本的正则是否覆盖了目标文本。7. 进阶让多个 Skill 协同工作7.1 为什么需要组合单个 Skill 只能解决一个单点任务但真实场景往往是复合型的。比如“读一份会议纪要写成项目周报再发给项目群”就需要至少三个能力会议纪要理解、周报生成、消息发送。如果把这几个能力拆成独立的 SkillAgent 可以先调用会议纪要解析 Skill再调用周报生成 Skill最后调用消息发送工具。这个过程中的编排逻辑既可以由 Agent 自主完成也可以由开发者在技能文本中写清楚。7.2 设计可衔接的输出要让 Skill 能顺利组合关键是输出格式要“好衔接”。如果一个技能输出很自由下一个技能解析时就会很吃力。建议每个 Skill 在输出时带上必要的数据标识。例如会议纪要审查技能的输出可以增加一个meeting_id字段{ meeting_id: MT-2025-001, score: 85, ... }后续其他技能或工作流可以根据这个 ID 关联数据形成完整的处理链路。7.3 失败降级与上下文保留多技能协同还有一个需要考虑的问题如果中间某个技能失败整个流程该怎么处理。常见的做法是降级策略。例如会议纪要审查时如果脚本执行失败可以先让 Agent 直接基于原始文本给出一个非结构化的评估同时明确告知用户“部分检查未完成”。这种降级策略能提升用户体验也能保留问题现场方便排查。无论哪个平台都应避免“失败后静默吞掉错误”的情况——用户看到的回答可能不完整但没有任何提示这种体验最差。8. 常见问题与排查思路无论你是在本地测试还是已经部署到了线上都可能遇到一些共性问题。下面列几个高频率场景。问题现象常见原因解决思路Agent 从不调用某个技能技能名称和描述写得不够清晰或与任务不匹配改写 description补充触发词和典型场景技能被调用但输出不稳定SKILL.md 中流程不够具体模型自由发挥空间大细化执行步骤增加输出格式要求脚本执行报错依赖缺失、路径不对、输入数据格式不对检查 requirements.txt使用绝对路径测试脚本输入技能目录加载失败目录结构不符合平台要求对照平台文档检查目录层级和文件命名启用了新技能后老功能异常技能之间的描述存在重叠Agent 选错技能调整 description区分边界暂时禁用新技能测试上下文变长、Token 成本上升技能文件内容过多Agent 频繁加载多个技能精简 SKILL.md将详细逻辑放入脚本缩小技能正文排查时有一个比较实用的习惯给每个技能添加运行日志。日志至少包含“是否被加载”“执行了哪几步”“输出结果摘要”“是否有异常”。有了日志很多看似奇怪的问题都能迅速定位。9. 最佳实践与工程建议9.1 技能编写规范命名用简短小写字母加下划线如csv_analyzer、meeting_minutes_reviewer。每个技能目录中必须有SKILL.md。description控制在 100 字左右必须包含触发场景。技能内脚本统一放在scripts/子目录。输出格式优先使用 JSON字段命名统一使用小写加下划线。9.2 权限与安全边界这是很容易被忽略的部分。技能如果涉及文件读取、网络请求、数据库查询等操作一定要明确最小权限原则。具体来说技能只能访问它明确需要的文件路径。涉及网络请求时配置合法且经过审批的接口凭证。禁止在技能描述中硬编码生产环境的密钥。涉及数据库时使用只读账号禁止 Skill 执行 DDL 和 DELETE 操作。任何可能产生数据变更的操作都要经过人工确认。这一点在生产环境尤其重要。一个技能如果权限过大一旦被恶意 Prompt 利用可能造成比想象中更严重的后果。安全永远要放在功能前面。9.3 测试与灰度发布技能上线前建议准备至少一类基准测试集。例如对会议纪要审查技能准备三份正常会议纪要、三份不完整纪要、一份空白文本观察技能输出是否稳定。正式更新技能时不要直接替换线上版本。可以先将新技能以不同名称部署灰度运行一段时间确认输出质量后再做切换。如果发现异常可以快速回滚到旧版本。9.4 性能与成本意识Agent Skills 虽然能减少重复编写 Prompt但如果技能写得太冗长每次加载都会增加 Token 消耗。建议只保留必要内容把大量细节放入脚本。另外技能数量增多后平台在每次请求时都可能扫描技能清单。如果技能数量达到几十个建议给技能增加分组或标签缩小匹配范围降低延迟。9.5 记录与复盘把每个技能的调整都记录下来包括调整原因、调整前后效果对比、上线时间。这个习惯短期内看不出价值但积累几个月后你会拥有一份非常宝贵的技能优化数据库几乎可以把“经验”变成团队资产。10. 总结与下一步学习建议到这里我们从概念、机制、实战、排查到最佳实践完整走了一遍 Agent Skills。回顾一下核心收获Agent Skills 不是一个新的框架而是对 Agent 能力的一种结构化组织方式。它把知识、流程、脚本、约束打包成一个可复用单元让 Agent 按需加载。用好一个技能重点在于写好 description 和执行流程。造一个技能核心是设计清晰稳定的输入输出并把精确计算放到代码脚本里把理解和决策留给模型。在生产环境落地权限、安全、日志、灰度发布这些工程细节比炫技更重要。如果你还想继续深入建议按下面的顺序来先把你日常工作中最高频的三个任务各做一个 Skill验证基本流程。然后尝试让两个 Skill 组合完成一个复合任务比如“解析会议纪要 → 生成待办事项”。再研究一下你所用平台的 Skill 调度机制看看是否有自定义调用优先级、分组加载等能力。最后把技能的形成、测试、发布流程逐步规范化形成一套团队内部的技能开发规范。Agent Skills 这个概念还在快速进化不同平台的具体格式和机制也会持续变化。但“把能力结构化、可复用、可编排”的思路是未来很长一段时间都适用的核心设计思想。现在动手做一个自己的技能哪怕很小也比停留在概念上更有价值。如果这篇文章对你有帮助可以收藏备用。也欢迎在评论区聊聊你正在思考的 Agent 场景大家一起少走弯路。