AI Agent Skill智能体技能现在是AI Agent开发里出现频率最高的词之一但很多人把它当成一段提示词或者当成普通插件的别称。这个误解会在后面带来一个很直接的问题模型到底什么时候该用Skill、用错了怎么排查完全理不清。如果你正准备入门AI Agent开发或者已经写了几个Agent但总感觉能力复用很乱我建议先花一篇文章把Skill的定位、组成和设计方法理解清楚。这篇文章不是从某个框架的官方文档翻译出来的而是把“理解Skill”这件事拆成几个可以直接用的层面它在Agent运行逻辑里的位置、它由哪些部分组成、怎么从零定义一个Skill、接入Agent时怎么判断它是否正常工作、新手最容易踩哪些坑。读完你可以拿一个最简单的任务自己跑通一遍。1. 理解Skill先看它在Agent运行逻辑里的位置1.1 Agent为什么会需要“技能”一个Agent从外部看很像一个“能自己干活”的程序。但把它拆开看核心仍然是大模型在做理解和决策。大模型擅长的是语言生成、语义匹配、常识推理并不擅长稳定执行一套确定的操作步骤。举个例子。你让一个大模型把一段Markdown表格转成CSV文件。如果不做任何约束它可能会给你一段Python代码也可能直接输出一个看起来像CSV的文本块甚至会在文本里加一句“这是转换结果”。原因是模型在“自由生成”不是在“执行任务”。这里的矛盾就在于Agent要稳定就必须减少大模型的自由发挥空间。Skill就是用来补这部分确定性的。我一般会把Skill理解成“给模型的一块能力封装”。模型不需要知道内部怎么实现它只需要知道什么情况下可以调用这个能力、需要传哪些参数、调用后返回什么结果。真正的执行逻辑比如脚本、命令、API请求都封装在Skill内部。1.2 Skill、Tool、Plugin、Workflow之间的边界很多人一上来就混淆这几个概念这里先给一个通用边界。Tool粒度更细。它通常是一个单一动作比如“读取文件”“调用某API”“执行一条SQL”。模型在对话过程中按需调用。Skill粒度在Tool之上。它通常对应一个完整任务比如“把Markdown转成CSV”“把文章批量生成摘要”“整理一份会议纪要”。Skill内部可能包含多个步骤也可能在内部调用Tool。Plugin更偏平台侧的扩展机制。不同框架对Plugin的定义差别很大有的Plugin只是一个打包分发单元里面可以包含多个Skill或Tool。Workflow强调流程编排。它的执行路径往往是固定的、可预测的适合“每步做什么都很明确”的业务场景。Skill则更强调“让模型根据场景按需调用”。这里可以看一张简表概念粒度通常包含的内容解决的问题Tool细一个函数、一个接口调用单一动作Skill中描述、输入输出协议、执行逻辑、校验完整任务Plugin偏平台多个能力或资源的打包分发单元能力集成Workflow大节点、分支、状态流转固定业务流程但要注意这只是一个为了帮助理解而画的通用边界。实际不同Agent框架里Tool和Skill的边界不一定这么清晰有的框架里Skill就是一组Tool的组合有的框架里Plugin和Skill是同一个概念。落地时一定要以具体框架文档为准。1.3 为什么不能把Skill当成一段提示词这是新手最容易犯的错误。提示词的本质是“通过语言影响模型行为”。它只能改变模型下一步输出的概率分布不能保证模型一定按规则执行。你可以在提示词里写“你必须调用某个工具”模型可能调用也可能不调用。你可以在提示词里写“输出必须是JSON”模型可能输出带说明文字的JSON也可能直接跑偏。Skill则不一样。它的执行部分不是模型“想”出来的而是提前写好的脚本或命令。模型只负责选择是否调用、传入什么参数真正的动作由程序完成。这样就把“不稳定的推理”和“稳定的执行”分开了。纯提示词方案还有一个问题不好测试。你很难给一段提示词写单元测试但你可以给一个Skill写测试用例。这一点在Agent项目复杂起来之后尤其重要。2. 把一个Skill拆开看它到底包含什么2.1 元数据和描述让模型知道“什么时候用”一个Skill首先要能被Agent框架发现并且能在大模型的工具选择阶段做出正确决定。所以它通常需要三样最基本的信息名称、描述、版本。名称要短语义要清晰。比如markdown_to_csv就比mdcsv更容易让模型理解。不要用脱离职责的代号。描述是最关键的部分。它不只是给人看的更是给模型看的。描述写得好不好直接决定模型在遇到相关任务时会不会选中这个Skill。我一般会把描述写成三段式用途这个Skill能做什么。使用条件出现什么特征时应该调用。不适用场景出现什么特征时不应该调用。比如把Markdown格式的表格转换为CSV文件。 当输入内容中包含Markdown表格且用户需要导出为表格文件时使用。 如果输入只是普通文本列表没有表头或分隔线不要使用。这样写比“Markdown转CSV”好用得多。因为模型做选择时需要的是“条件匹配”不是单纯的关键词匹配。2.2 输入输出协议让调用不出歧义Skill要能被模型正确调用必须把输入输出定义清楚。输入部分通常用JSON Schema描述。要写明每个字段的类型、是否必填、默认值、字段含义。如果输入是文本要明确传原文还是传文件路径。如果输入是文件要明确文件路径规则。如果字段定义模糊模型就会猜一猜就容易出错。输出部分同样重要。不少新手只关注输入忽略了输出协议。结果Skill执行成功了但Agent拿不到结构化结果仍然无法继续处理。输出至少要约定成功时返回什么、失败时返回什么错误码和错误信息。一个比较完整的基础输入协议长这样{ type: object, properties: { markdown_text: { type: string, description: 包含Markdown表格的原文 }, output_path: { type: string, description: 输出的CSV文件路径 } }, required: [markdown_text, output_path] }字段越明确模型填参时越不容易踩坑。尤其是字段的description看起来不是代码但对调用成功率影响很大。2.3 执行逻辑真正干活的代码Skill的描述部分只负责“让模型理解”真正的执行部分必须是确定性的脚本、命令或API调用。写执行逻辑时需要注意几点路径要稳定尽量基于Skill目录的相对路径不要写死一个绝对路径。日志要可读。脚本执行成功或失败都要在标准输出或日志文件里有明确体现。错误要可捕获。不要遇到异常就静默退出要返回明确的错误信息。资源占用要可控。如果处理的是大文件要考虑内存和耗时。这里也不是代码越复杂越好。一个Skill最好只做一件事不要塞进七八个功能。否则出问题时你很难判断是哪个环节失败。2.4 校验和测试保证可复用Skill要能被反复调用就必须有校验和测试。测试用例至少要覆盖三类输入正常输入确认输出结果正确。边界输入比如空字符串、只有表头、分隔行缺少等。错误输入比如格式完全不是Markdown表格。操作顺序我建议这样先在命令行单独跑脚本确认脚本本身能输出正确结果。再通过Agent触发Skill确认模型能正确传入参数。最后连续跑多次确认结果稳定。如果Skill输出不稳定先看日志不要急着改描述。先确认执行逻辑本身有没有问题再考虑是不是模型选错或参数传错。3. 从零定义一个“Markdown转CSV”Skill这一节用一个最简单的任务演示完整流程输入Markdown表格文本输出CSV文件。任务不大但足以把Skill的定义、配置、执行、测试链路跑通。3.1 先定任务边界不要上来就写脚本先把边界说清楚。这个Skill接收什么一段包含Markdown表格的文本。输出什么一个CSV文件。只处理标准Markdown表格也就是包含|分隔和表头分隔行的表格。不处理没有分隔线的普通文本列表不处理复杂嵌套表格。边界越清晰后续写描述和写脚本都越轻松。很多Skill做不好不是代码问题是任务边界一开始就模糊。3.2 定义输入输出输入字段就是两个markdown_textMarkdown原文。output_path输出CSV路径。输出结果约定为成功输出OK: wrote N rows to path。失败标准错误输出ERROR: no markdown table found退出码为1。这样Agent在调用后可以明确判断成功还是失败。3.3 写Skill描述描述可以这样写把Markdown格式的表格转换为CSV文件。 当输入内容中包含以|分隔的Markdown表格且用户需要导出为CSV时使用。 输入必须是完整的Markdown原文输出路径必须是带.csv后缀的文件路径。 如果输入只是普通列表没有表头分隔行不要使用。这里有一个经验描述里的“不要使用”不是废话它能避免模型在模糊场景下误调用。实际测试中加了“不适用场景”之后误触发率会明显下降。3.4 写执行逻辑下面是一个最小可运行的Python脚本示例。注意这是为了演示只支持简单的Markdown表格没有处理转义符。import argparse import csv import re import sys def parse_markdown_table(text: str): rows [] for raw_line in text.strip().splitlines(): line raw_line.strip() if not line.startswith(|): continue cells [cell.strip() for cell in line.strip(|).split(|)] if all(re.fullmatch(r:?-{2,}:?, cell) for cell in cells): continue rows.append(cells) return rows def main(): parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue, helpMarkdown table text) parser.add_argument(--output, requiredTrue, helpCSV output path) args parser.parse_args() rows parse_markdown_table(args.input) if not rows: print(ERROR: no markdown table found, filesys.stderr) raise SystemExit(1) with open(args.output, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerows(rows) print(fOK: wrote {len(rows)} rows to {args.output}) if __name__ __main__: main()这个脚本做了四件事按行拆分、过滤非表格行、跳过Markdown分隔行、写入CSV。真实生产环境里Markdown表格格式会更复杂比如单元格内包含转义竖线、对齐标记、多行内容等。这个脚本只是一个起步版本能帮你理解Skill执行逻辑的形态。3.5 单条测试先在命令行单独跑一遍python md_to_csv.py \ --input | 名称 | 数量 | | --- | --- | | 苹果 | 3 | | 香蕉 | 5 | \ --output out.csv跑完后打开out.csv应该看到三行有效内容表头、苹果行、香蕉行。这一步很重要。脚本没验证成功之前不要放到Agent里去调否则你分不清是脚本问题还是模型传参问题。3.6 放入Agent验证触发脚本跑通后再把它加进Agent的Skill配置里。完整配置结构在不同框架里不一致但大致会有下面这些信息name: markdown_to_csv description: 把Markdown表格转换为CSV文件 version: 1.0.0 input_schema: type: object properties: markdown_text: type: string description: 包含Markdown表格的原文 output_path: type: string description: 输出的CSV文件路径 required: - markdown_text - output_path execute: command: python scripts/md_to_csv.py启动Agent后给一句用户指令比如“帮我把这段Markdown表格转成CSV保存到/data/result.csv”然后观察日志。如果模型没有选中这个Skill不要急着改代码先看日志里到底发生了什么。4. 把Skill接入Agent时需要注意什么4.1 加载方式和目录约定不同Agent框架对Skill的加载方式不一样。有的框架里Skill放在skills目录有的放在plugins目录有的通过manifest.json声明。不要假设所有框架都一样。学习阶段最快的方式是找一个已有示例看清它的目录结构、配置文件字段、脚本入口然后照着复制一份改成自己的任务。还有一个很容易忽略的点配置加载成功不等于模型一定调用。你应该通过框架提供的能力查看当前已加载的Skill列表确认自己的Skill确实进入了候选集。4.2 描述对触发成功率的影响模型选择Skill本质是一个概率决策。描述越模糊误选和漏选概率越高。我给你一个对比弱描述强描述把Markdown转成CSV把Markdown表格转换为CSV文件当输入包含表格且需要导出为CSV时使用处理Excel把xlsx文件中的数据读取并整理成结构化JSON当用户需要提取Excel内容时使用生成摘要对长文本生成200字以内的中文摘要当输入文本超过500字且需要快速了解核心内容时使用不要觉得“处理Excel”已经够清楚了。对模型来说“处理”这个词太泛它不知道是读取、修改、合并还是转格式。描述里必须有明确的触发条件和输出目标。4.3 日志怎么看把Skill接入Agent后最需要盯的是日志。我一般会按这个顺序看有没有出现Skill名称的匹配记录。模型传入的参数是不是符合输入协议。执行脚本有没有报错。Agent有没有正确拿到输出结果。如果第一步就没有匹配记录先改描述不要动执行逻辑。如果第二步参数不对检查输入字段的类型和description是否清楚。如果第三步报错单独在命令行跑脚本复现。如果第四步失败大概率是输出协议和Agent的解析逻辑不匹配。这个排查顺序能避免一个典型问题明明脚本没问题却因为模型没选中Skill导致你反复改代码浪费时间。4.4 安全与权限边界Skill能执行命令、读写文件、调用API能力越强越要控制权限。不要直接加载来源不明的Skill文件尤其是只给了一个压缩包、没有任何文档的Skill。使用前至少确认它执行了什么命令、访问了哪些文件。给Skill传参时也要做校验。如果参数会拼进命令行一定要防止注入。不要把用户输入的原始字符串直接作为命令执行。在团队项目里Skill变更应该像代码变更一样走评审。别让一个Skill悄悄带着高风险命令进入生产环境。这一点很多个人项目不会遇到但一旦做生产级Agent就是必须考虑的边界。5. 新手设计Skill最常见的误区和排查思路5.1 误区一Skill越大越好有人觉得一个Skill能处理的事情越多越强大。实际恰恰相反。Skill职责越单一模型越容易判断“什么时候该用”调试时也越容易定位问题。如果一个Skill描述里要写四五种不同的用途说明它该拆分了。比如“处理文档”这个Skill实际上应该拆成“提取PDF文本”“Markdown转HTML”“生成文档摘要”等多个Skill。5.2 误区二描述随便写写就行描述是模型选择Skill的依据本质上是一种接口文档。描述写得太糙模型会漏选或误选。改进方法很简单给描述增加“使用条件”和“不适用场景”。不要只写“这个Skill能做什么”还要写“什么情况下必须用”和“什么情况下千万别用”。5.3 误区三只写提示词不写执行逻辑如果一个Skill只有一大段提示词没有真正的脚本、命令或API调用那它本质上还是Prompt不是Skill。确实存在一些“纯提示词Skill”但它们的适用范围很窄通常只负责输出格式约束不负责执行动作。凡是涉及文件读写、数据转换、外部系统调用都应该有明确执行逻辑。5.4 误区四不做测试就上线Skill和普通函数一样必须有测试。再简单的Skill也至少要有一个正常样例、一个边界样例、一个错误样例。没有测试的Skill可能在第一次调用时看着正常第二次换一种输入就翻车。等Agent在真实场景里失败时你连回归验证的手段都没有。5.5 误区五忽略输出格式输入协议写得很细输出却只有一个“成功”或“失败”这是常见问题。Agent拿到输出后还要继续处理如果输出格式不统一后续流程很难写。比如输出CSV时不仅要告诉Agent“文件写好了”还要给出路径、行数、字段列表。这些会成为Agent后续判断的上下文。5.6 通用排查顺序当Skill表现不符合预期时我建议按以下顺序排查先看日志中是否出现该Skill的调用记录。如果完全没有说明模型没选它优先改描述。再看传入参数。参数为空、字段传错、类型不对优先检查输入协议和字段描述。再看执行日志。脚本有没有报错、有没有超时、有没有输出异常信息。再看输出结果。结果是否符合输出协议Agent能否正确解析。最后看安全策略。有些框架或环境会拦截命令、限制文件写入导致执行被阻断。很多看起来是“功能问题”的故障实际都是描述问题或参数问题。不要总是怀疑框架有Bug先按链路逐层看。6. 从理解Skill到持续迭代6.1 先用最小版本跑通我第一次接触Skill时也犯过类似错误一上来就想做一个能处理十几种文档格式的复杂Skill结果光是配置就写了一堆最后模型还没调通。现在我更建议换个顺序先做一个极小极简单的Skill比如读取一行文本、转成大写、写入文件。先把“描述-入参-执行-输出-反馈”这条链路跑通再逐步增加复杂度。链路跑通之后你已经掌握了Skill的基本骨架。后面再设计复杂能力无非是往里加执行步骤、加校验、加API调用。6.2 把Skill当代码维护Skill不是“写一次就完事”的配置。它会随着Agent需求变化不断调整描述、参数和脚本。要像维护代码一样维护Skill放进版本管理Skill目录和Agent代码放一起。留版本号方便回滚。写简短的README说明这个Skill解决什么问题、依赖什么环境。每次修改描述或脚本后重新跑一遍测试样例。如果你的Agent项目里有十几个Skill没有版本管理会非常痛苦。你很难知道某个Skill是什么时候改的、为什么改、当前版本是否可复用。6.3 关注Skill生态变化Skill概念现在还在快速演进中。不同框架对Skill的定义、加载方式、编写规范都存在差异市面上也没有一个完全统一的标准。今天学到的通用思路落地到不同框架时可能需要做适配。我的建议是不必追求一步到位先把一个Skill的全流程理解透彻。等生态更清晰后再根据具体平台做迁移和扩展。如果你正在做Agent相关项目可以一边学一边积累自己的Skill库。每完成一个能稳定运行的Skill就保存下来后续新项目直接复用。时间长了你会发现自己真正沉淀下来的不是某段代码而是一套判断“什么时候该封装、怎么封装、怎么验证”的能力。