最近GitHub上带skills标签的仓库肉眼可见地多了起来skills这个词从原本模糊的技能含义迅速收敛成了一个具体的技术概念给AI agent打包好的工作技能。Claude、Codex这些主流产品都把它做成了官方能力社区里也冒出了大量可以直接下载的skills库从前端开发规范、论文润色、数据分析到分镜脚本生成什么方向都有。这篇内容我想从实操角度把skills聊透它到底是什么和function calling有什么区别怎么写一个自己的skill安装调试会踩哪些坑以及怎么在项目里安全地用起来。不管你是想给AI配个岗位说明书的产品经理还是想把重复劳动交给agent的前端、数据分析师看完应该都能直接上手。1. skills是什么为什么突然成了Agent圈的焦点你可以把skill理解成打包好的职业技能说明书工具箱一份Markdown文档说明操作流程和规范一两个脚本或资源文件负责具体执行。AI agent接到相关任务时自己会去翻这份说明书按里面写的规则来干活。这和每次都在提示词里反复交代完全不同相当于给AI配了一整套企业SOP和工具库。我前阵子带了个实习生做事认真但是每回都得把规则重新讲一遍先做格式检查再统一编码最后按模板输出。skills解决的正是这个场景——你把规则写一遍AI以后每次都按这套规则执行。而且它不依赖某个特定模型Claude能用、Codex能用很多本地部署的agent框架也在兼容这一套规范可复用性比想象中强很多。1.1 一个能自己翻说明书的AI助手生活化的类比是这样的以前用AI就像招了个聪明但没经验的新人你每次都得从头交代先做A再过滤B按C的格式输出稍微漏一句结果就跑偏。有了skills相当于给这个新人配了一整套企业SOP和工具库。它接到处理这批数据的任务时会自己去翻《数据处理SOP》看到先做格式检查再做去重最后生成摘要然后照着执行。这个自己翻说明书的机制是关键。skill目录通过文件系统暴露给agentagent可以浏览、打开、分析目录里的文件。它看到技能描述、步骤说明、示例输出甚至能运行你提供的脚本。这意味着它不只是在记住你的要求而是真正在学习一套工作方法。我第一次跑通自家skill的时候特意把提示词写得很模糊只说了把项目里的CSV按规矩处理一下。AI自己找到了数据处理skill按SKILL.md里的流程走了一遍最后还主动跑了我放在scripts目录里的校验脚本发现两个文件编码有问题直接标注出来问我要不要自动修复。那一刻我是真觉得这已经不是聊天机器人了这是一个有工作习惯的同事。1.2 skills和function calling到底差在哪很多人会问function calling不是早就能让AI调用工具了吗有必要再搞一套skills吗这两个东西看着像定位其实完全不同。function calling偏精确调用你预先定义好函数签名、参数类型AI根据用户问题决定调用哪个函数传什么参数拿返回结果。它适合对接API这种稳定边界比如查天气、下单、发邮件参数是结构化的返回格式也是固定的。skills偏过程学习它不一定有明确的函数签名也不用你预设所有调用参数。AI读的是自然语言写的操作文档自己判断什么时候启动、按什么步骤执行、是否需要运行辅助脚本。它更适合流程复杂、规则多变、需要综合判断的活儿。我自己的体感对比大概是这样维度Function CallingSkills触发方式明确函数调用阅读文档后自行决策核心载体JSON Schema / 参数定义Markdown 脚本适合场景稳定API对接流程、规范、方法论扩展成本每个接口都要写定义每份技能写一份文档可解释性调用日志清晰需要看agent上下文组合能力靠外部编排可直接多skill组合所以我的建议是有稳定后端接口先上function calling涉及流程规范、批量处理、内容生产优先考虑skills。两者不是替代关系更像互补function calling负责触达外部世界skills负责教agent怎么做人做事。1.3 一套skill的典型目录长什么样Anthropic早期公开的Agent Skills标准给了个很清爽的目录结构也是目前社区里最主流的组织方式。我自己的项目里通常是这样的my-skills/ ├── csv-cleaner/ │ ├── SKILL.md │ ├── scripts/ │ │ └── clean_csv.py │ └── references/ │ └──>--- name: csv-cleaner description: 用于CSV数据的清洗与标准化。适合处理空值填充、去重、编码转换、列名规范化、数据类型修正等场景。当用户提供数据文件并希望整理成统一格式时使用。 ---name要简短且唯一description要写得像搜索引擎的索引词。别小看这段描述agent就是靠它来判断当前任务和哪个skill匹配。我一开始写得太笼统写了个处理数据结果AI遇到所有数据类任务都找到它经常进错门。后来改成具体场景加输出边界的描述命中准确率高了很多。正文部分我建议分这几块前置条件、操作步骤、输出规范、示例。其中输出规范一定不能省它决定了AI交付的成品长什么样。比如CSV清洗skill里我明确要求最终输出必须保留原始表头映射、注明处理过的行数和类型、附一份处理摘要。有了这些硬约束AI就不会随手丢给你一个感觉差不多的结果。2.3 一个真实案例数据清洗skill从写到跑通下面是我实际用着的csv-cleaner的SKILL.md简化版重点看结构和规范描述--- name: csv-cleaner description: 清洗CSV数据文件处理空值、去重、列名规范化、编码与类型修正。适用于数据预处理与质量检查场景。 --- # CSV 数据清洗流程 ## 1. 前置检查 - 确认文件格式为 .csv - 读取前5行判断分隔符和编码 ## 2. 清洗步骤 1. 列名统一转为小写下划线命名 2. 空值处理数值列填充0或中位数文本列填充N/A 3. 去重基于主键列删除完全重复行 4. 类型检查日期列统一为 YYYY-MM-DD数值列去除千分位符号 ## 3. 输出规范 - 输出文件为 cleaned_文件名.csv - 单独提供清洗摘要原始行数、清洗后行数、处理规则 - 异常数据放入 warnings 字段备注不直接删除 ## 4. 辅助脚本 清洗逻辑参考 scripts/clean_csv.py当输入文件行数大于1000行时建议运行该脚本。配套的clean_csv.py也不用写得很复杂核心就是用pandas做了一套规整化处理import pandas as pd import argparse def clean(file_path): df pd.read_csv(file_path) original_count len(df) df.columns [c.strip().lower().replace( , _) for c in df.columns] df df.drop_duplicates() df df.fillna({数值列: 0, 文本列: N/A}) summary { 原始行数: original_count, 清洗后行数: len(df), } return df, summary if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(input) parser.add_argument(output) args parser.parse_args() df, summary clean(args.input) df.to_csv(args.output, indexFalse) print(summary)这套东西写完后放到skills目录里我在测试时故意给了个一万多行的脏数据文件agent读完SKILL.md后自动跑了脚本返回了干净文件和摘要。从那之后每次收到新数据我都是同一句话用csv-cleaner处理一下三秒进入标准流程。3. 安装、调试与实战排坑写完skill只是第一步真正的问题都出在安装和调试阶段。这部分我踩过的坑比写skill本身多得多一个个说来。3.1 不同平台的安装路径与加载机制主流的agent产品现在都支持skills目录。Claude桌面版和Codex的官方文档里都有说明在配置目录下建一个skills文件夹把每个skill作为独立子目录放进去重启客户端就会自动加载。还有一批第三方或私有化封装工具把skills做进了图形界面里本质上也是把这套目录结构挂到指定位置界面操作只是帮你省了手动复制这一步。安装时我强烈建议先看本地目录结构再动手。以Claude桌面版的配置目录为例mkdir -p ~/.claude/skills cp -r csv-cleaner ~/.claude/skills/ # 重启客户端后执行 related tasks 验证加载Codex的skills目录路径略有不同但结构一致。如果是通过官方市场或插件市场安装通常点几下就完事。这里有个很实用的经验安装完第一件事不是急着跑正式任务而是先问一句你现在加载了哪些skills分别是什么用途让agent自己报一遍。它说不出来说明没加载成功它说得出来再看描述是否准确。这一步能省下后面大量排查时间。3.2 我在调试里踩过的四个坑第一个坑description写得太宽泛导致skill被误触发。我最早给一个周报生成skill写的描述是帮助生成周报结果AI碰到写月报、写项目总结、写日报的任务都强行调它输出各种牛头不对马嘴。后来把描述改成根据项目进度数据生成周报适用于周报场景不支持月报/日报/总结类任务误触发率骤降。第二个坑SKILL.md里提到了脚本但没告诉agent什么时候运行。AI读完说明后一直尝试手动处理不用脚本速度慢还容易出错。后来我在流程里显式加了一句超过1000行数据时必须运行scripts/clean_csv.py它才按路径去执行。其实不是AI笨是我没把决策条件写清楚。第三个坑references引用文件路径写错。Markdown里的相对路径看着没问题但agent在处理时可能把当前目录理解成工作区目录而不是skill目录。解决办法是绝对路径或明确的相对路径标注并且在文档里写上如不确定路径请先查看当前目录结构。第四个坑输出格式没有硬约束。第一次测试时AI给了我一份格式完全自由的清洗结果字段对不上摘要也没有。后来我在SKILL.md里加了必须输出承接报告包含原始行数、清洗后行数、处理规则这行字才真正稳定下来。对AI来说应该怎么做和必须怎么做差距很大只有后者才叫规范。3.3 常见问题速查表现象排查方向处理方式agent完全找不到skill检查目录位置和文件名确保目录在配置路径下SKILL.md命名无误找到skill但没执行description不匹配或过于笼统重写description标注具体触发场景执行步骤但忽略脚本SKILL.md未写运行条件添加何时运行脚本的明确指令输出不符合预期缺少输出规范在SKILL.md加入输出结构、格式、摘要要求脚本报权限错误脚本没有执行权限或依赖缺失本地先手动跑一遍确认依赖和权限一个skill误伤其他任务description范围太宽加入边界说明如不适用于XX场景这里额外提一个通用心得所有问题都能通过让AI先说思路来加速定位。调试时不直接说你错了或这样不行而是问你打算怎么处理这个任务你觉得SKILL.md里哪一步不清楚它会把理解和判断路径讲出来问题出在哪个环节一目了然。这比反复试错高效得多。4. skills生态、组合玩法与安全边界skills真正让我兴奋的地方在于生态。官方市场里有大量高质量技能社区仓库也涌现出很多偏门但好用的封装大家已经把它当成了新的分发单元。4.1 官方市场与社区公开库怎么选现在找skills的地方主要集中在几类第一类是官方市场或示例库质量稳定、文档齐全推荐先从这里起步。第二类是GitHub等代码托管平台上的开源仓库数量大、种类多从论文写作辅助到分镜脚本生成都能找到。第三类是各类技术社区里个人博主分享的打包下载胜在新颖但质量参差不齐。GitHub上还有个容易混淆的项目叫GitHub Skills那是官方出品的交互式课程帮新手学GitHub操作跟AI agent skills不是一回事。找的时候注意区分别下载错了东西。我的选择顺序是官方市场优先-看社区star和issue-下来后自己审一遍目录内容。community模块尤其要小心因为skills的本质是提示词加脚本任何脚本都有执行能力。下载下来先别急着装打开SKILL.md通读一遍scripts目录下的代码逐行看一遍确认没有可疑命令再放进配置目录。我在试过几个第三方skill后基本养成了下载审查的条件反射。4.2 知识型skill与操作型skill的区别用久了你会发现skills可以分成两大类。知识型skill只提供文档和规范不需要脚本。比如团队代码规范、内容风格指南、PRD模板。它的作用是教AI知道该怎么做适用于稳定但灵活的流程。我做过的code-review skill就属于这一类只放团队约定、检查清单、常见问题案例AI按清单逐项审查不依赖任何外部程序。操作型skill则必须搭配脚本或命令比如数据清洗、批量改文件、调用内部API。这种skill的价值是知道做到AI读流程执行脚本拿到结果。它适合高度标准化、量大、人工做容易出错的任务。实际项目里两者经常混用。比如一个前端开发skill可以包含知识型的组件规范文档也可以包含一个自动跑lint和test的操作型脚本。我的经验是先做知识型跑通了再加脚本每一步都可控排查范围也小。4.3 把多个skill组合成一条流水线单个skill解决的是单点任务真正的效率提升来自组合。比如做数据周报我会同时挂载三个skillcsv-cleaner负责清洗数据、report-generator负责按模板生成周报、format-checker负责终稿格式校验。agent拿到任务后自动按顺序调用一条处理链就串起来了。组合使用时有个关键点skill之间要解耦。每个skill不依赖其他skill的内部文件只依赖标准输入输出。周报生成器只认清洗好的CSV文件名至于CSV怎么来的它不管。这样你换掉csv-cleaner或者升级它不影响下游。所有系统设计的单一职责原则在这里同样适用。我还会在SKILL.md之间建立显式引用比如清洗skill里写下游流程请使用report-generator生成周报。这不是强制依赖只是给agent一个明显的下一步提示。AI的路径规划能力再强我们给的指引越清晰它的行为就越稳定。4.4 安全边界与合规意识skills能力的另一面是风险。你给AI的skill如果有脚本执行能力它可能真的会去操作文件、调接口、跑命令。所以几个底线我必须强调第一不安装来源不明的skill尤其是压缩包一键安装的那种。第二不在skill里硬编码密钥、token。这部分应该走标准的环境变量或密码管理方案任何教程让你把密钥写进SKILL.md都要警惕。第三对带网络请求或文件删除操作的脚本保持高度警惕审查时必须逐行确认。第四所有安全测试、审计相关的技能只能在明确授权和合法合规的范围内使用这个边界没有模糊地带。我自己的习惯是给skill建一个专门的运行目录脚本只允许访问白名单路径。第一次运行一个不熟悉的操作型skill之前我会开个临时环境看一眼它到底创建了什么文件、改了什么配置。多花五分钟后面能省十个小时的善后时间。再说一个更日常的场景内容创作类的skills比如分镜脚本生成、论文格式整理这类技能很受欢迎但使用时也要注意不侵犯他人版权、不伪造数据、遵守对应平台和学术机构的规范。工具本身没有对错但使用工具的人要对结果负责。5. 实操总结与个人体会从接触skills到现在我最大的感受是它把调教AI这件事从提示词工程升级成了流程设计。以前你写一个完美prompt只能服务一次现在你写一份SKILL.md能重复使用无数次还能分享给团队、上传到社区。这种沉淀和复利效应是单纯堆提示词做不到的。有几个动作我几乎每周都在做持续收集工作中重复出现3次以上的任务每两周给自己写的skill做一次小评审看哪些指令还能更精确看到别人分享的skill先从SKILL.md读起理解设计思路再考虑要不要装进来。这套习惯让我的AI工具库越来越厚但每个skill都清楚地知道自己该干什么、不该干什么。最后分享一个小技巧写skill时把错误案例也写进文档。AI非常擅长从反例里理解边界你告诉它不要删除原始文件不要把列名改成中文它就很少再犯同类错误。这比只写正面流程管用得多。skills这个方向还在快速演进标准也在不断完善但把经验文档化、把流程标准化、把工具嵌入AI决策链这套思路我判断会是接下来很长一段时间里Agent真正落地的一个核心方式。你现在开始积累自己的skill库一点都不早。