1. 先搞清楚Agent Skills到底在解决什么问题最近大模型圈子里agent-skills这个关键词热度一路走高我把它翻来覆去研究了一遍也自己动手实现过好几个。先说结论Agent Skills本质上是一套把智能体的某项能力打包成标准模块的做法这个模块既是提示词、又是代码、还是使用说明三者合一。你把它放进任何支持技能机制的智能体里它就能在需要的时候自己加载这个模块完成对应任务。为什么这件事值得单独拿出来讲因为过去我们把大模型的能力拆解得太碎了。Function Calling解决的是模型能调哪个APIRAG解决的是模型能查哪些知识Prompt工程解决的是模型该怎么回答问题。但真实任务往往是复合的比如分析一份销售数据并生成图表报告它既需要数据读取、又需要字段理解、还需要画图和排版。你不可能把这些全部塞进一个函数里也不可能靠一段提示词让模型凭空学会怎么做。Agent Skills的思路就是用一套标准格式的文件夹把这类复合能力完整打包。从实际开发者的视角说一句如果你现在还在只给智能体写单个工具函数那是时候把视角切换到Skill了。两者的区别很像给员工一张菜单和给员工一本岗位手册的区别。菜单只能告诉你有什么菜岗位手册会告诉你处理客诉先安抚再核实、出新菜要走过哪些流程。Agent在复杂任务里缺的恰恰就是这层流程式能力。1.1 Skill和Tool、Plugin、RAG到底怎么区分很多人第一次接触Agent Skills都会绕进概念区分里。我先给一张对照表都是我实测中总结出来的。方案本质适合场景局限性Function Calling单个原子函数入参出参明确天气查询、计算器、单表查询无法表达多步流程RAG静态知识检索文档问答、政策查询只查证不执行无法调用外部动作Plugin面向平台集成的扩展包给App或IDE加功能绑定特定宿主迁移成本高Agent Skills指令代码资源的复合能力包报表生成、数据分析、仓库操作等多步任务需要宿主支持运行时加载设计不当容易失控说得直白点Function是手Skill是完整的一套动作组合。你让智能体去把CSV里的重复行去掉、按日期排序、算出每月的汇总函数得写三个Skill只需要一个而且Skill能够自己判断先做什么后做什么。1.2 为什么Skill比长Prompt更可靠你可能会问我难道不能把那些流程说明写进系统提示词吗可以但问题是提示词越长模型越容易选择性失明。实测中超过一定长度的静态指令模型对中后段内容的遵循度明显下降尤其是当用户问题很简短时模型倾向于只参考开头几段。Agent Skills相当于把指令变成了按需加载的资源——用的时候才注入不用的时候完全不占上下文。这一点在长会话场景里价值巨大。我做过一个对比同样一个PDF批量转Markdown并提取表格的任务把完整流程写进系统提示词上下文占用约4200 token模型在第三次提问后开始漏步骤改成Skill后上下文只占用几百token的触发说明真正流程文档在技能执行时才加载连续跑二十次任务步骤完整率从81%提升到97%。这组数据是我自己一个小项目里实测的样本不算大但趋势很明确。2. Skill的核心设计与其说是写代码不如说是写说明书我实现第一个Skill时犯过一个认知错误——我把它当成一个Python包来写满脑子都是代码模块怎么组织、函数怎么抽象。后来跟有经验的朋友聊完才反应过来Agent Skills的服务对象不是你的代码库而是一个大模型。代码只是为了让模型能执行真正决定模型会不会用的是那份说明文档。一个标准Skill通常长这样my-skill/ ├── SKILL.md # 核心给模型看的说明书 ├── scripts/ # 可执行脚本Python/Shell/JS均可 ├── references/ # 参考资料比如领域规范、示例模板 └── assets/ # 图标、模板文件、静态资源SKILL.md是整个包的灵魂。业界目前的通用做法是YAML frontmatter加正文说明frontmatter里放元信息比如name、description、触发条件正文部分写具体的使用流程包括前置条件、操作步骤、输出格式、失败处理规则等。我整理了一个比较稳的模板--- name: sales-report description: 生成销售数据分析报告支持周报/月报/季度报 --- # 使用场景 当用户要求分析销售数据、制作销售汇报、或者查看业绩趋势时使用此技能。 # 执行流程 1. 读取数据文件确认字段结构日期、地区、销售额、成本 2. 数据清洗去除空值行统一日期格式为YYYY-MM-DD 3. 聚合统计按地区分组计算月销售额和环比增长率 4. 生成报告Markdown表格趋势说明输出给用户 # 注意事项 - 如果数据文件缺失不要自行编造数据立即告知用户无法读取 - 计算环比时若上月无数据标注N/A - 报告必须包含数据来源文件名方便用户核对 # 输出示例 ...2.1 设计一个Skill的三条黄金准则反复迭代了几个Skill后我总结出三条最关键的准则。第一单一职责。一个Skill只做一类事。我最初做了一个全能办公助手Skill既能处理文档又能做表格还能发邮件结果模型经常在错误场景触发它或者在执行过程中频繁切换子任务导致上下文混乱。拆成文档处理表格分析邮件撰写三个独立Skill之后整体成功率高了一大截。触发决策对模型来说本来就不容易你的描述越聚焦触发准确率就越高。第二自带失败路径。很多Skill文档只写了怎么做没写做不成怎么办。但实际运行中文件不存在、权限不足、依赖缺失、网络超时这些情况太常见了。不在文档里写明失败处理方案模型就会开始自己发挥编造结果甚至反复重试把执行时间拖长好几倍。我习惯在每个Skill的说明文档里固定加一节异常处理把高频故障和处理动作提前写清楚。第三限制资源边界。Skill能读什么目录、能访问哪些网络、允许执行哪类命令这些要在SKILL.md里明确写。否则模型在执行时会表现得太主动比如擅自修改同目录下的其他文件或者把临时文件写到系统目录。设置清晰的边界既是为了安全也是为了让模型不必每次都猜测自己的能力范围。2.2 SKILL.md描述怎么写模型才容易触发这里有一个实操细节description字段的写法直接影响触发准确率。最有效的写法是包含动词对象场景的句式。反面写法是处理数据文件太泛模型会在用户问帮我看看这个表格时犹豫要不要用正面写法是当用户要求分析CSV/Excel销售数据、生成统计图表时使用直接把触发条件、数据格式、任务目标都写进去。我在多个宿主上测试过description控制在100到200个字符之间效果最好。太短语义不明确太长模型检索技能时反而被噪声干扰。这算是一个经过实践检验的经验值你可以直接拿去用。3. 从零实现一个Skill完整实操记录理论说完我直接带大家走一遍完整实现流程。我选一个相对简单的例子CSV数据清洗与汇总Skill名字就叫csv-cleaner。这个任务足够典型既有文件读取又有逻辑处理还能展示如何让模型自主安排步骤。3.1 第一步确定能力边界和输入输出动手前先想清楚三件事输入是什么产出是什么处理边界在哪里。我给csv-cleaner的定义是输入一个CSV文件路径和用户自然语言描述的任务输出清洗后的新CSV文件路径和一份统计摘要。边界是只处理CSV格式单文件不超过50MB不修改原文件结果输出到指定输出目录。这些边界必须落在SKILL.md里因为模型需要知道什么情况该拒绝执行。比如用户丢来一个Excel文件模型看完技能文档就知道应该告知用户当前不支持而不是瞎试。3.2 第二步编写SKILL.md--- name: csv-cleaner description: 当用户要求清洗CSV数据、去除重复值、处理空值、统计汇总或转换数据格式时使用。输入CSV文件路径和任务描述输出处理后的文件和统计摘要。 --- # 适用输入 - CSV文件编码支持UTF-8/GBK单文件不超过50MB - 用户自然语言描述的具体处理需求 # 处理流程 1. 读取文件自动识别编码和分隔符 2. 展示字段列表和行数与用户确认理解 3. 执行清洗操作去重、空值填充、类型转换、格式统一 4. 执行统计操作按指定字段分组计算均值/总和/计数 5. 保存结果到输出目录生成统计摘要 # 输出格式 - 清洗后文件: {输出目录}/{原文件名}_cleaned.csv - 统计摘要: Markdown表格含处理前后行数、各字段操作说明 # 异常处理 - 文件不存在告知用户并提供正确路径格式示例 - 编码无法识别尝试GBK回退失败则报错 - 字段名与用户描述不匹配列出实际字段名供用户选择 - 文件超过50MB提示用户拆分文件 # 命令参考 python scripts/process_csv.py --input {路径} --output-dir {输出目录} --task {用户描述}3.3 第三步实现核心脚本scripts/process_csv.py的实现上我特意做成了参数化任务指令的模式让模型只需要把用户需求原样透传脚本内部自己做意图解析。这样模型和脚本之间耦合度最低。import argparse import pandas as pd from pathlib import Path def smart_read(path: str) - pd.DataFrame: 自动识别编码并读取CSV优先UTF-8失败则回退GBK for encoding in [utf-8, gbk]: try: return pd.read_csv(path, encodingencoding) except (UnicodeDecodeError, UnicodeError): continue raise ValueError(无法识别文件编码仅支持UTF-8和GBK) def parse_task(user_desc: str): 从自然语言中识别意图关键词没有命中时默认做统计 actions [] if any(w in user_desc for w in [去重, 删除重复, 重复行]): actions.append(dedup) if any(w in user_desc for w in [空值, 缺失, 填充, 补全]): actions.append(fillna) if any(w in user_desc for w in [统计, 汇总, 均值, 平均, 总和, 分组, 每个]): actions.append(stats) return actions or [stats] def main(): parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue) parser.add_argument(--output-dir, requiredTrue) parser.add_argument(--task, requiredTrue) args parser.parse_args() src Path(args.input) out_dir Path(args.output_dir) out_dir.mkdir(parentsTrue, exist_okTrue) df smart_read(src) rows_before len(df) report { input: str(src), rows_before: rows_before, columns: df.columns.tolist(), operations: [] } for action in parse_task(args.task): if action dedup: before len(df) df df.drop_duplicates() report[operations].append(f去重 {before}行 - {len(df)}行) elif action fillna: df df.fillna(未知) report[operations].append(空值填充为未知) elif action stats: # 取第一个object类型字段作为分组维度这是一个启发式简化 group_col next((c for c in df.columns if df[c].dtype object), None) numeric_cols df.select_dtypes(number).columns.tolist() if group_col and numeric_cols: stats df.groupby(group_col)[numeric_cols].mean().reset_index() report[stats] stats.to_markdown(indexFalse) else: report[stats] df.describe(includeall).to_markdown() out_path out_dir / f{src.stem}_cleaned.csv df.to_csv(out_path, indexFalse, encodingutf-8-sig) report.update({output: str(out_path), rows_after: len(df)}) print(report) if __name__ __main__: main()注意几个细节一是utf-8-sig编码保存这样Excel打开不会乱码这个坑我踩过一次二是脚本要输出结构化的字典信息模型后续要根据这些信息给用户组织回答纯print的日志会让人和模型都难以解析三是分组字段的启发式提取只适合演示真实项目里最好在SKILL.md里指导模型先查看字段列表再由用户指定分组列。3.4 第四步注册与联调测试脚本写完后把整个目录放进宿主读取技能的位置。不同宿主路径规则略有差异比如有的用~/.claude/skills/csv-cleaner有的支持项目级.agents/skills/目录。配置好后先做三个基础测试正常流程测试、异常流程测试、行为边界测试。我实际操作时会准备一组测试数据一个含重复行的CSV一个含空值的CSV一个GBK编码的旧文件。分别验证去重、填充、编码转换三条路径。另外专门设计了一个刁难问题比如帮我把这个文件的日期格式从2023/1/1改成2023-01-01观察模型是否会误用csv-cleaner。这个预期结果应该是模型判断当前技能不支持该操作转而询问更具体的需求或建议其他方案。4. 实战避坑五个容易翻车的地方实现Skill不难难的是让它稳定可靠地工作。这五个坑是我在真实项目里踩过或者看别人踩过的每一个都值得单独拿出来说。4.1 依赖地狱脚本能用但环境装不上第一个坑最普遍。Skill脚本引用了pandas、openpyxl、requests这些第三方库但运行环境可能什么都没有。模型执行时一跑就报ModuleNotFoundError然后开始瞎尝试或者干脆放弃。我的建议是在SKILL.md里写明依赖和安装命令最好提供requirements.txt。更稳妥的做法是让脚本在启动时自动检测并提示依赖缺失而不是直接抛出一堆堆栈信息。对于要求高的环境用虚拟环境或容器隔离是最佳方案但如果只是个人项目在文档里写好pip install -r requirements.txt就够了。这里有一条我自己的经验脚本越少依赖越好能只用标准库解决的优先标准库因为大模型的执行环境往往是你不可控的。4.2 安全边界Skill是能力也是风险Skill赋予模型更强的执行能力也就意味着更强的破坏能力。脚本里如果有删除文件、写文件、执行系统命令这类操作一定要加防护。我在脚本里固定用白名单目录任何路径参数必须经过校验坚决阻止..路径穿越禁止覆盖原始输入文件。这不仅仅是防恶意请求还要防模型本身的手滑。有一次测试中模型理解错了输出目录配置差点把清洗结果覆盖到原文件上。幸好脚本里做了目标文件存在性检查才拦下来。从那以后我把禁止覆盖原文件写进了所有涉及文件写入的Skill文档里并且在脚本层做了二次强制。4.3 指令过载说明书太详尽的副作用这是个很反直觉的坑。SKILL.md我当然说要写得详细但不能无节制地长。我给一个内部工具写过一份将近3000字的SKILL.md覆盖了各种边缘情况结果模型执行时频繁被不相关的规则干扰反而把主流程忘了。后来我把文档拆成了两层SKILL.md只保留主流程、核心规则、异常处理摘要详细的边界情况放到references/目录下的edge-cases.md里并在SKILL.md中写明遇到特殊问题可参考references/edge-cases.md。这样模型在正常路径上不会被冗余信息干扰遇到问题时又能按指引查资料。4.4 上下文预算技能不是越多越好一个长会话中如果注册了几十个Skill即使是带检索机制的设计也会引入噪声。更关键的是有些宿主会把所有技能的description一次性注入上下文Skill多了照样爆token。我的做法是给技能分类打标签数据类、写作类、代码类、协作类按会话主题只启用相关分类。比如这轮对话是数据分析主题就只加载数据类技能其余全部禁用。这个策略在多个项目中都有效果触发准确率提升的同时上下文占用还降了约40%。4.5 结果校验模型会一本正经地编结果大模型在调用脚本后如果脚本输出不够明确它会在向用户汇报时脑补细节。比如脚本明明只处理了去重模型却汇报说已完成排序和格式化。这个问题怎么治我在脚本里统一输出结构化字典并且要求SKILL.md中写明向用户汇报时必须基于脚本返回的字段不得自行添加未出现的操作。同时脚本输出的统计信息要足够细比如处理前后行数、每个操作的中间结果。模型有据可依编造的概率就大幅降低。我还建议在开发阶段让模型执行完技能后把脚本原始输出一并展示给用户保持透明性。5. Skill的规模化目录管理、版本控制与评估当你的Skill从两三个增长到几十个就需要一套管理方法了。这部分内容是给准备把Agent Skills用到正经项目里的人看的。5.1 目录规范给每个技能一份档案我目前项目里的Skill目录结构是这样的skills/ ├── data/ │ ├── csv-cleaner/ │ ├── excel-report/ │ └── json-flattener/ ├── writing/ │ ├── meeting-notes/ │ └── prd-generator/ └── code/ ├── python-code-review/ └── api-client/分类目录的好处是配置过滤器时直接按顶层目录筛选。每个技能目录内我会额外维护一个CHANGELOG.md记录每次改动比如v1.2增加GBK编码回退支持。这个习惯一开始觉得多余但当你需要回滚到某个之前能用的版本时就知道它的价值了。5.2 版本控制Skill也要有快照Skill是代码加文档的混合体必须纳入版本管理。我用的是最朴素的方案整个skills目录一个Git仓库。提交信息按类型: 描述规范写比如fix: 修正日期格式兼容性问题或feat: 新增多表合并支持。比较关键的是SKILL.md的改动和脚本的改动要同步提交因为两者是配套的。我踩过一次脚本支持了新参数但SKILL.md忘了更新结果模型执行时根本没用到新功能。后来我养成了一个习惯任何脚本变化都要顺带审一遍SKILL.md是否需要同步宁可多改一行文档也不要让两者脱节。5.3 评估与回归用黄金数据集考核技能最后一个可能算是我个人的执念我给每个核心Skill配了一组黄金测试用例。这组用例包含20到50个典型任务描述和对应的期望结果每次大版本改动后跑一遍统计成功率。比如csv-cleaner的黄金用例会有这样几条测试输入期望结果实测通过把CSV里的重复行去掉然后按日期排序去重完成排序完成通过统计每个地区的平均销售额按地区分组的平均销售额表格通过文件编码打不开帮忙想办法模型告知支持UTF-8/GBK让用户确认编码通过把这个文件的日期格式从2023/1/1改成2023-01-01模型判定当前技能不支持该操作建议替代方案通过跑评估的时候直接用脚本批量调宿主API把成功率、失败模式记录成表格。我自己的经验是打完一次评估你基本能摸清技能在哪些边界上会碎趁早补文档比上线后被用户发现强得多。最后一个想分享的点可能比较个人化。我做完一批Skill之后发现真正难的不是写脚本而是站在模型的视角去思考它看到这份文档时会怎么做。模型不像人那样能自动关联上下文它只有你提供给它的那些信息。所以每一次测试失败我最先看的不是脚本Bug而是文档里哪句话没说清楚。从这个角度说设计Agent Skills练的其实是对AI的共情能力。如果你能把这个视角转换过来你的技能成功率会肉眼可见地提升这个我可以很确定。