从“AI 很聪明但让它干点具体活还是费劲”这个感受聊起。过去一年越来越多开发者开始接触 Agent 开发。试过的朋友大多有类似体验大模型本身挺聪明写 Prompt 也能写出像模像样的方案可真让它去“完成一件完整任务”比如自动整理一份数据表格、批量处理文件、定时抓取网页信息就经常跑偏要么缺步骤要么格式不对。问题通常不出在模型上而是出在“模型缺少完成这项任务的具体方法”。你光告诉一个实习生“去把数据整理好”他也会一脸茫然你得告诉他用什么工具、按什么顺序、输出成什么格式。这一整套“做事的固定套路”在 Agent 体系里就是 Agent Skills。这篇文章不绕弯子目标很明确用一小时从理解 Agent Skills 是什么到能读懂别人的 Skill再到自己动手造一个可用的 Skill。文章不会涉及太多抽象理论重点放在可以直接落地的结构和代码上。先给一个判断Agent Skills 是 Agent 从“演示级”走向“可用级”的关键门槛。模型负责“想”Skill 负责“会做”。谁先把技能沉淀成标准模块谁就能大幅降低 Agent 的开发成本。1. 为什么突然都在聊 Agent Skills最近一段时间Agent Skills 的热度明显上升相关讨论也从概念层慢慢转向实战层。这背后的技术变化其实很直接早期 Agent 主要靠“大模型 Prompt”驱动本质是一个推理框架。你告诉模型目标它自己拆步骤自己决定调用哪些工具。这套思路做 Demo 没问题但要上真实业务就会暴露出两个麻烦第一模型每次都在“临场发挥”同样的任务可能每次执行顺序都不一样结果不稳定第二业务里的很多操作是有固定套路的比如“先校验数据再清洗再统计最后出报告”这些流程不该让模型每次重新发明一次。Agent Skills 要解决的问题就是把“固定套路”沉淀成可复用的能力模块。你可以把它理解成给 Agent 配备的“岗位技能包”。一个技能包封装了某个任务领域的完整方法包括什么时候用、怎么用、输入什么、输出什么。模型只需要识别当前任务适合调用哪个技能然后按技能中定义的方法执行即可。从产业链看主流 AI 厂商和开源社区都在往这个方向使劲虽然具体叫法可能不同但核心理念一致把能力封装成标准模块供 Agent 调用。对普通开发者来说这意味着一个新的机会点——你不需要从零训练模型也能通过编写高质量 Skill 成为 Agent 生态里的“能力供应商”。这个变化对两类人特别有价值业务开发人员把公司内部复杂业务流程封装成 Skill减少重复开发。普通使用者通过组合现成 Skill让通用 Agent 完成自己领域的专业任务。一句话总结Agent Skills 不是新概念而是 Agent 应用走向工程化的必然产物。2. Agent Skills 到底是什么用一个比喻来理解。假设你是一家公司的老板Agent 是你的一个新员工。大模型是这个员工的“大脑”很聪明知识面广但没经验。你给他安排任务他大概率能听懂但具体操作未必专业。这时候你需要给他配“岗位手册”手册里清楚写着这类任务的标准步骤是什么、第一步做什么、遇到异常怎么处理、最终交付什么格式。Agent Skills 就是这个岗位手册只不过它不止是给人看的文字而是能被模型读取、能配合脚本执行的结构化文件。从实现角度看一个典型的 Agent Skill 通常包含三部分组成部分职责类比描述文件如 SKILL.md告诉模型什么时候用、怎么用、输入输出是什么岗位手册实现脚本/代码真正执行任务逻辑员工的手艺依赖与配置声明声明运行环境和依赖库工具条件模型在执行任务时会先阅读描述文件判断当前任务是否匹配这个技能如果匹配模型就会按照描述中说明的方式来调用实现脚本把结果处理后反馈给用户。这个机制听起来复杂但设计上有一个关键原则只有描述部分需要模型理解执行部分仍然是确定性代码。换句话说Skill 把“模型的灵活性”和“代码的确定性”结合在了一起。模型负责决策代码负责执行。这也正是它稳定可靠的原因。那为什么要单独做一层 Skill而不是把所有逻辑都写进系统 Prompt核心原因是复用和隔离。系统 Prompt 会随着项目膨胀变得难以维护而且不同任务混杂在一起模型容易“精神分裂”。Skill 做成了独立模块按需加载哪个任务匹配哪个技能边界清晰开发和测试都能单独进行。3. Agent、Agent Skill、Tool、Workflow 到底什么区别很多初学者会把 Agent Skills 和 Tool、Workflow 混为一谈这里必须把概念边界说清楚。3.1 Tool工具Tool 是 Agent 可以调用的单一函数或接口。它解决的是“某一个动作怎么做”的问题。比如一个get_weather(city)函数输入城市名返回天气数据。它动作单一、职责明确没有复杂的流程判断。3.2 Skill技能Skill 是“一组能力的封装”它通常包含使用场景描述 流程步骤 一个或多个底层调用。它解决的是“一类任务怎么完成”的问题。比如“周报生成”这个 Skill内部可能包含数据读取、指标计算、文本生成、格式排版四个步骤模型只需要描述目标Skill 内部按流程执行。3.3 Workflow工作流Workflow 是多个步骤的固定编排通常面向一个完整业务场景步骤之间的流转关系是提前定义死的。比如“每天早上 9 点抓取数据 → 清洗 → 生成日报 → 发到群里”。它强调流程的确定性适合稳定、重复、不太需要模型判断的任务。三者可以这样对比概念作用范围决策方式复用粒度典型例子Tool单一动作基本无决策函数级发送 HTTP 请求、读取文件Skill一类任务模型判断何时用任务级数据分析、文档转换、周报生成Workflow完整业务流程流程固定业务级每日数据监控、定时发布在实际项目中三者常常组合使用。Workflow 在宏观上编排流程Skill 在关键节点提供专业能力Tool 则是 Skill 内部的底层操作单元。很多刚接触 Agent Skills 的人会有一个误区觉得 Skill 就是“把多个 Tool 写在同一个文件里”。其实区别在于Skill 不只是动作的组合它更强调“对任务的理解”——描述清楚什么场景下用、怎么用、输出什么。好的 Skill 能让模型一目了然差的 Skill 即使代码逻辑正确模型也可能在错误场景调用它。4. 核心原理模型如何“学会”使用一个 Skill理解 Skill 的工作机制关键要理解模型是怎么“阅读”和“选择”技能的。在 Skill 机制中模型并不是预先把所有技能代码加载到大脑里。更常见的做法是系统把已注册 Skill 的描述信息名称、使用场景、输入输出格式提供给模型推理模型根据用户当前需求从候选技能中挑选匹配项。一个形象的类比你打开手机应用商店看到几十个 App 的图标和简介你不会把所有 App 都下载下来而是根据当前需求挑选一个下载安装。模型的技能选择也类似它先在“技能列表”里做匹配选中后再把对应实现拉起来执行。所以Skill 描述文件写得清不清楚直接决定模型会不会正确调用它。一个合格的 Skill 描述文件通常需要回答四个问题这个技能解决什么问题什么场景下应该调用它需要什么输入以什么格式给返回值是什么以什么格式返回如果描述模糊模型就会犹豫或误判。比如一个“数据转换”技能如果描述里没写清楚是“Markdown 转 CSV”模型可能在用户问“帮我处理表格”时错误调用最终产出不符合预期。实现侧的逻辑就简单多了。一旦模型确定要调用某个技能系统执行的就是确定性代码按部就班地跑脚本、传参数、接收输出。这也是 Skill 机制比“纯 Prompt 驱动”更稳定的原因决定用哪个方法交给模型方法本身交给代码。5. 第一步读懂一个现成 Skill 的结构会用既然要“会用”第一步是能读懂一个现成的 Skill。目前社区里常见的 Skill 组织方式通常是一个目录里面至少包含描述文件和实现文件。下面是一个典型的目录结构示例skills/ └── markdown_table_to_csv/ ├── SKILL.md └── md2csv.py其中SKILL.md是这个技能的名片也是模型判断调用时最重要的依据。5.1 SKILL.md 描述文件示例--- name: markdown_table_to_csv description: 将 Markdown 格式的表格转换为标准 CSV 文件适用于 Excel 打开、数据分析等场景。 input: 一段包含 | 分隔的 Markdown 表格文本。 output: 一个 CSV 文件路径。 --- # Markdown Table to CSV ## 适用场景 - 用户粘贴了 Markdown 格式的表格 - 用户需要把表格数据用于 Excel 或数据分析工具 ## 输入格式 一段 Markdown 表格文本例如 | 姓名 | 年龄 | 城市 | | --- | --- | --- | | 张三 | 25 | 北京 | ## 输出格式 标准 CSV 文件路径使用 UTF-8 编码。从表面看这份描述文件就是一段普通文档但在 Agent 体系中它就是模型决定“是否调用”的依据。这里有几个关键点name字段是技能的唯一标识要简短且含义明确。description字段是技能的功能摘要模型会优先阅读它。写的时候要覆盖“解决什么问题、输入什么、输出什么”。正文部分可以补充更详细的格式约定供模型在被选中后阅读。5.2 实现脚本示例#!/usr/bin/env python3 文件路径skills/markdown_table_to_csv/md2csv.py 功能读取 stdin 中的 Markdown 表格输出 CSV 文件。 import csv import sys import re def md_table_to_rows(md_text: str): lines [line.strip() for line in md_text.splitlines() if line.strip()] rows [] for line in lines: # 跳过 Markdown 表格的分隔行如 | --- | --- | if re.match(r^\|?[\s:\-|]\|?$, line) and - in line: continue cells [cell.strip() for cell in line.strip(|).split(|)] rows.append(cells) return rows def save_rows_to_csv(rows, output_path): with open(output_path, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerows(rows) if __name__ __main__: md_input sys.stdin.read() output sys.argv[1] if len(sys.argv) 1 else output.csv data_rows md_table_to_rows(md_input) save_rows_to_csv(data_rows, output) print(f已保存 {len(data_rows)} 行数据到 {output})如果有同学想直接验证这段脚本可以这样操作echo | 姓名 | 年龄 | 城市 | | --- | --- | --- | | 张三 | 25 | 北京 | | python3 md2csv.py result.csv如果一切正常屏幕上会打印“已保存 2 行数据到 result.csv”当前目录下会生成result.csv文件。理解这个阶段的关键是描述文件负责“说清楚”实现代码负责“做出来”。两者缺一不可。6. 第二步把 Skill 挂载到 Agent 上跑起来会用读懂了一个 Skill 之后接下来把它挂到 Agent 上跑通这是建立信心的关键一步。不同 Agent 框架对 Skill 的实现差异很大但从设计模式看通常都需要你完成三件事注册 Skill 的描述信息。指定 Skill 的入口命令和输入输出方式。让 Agent 在推理时能“看得到”这些描述。这里不针对某个具体框架写死代码而是给出一个通用思路。下面是一个简化的挂载逻辑示意在实际项目中可替换为对应框架的注册 API。# 文件路径examples/mount_skill.py 伪代码演示将 Skill 挂载到 Agent 的核心思路 实际项目中请根据所选 Agent 框架的 API 调整 import subprocess import json # 1. 技能注册表Agent 运行时会拿这份描述去匹配用户需求 SKILL_REGISTRY { markdown_table_to_csv: { description: 将 Markdown 表格转换为 CSV 文件, entry: python3 skills/markdown_table_to_csv/md2csv.py, input: text/markdown, output: file/csv, }, # ... 其他 Skill } def run_skill(skill_name: str, input_text: str, output_file: str output.csv): 执行指定 Skill 的入口脚本。 这是一个通用示例生产环境请做好参数校验和异常处理。 if skill_name not in SKILL_REGISTRY: raise ValueError(f未知 Skill: {skill_name}) entry SKILL_REGISTRY[skill_name][entry] command entry.split() [output_file] completed subprocess.run( command, inputinput_text, capture_outputTrue, textTrue ) if completed.returncode ! 0: # 真实项目里这里应该记录详细日志 raise RuntimeError(fSkill 执行失败: {completed.stderr}) return completed.stdout if __name__ __main__: # 模拟 Agent 识别到用户需求后调用 markdown_table_to_csv 技能 user_input | 商品 | 价格 |\n| --- | --- |\n| 鼠标 | 99 | result run_skill(markdown_table_to_csv, user_input, goods.csv) print(result)跑通这个流程之后你对“Agent 使用 Skill”的理解就会变得非常具体不再是一个模糊概念而是一条完整链路用户提出问题 → 模型理解意图 → 在技能注册表中匹配 → 执行技能脚本 → 返回结果。如果你选的框架已经内置支持 Skill比如某些开源 Agent 项目提供了 Skills 目录约定那实际接入会更简单通常只需要把 Skill 目录放到指定位置在配置里声明启用即可。但无论框架怎么封装背后都是这套“描述 执行”的逻辑。7. 第三步从零动手“造”一个自己的 Skill会造到这一步你已经知道了 Skill 是什么、长什么样、怎么挂载。接下来就是标题里“会造”这个目标了。这里我们造一个实用的小技能把一段 Markdown 表格文本转换成 CSV 文件。之所以选这个是因为它足够简单、贴近日常办公而且能完整展示一个 Skill 从设计到落地的全过程。7.1 第一步定义能力边界写代码之前先明确你的 Skill 负责什么、不负责什么。负责读取 Markdown 表格文本提取表头和行数据生成 CSV 文件。不负责处理复杂格式如单元格内换行、生成图表、做数据分析。为什么明确边界很重要因为描述文件写得太宽模型会在不合适的场景调用它最后产出不理想。边界收窄一些反而能提高触发的准确性。7.2 第二步编写实现脚本这里直接使用前面第 5 节里那个md2csv.py脚本。它在真实场景里能跑通基础的 Markdown 表格转换够用且不复杂。7.3 第三步编写 SKILL.md 描述文件描述文件是整个 Skill 的灵魂。写的时候站在模型的角度思考如果我是大模型看到这段描述能不能明确判断“该用它”--- name: markdown_table_to_csv description: 将 Markdown 格式的表格转换为标准 CSV 文件。 当用户提供包含 | 分隔符号的 Markdown 表格并希望导出为 Excel、CSV 或数据分析格式时使用。 输入为 Markdown 表格文本输出为 CSV 文件路径。 --- # Markdown Table to CSV ## 触发场景 - 用户粘贴了一段 Markdown 表格 - 用户想转换为 CSV、Excel 或表格文件 - 用户需要把网页中复制的表格结构化为文件 ## 输入说明 输入一段 Markdown 表格格式如下 | 姓名 | 年龄 | | --- | --- | | 张三 | 25 | ## 输出说明 输出一个 UTF-8 编码的 CSV 文件路径。 ## 注意事项 - 分隔行如 | --- | --- |会被自动跳过 - 不支持表格内换行和合并单元格7.4 第四步手动验证写完后先别急着挂到 Agent 上先用命令行手动测一遍确认脚本本身没问题cd skills/markdown_table_to_csv printf | 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 25 |\n| 李四 | 30 |\n | python3 md2csv.py team.csv cat team.csv预期输出姓名,年龄 张三,25 李四,30脚本没问题后再挂载到 Agent 里用一句自然语言测试比如“把下面这个表格转成 CSV| 姓名 | 年龄 |\n| 张三 | 25 |”看模型是否能正确触发技能并返回文件。8. 验证一个 Skill 好不好的三个指标自己造完 Skill 之后很多人会陷入“能跑就行”的状态。但如果目标是做出稳定的 Agent 应用建议用三个指标来评价一个 Skill 的质量。8.1 触发准确率触发准确率衡量的是该调用时是否调用不该调用时是否沉默。测试方式准备一组包含正例和负例的用户请求跑一轮 Agent统计正确触发比例。常见问题及原因现象可能原因应该触发却没触发描述文件场景写得太窄或关键词不匹配不该触发却触发了描述文件边界不清晰被同类场景误命中触发不稳定描述文件在注册列表中被其他技能干扰8.2 任务完成率任务完成率衡量的是触发之后是否真正完成了用户目标。这一步主要测试实现脚本的健壮性。比如输入格式稍微变化脚本是否还能正常工作。处理各种边界情况是提高完成率的主要工作。8.3 结果稳定度同一个输入多次执行结果是否一致。由于 Skill 的执行代码是确定性的结果稳定度通常很高。如果出现不稳定往往是模型在调用步骤中做了额外操作比如自动修改参数或者脚本依赖了外部环境状态。这三个指标不需要做得特别精细但它们能帮助你快速定位问题触发不准改描述完成了但结果不对改实现结果飘忽检查调用链路。从长期看把 Skill 当作一个小型产品来迭代会让你的 Agent 应用质量有质的提升。9. 常见问题与排查思路在实际操作中新手最容易在下面几个地方卡住这里集中列一下。问题现象可能原因排查方式解决方案Agent 没有调用 Skill描述文件中触发场景写得太窄查看 Agent 日志中模型选择了什么扩展 description覆盖更多用户表达方式Agent 在错误场景调用了 Skill技能边界描述不清晰检查是否有多个技能描述相互干扰收窄 description明确“不适用于”的场景Skill 脚本执行报错依赖库未安装或路径不对手动在终端运行脚本复现报错补齐依赖声明使用绝对路径脚本执行成功但输出格式不对输入解析逻辑有 Bug用边界数据测试脚本增加异常输入处理补充转义逻辑同一请求多次执行结果不一致模型在调用时临时修改了参数查看调用日志中的实际参数在描述文件中明确输出格式降低模型自由度中文内容变成乱码编码未统一检查脚本和文件保存编码统一使用 UTF-8 编码写入 CSV 时指定 encodingutf-8如果你第一次挂载后 Agent 没反应不要急着改代码。先做一个动作打开 Agent 的调试日志看模型在拿到用户输入后到底有没有“看到”你的 Skill 描述。很多时候问题是出在注册环节——描述根本没被加载模型自然不知道有这个技能可用。这里补充几个排查顺序的建议按优先级走先确认 Skill 目录和描述文件能被框架扫描到。再确认描述文件内容能被模型看到。最后确认脚本本身可以独立运行。大部分问题都出在前两步。10. 最佳实践从玩具到生产级 Skill 的工程建议如果只是个人学习和 Demo上面这些内容已经够了。但如果你想在公司项目里真正落地 Agent Skills下面这些工程化建议值得提前看。10.1 描述文件是核心资产要投入足够精力很多开发者把大部分时间花在实现脚本上描述文件随便写几句。这是个常见误区。实际操作中模型能不能正确触发技能决定性的就是描述文件。写描述文件时建议遵循“场景列表 输入输出示例 反例说明”结构。场景列表帮助模型匹配输入输出示例让模型知道怎么传参反例说明能避免误触发。10.2 每个 Skill 保持单一职责一个 Skill 只做一件事并把它做好。如果你发现一个 Skill 的描述里要写“如果……又如果……”的分支说明它可能承担了太多职责拆成两个更合适。单一职责的好处不仅在于模型更容易触发也让测试和维护变得简单。一个只做 Markdown 转 CSV 的技能和一个既做转换又做数据清洗还能生成报告的技能前者的稳定性和可维护性会高得多。10.3 做好日志与可观测性生产环境中Skill 的调用日志非常关键。建议至少记录以下内容用户原始输入模型选择了哪个 Skill传入 Skill 的参数脚本执行耗时输出结果摘要异常堆栈信息有了这些日志才能快速定位是触发问题、参数问题还是脚本问题。10.4 安全边界与权限控制Skill 本质上是让模型具备了执行代码的能力这在带来效率的同时也带来了风险。在工程化落地时必须注意最小权限原则Skill 脚本只申请完成当前任务所需的最小权限尽量不提供通用 shell 能力。输入校验对用户传入的参数做严格校验防止通过参数注入恶意内容。资源限制给脚本执行设置超时和资源配额避免失控。审计生产环境要能回溯哪个用户、在什么时间、触发了哪个技能。10.5 版本管理与灰度发布Skill 会随着业务需求迭代版本管理不能忽略。建议描述文件中增加版本号字段在注册表里记录版本变更。上线新版本时先小流量灰度观察触发准确率和任务完成率稳定后再全量。10.6 通过示例降低模型理解成本描述文件中的示例是降低模型理解成本最有效的手段。尤其当输入格式比较复杂时一定要附上“输入长什么样、输出长什么样”的完整示例。模型不需要猜自然就不容易出错。10.7 先复用以再造动手造 Skill 之前先去社区和框架仓库里找找有没有现成的。很多通用任务文件转换、请求抓取、数据清洗、格式处理已经有成熟实现。站在别人的肩膀上把时间花在你业务真正独特的逻辑上才是合理的资源分配。11. 给新手的 1 小时练习计划既然标题承诺了“1小时从会用到会造”这里给出一个可以直接照着做的时间分配前 10 分钟通读本文第 2 节和第 3 节理解 Agent Skills 与 Tool、Workflow 的区别。第 1125 分钟动手运行第 5 节的md2csv.py示例脚本熟悉 Skill 的文件结构和描述文件格式。第 2640 分钟把 Skill 挂载到你自己选的 Agent 框架或参考第 6 节的伪代码示例跑通一次“自然语言 → 技能触发 → 输出文件”的完整流程。第 4155 分钟按照第 7 节的步骤自己改造一个 Skill。不一定是 Markdown 转 CSV也可以换成 JSON 转 YAML、文本清洗、关键词抽取等更贴合你日常工作的小任务。最后 5 分钟用第 8 节的三个指标测试一下你刚造的 Skill 触发准确率如何并想清楚下一步改哪里。这个计划不需要复杂的硬件或大型模型只要有一个能调用大模型 API 的环境就能完成。重点是完整体验一遍“理解一个 Skill、挂载一个 Skill、制造一个 Skill”的过程。练完之后你可以继续深入的方向有三个一是研究主流 Agent 框架中 Skills 的底层调度实现二是为你的业务场景设计一套完整的技能库体系三是关注社区里高 Star 的 Skill 项目学习优秀描述文件的设计思路。Agent Skills 并不神秘它本质上是工程化思想的产物把不确定的模型推理和确定性的代码执行结合起来让 Agent 真正变得可靠。掌握它你离做出一个“真正能干活”的 Agent 应用就不远了。 Agent Skills实战：从理解原理到动手创建自己的技能包
从“AI 很聪明但让它干点具体活还是费劲”这个感受聊起。过去一年越来越多开发者开始接触 Agent 开发。试过的朋友大多有类似体验大模型本身挺聪明写 Prompt 也能写出像模像样的方案可真让它去“完成一件完整任务”比如自动整理一份数据表格、批量处理文件、定时抓取网页信息就经常跑偏要么缺步骤要么格式不对。问题通常不出在模型上而是出在“模型缺少完成这项任务的具体方法”。你光告诉一个实习生“去把数据整理好”他也会一脸茫然你得告诉他用什么工具、按什么顺序、输出成什么格式。这一整套“做事的固定套路”在 Agent 体系里就是 Agent Skills。这篇文章不绕弯子目标很明确用一小时从理解 Agent Skills 是什么到能读懂别人的 Skill再到自己动手造一个可用的 Skill。文章不会涉及太多抽象理论重点放在可以直接落地的结构和代码上。先给一个判断Agent Skills 是 Agent 从“演示级”走向“可用级”的关键门槛。模型负责“想”Skill 负责“会做”。谁先把技能沉淀成标准模块谁就能大幅降低 Agent 的开发成本。1. 为什么突然都在聊 Agent Skills最近一段时间Agent Skills 的热度明显上升相关讨论也从概念层慢慢转向实战层。这背后的技术变化其实很直接早期 Agent 主要靠“大模型 Prompt”驱动本质是一个推理框架。你告诉模型目标它自己拆步骤自己决定调用哪些工具。这套思路做 Demo 没问题但要上真实业务就会暴露出两个麻烦第一模型每次都在“临场发挥”同样的任务可能每次执行顺序都不一样结果不稳定第二业务里的很多操作是有固定套路的比如“先校验数据再清洗再统计最后出报告”这些流程不该让模型每次重新发明一次。Agent Skills 要解决的问题就是把“固定套路”沉淀成可复用的能力模块。你可以把它理解成给 Agent 配备的“岗位技能包”。一个技能包封装了某个任务领域的完整方法包括什么时候用、怎么用、输入什么、输出什么。模型只需要识别当前任务适合调用哪个技能然后按技能中定义的方法执行即可。从产业链看主流 AI 厂商和开源社区都在往这个方向使劲虽然具体叫法可能不同但核心理念一致把能力封装成标准模块供 Agent 调用。对普通开发者来说这意味着一个新的机会点——你不需要从零训练模型也能通过编写高质量 Skill 成为 Agent 生态里的“能力供应商”。这个变化对两类人特别有价值业务开发人员把公司内部复杂业务流程封装成 Skill减少重复开发。普通使用者通过组合现成 Skill让通用 Agent 完成自己领域的专业任务。一句话总结Agent Skills 不是新概念而是 Agent 应用走向工程化的必然产物。2. Agent Skills 到底是什么用一个比喻来理解。假设你是一家公司的老板Agent 是你的一个新员工。大模型是这个员工的“大脑”很聪明知识面广但没经验。你给他安排任务他大概率能听懂但具体操作未必专业。这时候你需要给他配“岗位手册”手册里清楚写着这类任务的标准步骤是什么、第一步做什么、遇到异常怎么处理、最终交付什么格式。Agent Skills 就是这个岗位手册只不过它不止是给人看的文字而是能被模型读取、能配合脚本执行的结构化文件。从实现角度看一个典型的 Agent Skill 通常包含三部分组成部分职责类比描述文件如 SKILL.md告诉模型什么时候用、怎么用、输入输出是什么岗位手册实现脚本/代码真正执行任务逻辑员工的手艺依赖与配置声明声明运行环境和依赖库工具条件模型在执行任务时会先阅读描述文件判断当前任务是否匹配这个技能如果匹配模型就会按照描述中说明的方式来调用实现脚本把结果处理后反馈给用户。这个机制听起来复杂但设计上有一个关键原则只有描述部分需要模型理解执行部分仍然是确定性代码。换句话说Skill 把“模型的灵活性”和“代码的确定性”结合在了一起。模型负责决策代码负责执行。这也正是它稳定可靠的原因。那为什么要单独做一层 Skill而不是把所有逻辑都写进系统 Prompt核心原因是复用和隔离。系统 Prompt 会随着项目膨胀变得难以维护而且不同任务混杂在一起模型容易“精神分裂”。Skill 做成了独立模块按需加载哪个任务匹配哪个技能边界清晰开发和测试都能单独进行。3. Agent、Agent Skill、Tool、Workflow 到底什么区别很多初学者会把 Agent Skills 和 Tool、Workflow 混为一谈这里必须把概念边界说清楚。3.1 Tool工具Tool 是 Agent 可以调用的单一函数或接口。它解决的是“某一个动作怎么做”的问题。比如一个get_weather(city)函数输入城市名返回天气数据。它动作单一、职责明确没有复杂的流程判断。3.2 Skill技能Skill 是“一组能力的封装”它通常包含使用场景描述 流程步骤 一个或多个底层调用。它解决的是“一类任务怎么完成”的问题。比如“周报生成”这个 Skill内部可能包含数据读取、指标计算、文本生成、格式排版四个步骤模型只需要描述目标Skill 内部按流程执行。3.3 Workflow工作流Workflow 是多个步骤的固定编排通常面向一个完整业务场景步骤之间的流转关系是提前定义死的。比如“每天早上 9 点抓取数据 → 清洗 → 生成日报 → 发到群里”。它强调流程的确定性适合稳定、重复、不太需要模型判断的任务。三者可以这样对比概念作用范围决策方式复用粒度典型例子Tool单一动作基本无决策函数级发送 HTTP 请求、读取文件Skill一类任务模型判断何时用任务级数据分析、文档转换、周报生成Workflow完整业务流程流程固定业务级每日数据监控、定时发布在实际项目中三者常常组合使用。Workflow 在宏观上编排流程Skill 在关键节点提供专业能力Tool 则是 Skill 内部的底层操作单元。很多刚接触 Agent Skills 的人会有一个误区觉得 Skill 就是“把多个 Tool 写在同一个文件里”。其实区别在于Skill 不只是动作的组合它更强调“对任务的理解”——描述清楚什么场景下用、怎么用、输出什么。好的 Skill 能让模型一目了然差的 Skill 即使代码逻辑正确模型也可能在错误场景调用它。4. 核心原理模型如何“学会”使用一个 Skill理解 Skill 的工作机制关键要理解模型是怎么“阅读”和“选择”技能的。在 Skill 机制中模型并不是预先把所有技能代码加载到大脑里。更常见的做法是系统把已注册 Skill 的描述信息名称、使用场景、输入输出格式提供给模型推理模型根据用户当前需求从候选技能中挑选匹配项。一个形象的类比你打开手机应用商店看到几十个 App 的图标和简介你不会把所有 App 都下载下来而是根据当前需求挑选一个下载安装。模型的技能选择也类似它先在“技能列表”里做匹配选中后再把对应实现拉起来执行。所以Skill 描述文件写得清不清楚直接决定模型会不会正确调用它。一个合格的 Skill 描述文件通常需要回答四个问题这个技能解决什么问题什么场景下应该调用它需要什么输入以什么格式给返回值是什么以什么格式返回如果描述模糊模型就会犹豫或误判。比如一个“数据转换”技能如果描述里没写清楚是“Markdown 转 CSV”模型可能在用户问“帮我处理表格”时错误调用最终产出不符合预期。实现侧的逻辑就简单多了。一旦模型确定要调用某个技能系统执行的就是确定性代码按部就班地跑脚本、传参数、接收输出。这也是 Skill 机制比“纯 Prompt 驱动”更稳定的原因决定用哪个方法交给模型方法本身交给代码。5. 第一步读懂一个现成 Skill 的结构会用既然要“会用”第一步是能读懂一个现成的 Skill。目前社区里常见的 Skill 组织方式通常是一个目录里面至少包含描述文件和实现文件。下面是一个典型的目录结构示例skills/ └── markdown_table_to_csv/ ├── SKILL.md └── md2csv.py其中SKILL.md是这个技能的名片也是模型判断调用时最重要的依据。5.1 SKILL.md 描述文件示例--- name: markdown_table_to_csv description: 将 Markdown 格式的表格转换为标准 CSV 文件适用于 Excel 打开、数据分析等场景。 input: 一段包含 | 分隔的 Markdown 表格文本。 output: 一个 CSV 文件路径。 --- # Markdown Table to CSV ## 适用场景 - 用户粘贴了 Markdown 格式的表格 - 用户需要把表格数据用于 Excel 或数据分析工具 ## 输入格式 一段 Markdown 表格文本例如 | 姓名 | 年龄 | 城市 | | --- | --- | --- | | 张三 | 25 | 北京 | ## 输出格式 标准 CSV 文件路径使用 UTF-8 编码。从表面看这份描述文件就是一段普通文档但在 Agent 体系中它就是模型决定“是否调用”的依据。这里有几个关键点name字段是技能的唯一标识要简短且含义明确。description字段是技能的功能摘要模型会优先阅读它。写的时候要覆盖“解决什么问题、输入什么、输出什么”。正文部分可以补充更详细的格式约定供模型在被选中后阅读。5.2 实现脚本示例#!/usr/bin/env python3 文件路径skills/markdown_table_to_csv/md2csv.py 功能读取 stdin 中的 Markdown 表格输出 CSV 文件。 import csv import sys import re def md_table_to_rows(md_text: str): lines [line.strip() for line in md_text.splitlines() if line.strip()] rows [] for line in lines: # 跳过 Markdown 表格的分隔行如 | --- | --- | if re.match(r^\|?[\s:\-|]\|?$, line) and - in line: continue cells [cell.strip() for cell in line.strip(|).split(|)] rows.append(cells) return rows def save_rows_to_csv(rows, output_path): with open(output_path, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerows(rows) if __name__ __main__: md_input sys.stdin.read() output sys.argv[1] if len(sys.argv) 1 else output.csv data_rows md_table_to_rows(md_input) save_rows_to_csv(data_rows, output) print(f已保存 {len(data_rows)} 行数据到 {output})如果有同学想直接验证这段脚本可以这样操作echo | 姓名 | 年龄 | 城市 | | --- | --- | --- | | 张三 | 25 | 北京 | | python3 md2csv.py result.csv如果一切正常屏幕上会打印“已保存 2 行数据到 result.csv”当前目录下会生成result.csv文件。理解这个阶段的关键是描述文件负责“说清楚”实现代码负责“做出来”。两者缺一不可。6. 第二步把 Skill 挂载到 Agent 上跑起来会用读懂了一个 Skill 之后接下来把它挂到 Agent 上跑通这是建立信心的关键一步。不同 Agent 框架对 Skill 的实现差异很大但从设计模式看通常都需要你完成三件事注册 Skill 的描述信息。指定 Skill 的入口命令和输入输出方式。让 Agent 在推理时能“看得到”这些描述。这里不针对某个具体框架写死代码而是给出一个通用思路。下面是一个简化的挂载逻辑示意在实际项目中可替换为对应框架的注册 API。# 文件路径examples/mount_skill.py 伪代码演示将 Skill 挂载到 Agent 的核心思路 实际项目中请根据所选 Agent 框架的 API 调整 import subprocess import json # 1. 技能注册表Agent 运行时会拿这份描述去匹配用户需求 SKILL_REGISTRY { markdown_table_to_csv: { description: 将 Markdown 表格转换为 CSV 文件, entry: python3 skills/markdown_table_to_csv/md2csv.py, input: text/markdown, output: file/csv, }, # ... 其他 Skill } def run_skill(skill_name: str, input_text: str, output_file: str output.csv): 执行指定 Skill 的入口脚本。 这是一个通用示例生产环境请做好参数校验和异常处理。 if skill_name not in SKILL_REGISTRY: raise ValueError(f未知 Skill: {skill_name}) entry SKILL_REGISTRY[skill_name][entry] command entry.split() [output_file] completed subprocess.run( command, inputinput_text, capture_outputTrue, textTrue ) if completed.returncode ! 0: # 真实项目里这里应该记录详细日志 raise RuntimeError(fSkill 执行失败: {completed.stderr}) return completed.stdout if __name__ __main__: # 模拟 Agent 识别到用户需求后调用 markdown_table_to_csv 技能 user_input | 商品 | 价格 |\n| --- | --- |\n| 鼠标 | 99 | result run_skill(markdown_table_to_csv, user_input, goods.csv) print(result)跑通这个流程之后你对“Agent 使用 Skill”的理解就会变得非常具体不再是一个模糊概念而是一条完整链路用户提出问题 → 模型理解意图 → 在技能注册表中匹配 → 执行技能脚本 → 返回结果。如果你选的框架已经内置支持 Skill比如某些开源 Agent 项目提供了 Skills 目录约定那实际接入会更简单通常只需要把 Skill 目录放到指定位置在配置里声明启用即可。但无论框架怎么封装背后都是这套“描述 执行”的逻辑。7. 第三步从零动手“造”一个自己的 Skill会造到这一步你已经知道了 Skill 是什么、长什么样、怎么挂载。接下来就是标题里“会造”这个目标了。这里我们造一个实用的小技能把一段 Markdown 表格文本转换成 CSV 文件。之所以选这个是因为它足够简单、贴近日常办公而且能完整展示一个 Skill 从设计到落地的全过程。7.1 第一步定义能力边界写代码之前先明确你的 Skill 负责什么、不负责什么。负责读取 Markdown 表格文本提取表头和行数据生成 CSV 文件。不负责处理复杂格式如单元格内换行、生成图表、做数据分析。为什么明确边界很重要因为描述文件写得太宽模型会在不合适的场景调用它最后产出不理想。边界收窄一些反而能提高触发的准确性。7.2 第二步编写实现脚本这里直接使用前面第 5 节里那个md2csv.py脚本。它在真实场景里能跑通基础的 Markdown 表格转换够用且不复杂。7.3 第三步编写 SKILL.md 描述文件描述文件是整个 Skill 的灵魂。写的时候站在模型的角度思考如果我是大模型看到这段描述能不能明确判断“该用它”--- name: markdown_table_to_csv description: 将 Markdown 格式的表格转换为标准 CSV 文件。 当用户提供包含 | 分隔符号的 Markdown 表格并希望导出为 Excel、CSV 或数据分析格式时使用。 输入为 Markdown 表格文本输出为 CSV 文件路径。 --- # Markdown Table to CSV ## 触发场景 - 用户粘贴了一段 Markdown 表格 - 用户想转换为 CSV、Excel 或表格文件 - 用户需要把网页中复制的表格结构化为文件 ## 输入说明 输入一段 Markdown 表格格式如下 | 姓名 | 年龄 | | --- | --- | | 张三 | 25 | ## 输出说明 输出一个 UTF-8 编码的 CSV 文件路径。 ## 注意事项 - 分隔行如 | --- | --- |会被自动跳过 - 不支持表格内换行和合并单元格7.4 第四步手动验证写完后先别急着挂到 Agent 上先用命令行手动测一遍确认脚本本身没问题cd skills/markdown_table_to_csv printf | 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 25 |\n| 李四 | 30 |\n | python3 md2csv.py team.csv cat team.csv预期输出姓名,年龄 张三,25 李四,30脚本没问题后再挂载到 Agent 里用一句自然语言测试比如“把下面这个表格转成 CSV| 姓名 | 年龄 |\n| 张三 | 25 |”看模型是否能正确触发技能并返回文件。8. 验证一个 Skill 好不好的三个指标自己造完 Skill 之后很多人会陷入“能跑就行”的状态。但如果目标是做出稳定的 Agent 应用建议用三个指标来评价一个 Skill 的质量。8.1 触发准确率触发准确率衡量的是该调用时是否调用不该调用时是否沉默。测试方式准备一组包含正例和负例的用户请求跑一轮 Agent统计正确触发比例。常见问题及原因现象可能原因应该触发却没触发描述文件场景写得太窄或关键词不匹配不该触发却触发了描述文件边界不清晰被同类场景误命中触发不稳定描述文件在注册列表中被其他技能干扰8.2 任务完成率任务完成率衡量的是触发之后是否真正完成了用户目标。这一步主要测试实现脚本的健壮性。比如输入格式稍微变化脚本是否还能正常工作。处理各种边界情况是提高完成率的主要工作。8.3 结果稳定度同一个输入多次执行结果是否一致。由于 Skill 的执行代码是确定性的结果稳定度通常很高。如果出现不稳定往往是模型在调用步骤中做了额外操作比如自动修改参数或者脚本依赖了外部环境状态。这三个指标不需要做得特别精细但它们能帮助你快速定位问题触发不准改描述完成了但结果不对改实现结果飘忽检查调用链路。从长期看把 Skill 当作一个小型产品来迭代会让你的 Agent 应用质量有质的提升。9. 常见问题与排查思路在实际操作中新手最容易在下面几个地方卡住这里集中列一下。问题现象可能原因排查方式解决方案Agent 没有调用 Skill描述文件中触发场景写得太窄查看 Agent 日志中模型选择了什么扩展 description覆盖更多用户表达方式Agent 在错误场景调用了 Skill技能边界描述不清晰检查是否有多个技能描述相互干扰收窄 description明确“不适用于”的场景Skill 脚本执行报错依赖库未安装或路径不对手动在终端运行脚本复现报错补齐依赖声明使用绝对路径脚本执行成功但输出格式不对输入解析逻辑有 Bug用边界数据测试脚本增加异常输入处理补充转义逻辑同一请求多次执行结果不一致模型在调用时临时修改了参数查看调用日志中的实际参数在描述文件中明确输出格式降低模型自由度中文内容变成乱码编码未统一检查脚本和文件保存编码统一使用 UTF-8 编码写入 CSV 时指定 encodingutf-8如果你第一次挂载后 Agent 没反应不要急着改代码。先做一个动作打开 Agent 的调试日志看模型在拿到用户输入后到底有没有“看到”你的 Skill 描述。很多时候问题是出在注册环节——描述根本没被加载模型自然不知道有这个技能可用。这里补充几个排查顺序的建议按优先级走先确认 Skill 目录和描述文件能被框架扫描到。再确认描述文件内容能被模型看到。最后确认脚本本身可以独立运行。大部分问题都出在前两步。10. 最佳实践从玩具到生产级 Skill 的工程建议如果只是个人学习和 Demo上面这些内容已经够了。但如果你想在公司项目里真正落地 Agent Skills下面这些工程化建议值得提前看。10.1 描述文件是核心资产要投入足够精力很多开发者把大部分时间花在实现脚本上描述文件随便写几句。这是个常见误区。实际操作中模型能不能正确触发技能决定性的就是描述文件。写描述文件时建议遵循“场景列表 输入输出示例 反例说明”结构。场景列表帮助模型匹配输入输出示例让模型知道怎么传参反例说明能避免误触发。10.2 每个 Skill 保持单一职责一个 Skill 只做一件事并把它做好。如果你发现一个 Skill 的描述里要写“如果……又如果……”的分支说明它可能承担了太多职责拆成两个更合适。单一职责的好处不仅在于模型更容易触发也让测试和维护变得简单。一个只做 Markdown 转 CSV 的技能和一个既做转换又做数据清洗还能生成报告的技能前者的稳定性和可维护性会高得多。10.3 做好日志与可观测性生产环境中Skill 的调用日志非常关键。建议至少记录以下内容用户原始输入模型选择了哪个 Skill传入 Skill 的参数脚本执行耗时输出结果摘要异常堆栈信息有了这些日志才能快速定位是触发问题、参数问题还是脚本问题。10.4 安全边界与权限控制Skill 本质上是让模型具备了执行代码的能力这在带来效率的同时也带来了风险。在工程化落地时必须注意最小权限原则Skill 脚本只申请完成当前任务所需的最小权限尽量不提供通用 shell 能力。输入校验对用户传入的参数做严格校验防止通过参数注入恶意内容。资源限制给脚本执行设置超时和资源配额避免失控。审计生产环境要能回溯哪个用户、在什么时间、触发了哪个技能。10.5 版本管理与灰度发布Skill 会随着业务需求迭代版本管理不能忽略。建议描述文件中增加版本号字段在注册表里记录版本变更。上线新版本时先小流量灰度观察触发准确率和任务完成率稳定后再全量。10.6 通过示例降低模型理解成本描述文件中的示例是降低模型理解成本最有效的手段。尤其当输入格式比较复杂时一定要附上“输入长什么样、输出长什么样”的完整示例。模型不需要猜自然就不容易出错。10.7 先复用以再造动手造 Skill 之前先去社区和框架仓库里找找有没有现成的。很多通用任务文件转换、请求抓取、数据清洗、格式处理已经有成熟实现。站在别人的肩膀上把时间花在你业务真正独特的逻辑上才是合理的资源分配。11. 给新手的 1 小时练习计划既然标题承诺了“1小时从会用到会造”这里给出一个可以直接照着做的时间分配前 10 分钟通读本文第 2 节和第 3 节理解 Agent Skills 与 Tool、Workflow 的区别。第 1125 分钟动手运行第 5 节的md2csv.py示例脚本熟悉 Skill 的文件结构和描述文件格式。第 2640 分钟把 Skill 挂载到你自己选的 Agent 框架或参考第 6 节的伪代码示例跑通一次“自然语言 → 技能触发 → 输出文件”的完整流程。第 4155 分钟按照第 7 节的步骤自己改造一个 Skill。不一定是 Markdown 转 CSV也可以换成 JSON 转 YAML、文本清洗、关键词抽取等更贴合你日常工作的小任务。最后 5 分钟用第 8 节的三个指标测试一下你刚造的 Skill 触发准确率如何并想清楚下一步改哪里。这个计划不需要复杂的硬件或大型模型只要有一个能调用大模型 API 的环境就能完成。重点是完整体验一遍“理解一个 Skill、挂载一个 Skill、制造一个 Skill”的过程。练完之后你可以继续深入的方向有三个一是研究主流 Agent 框架中 Skills 的底层调度实现二是为你的业务场景设计一套完整的技能库体系三是关注社区里高 Star 的 Skill 项目学习优秀描述文件的设计思路。Agent Skills 并不神秘它本质上是工程化思想的产物把不确定的模型推理和确定性的代码执行结合起来让 Agent 真正变得可靠。掌握它你离做出一个“真正能干活”的 Agent 应用就不远了。