如果你现在还在用一长串prompt去教agent怎么完成任务那你大概率已经掉队了。过去半年里我陆续把一些重复性、流程式的工作交给了Agent但真正让效果产生质变的不是模型本身而是“Agent Skills”这套机制。它解决了一个很根本的问题模型再聪明也不知道你项目里那些特定格式、特定工具链、特定团队规范而Skills就是把这类“系统级知识”固化下来让agent开箱即用。这篇文章我不打算讲空泛的概念而是直接按照我自己从零开发、安装、调试、上线一套skills的完整过程来拆先说它到底是什么、和tools的区别在哪然后手把手写一个能跑的skill再讲安装分发和市场现状最后给出我在真实项目中踩过的坑和排查思路。适合两类人看一类是agent开发新手想搞清楚skills到底解决什么问题另一类是已经在用agent的开发者想把自己的工作流沉淀成可复用的技能包。1. 为什么要关注Agent Skills先搞清楚它解决的是什么问题1.1 从一长串prompt到结构化技能包早期用agent干活最常见的做法是把所有规则写进系统提示词里。比如“你是一个前端开发助手项目使用React 18组件放在src/components样式用Tailwind提交前必须跑lint”。这段话看着没问题但随着约束变多、步骤变多prompt会越来越长模型在上下文里“记住”这些规则的成本也会越来越高最终导致指令漂移——模型开始自作聪明地忽略部分规则。Skills的思路完全不同它不把规则塞进对话而是把规则和可执行脚本一起打包成独立的目录。agent在需要某种能力时主动去读这个目录里的说明文件按说明执行执行完再把结果带回对话。这样有几个好处上下文更干净日常对话不会被几十条规则污染技能复用性极强同一套skill可以被不同项目、不同会话调用支持版本管理skill改坏了可以回滚可以像代码一样review1.2 Skills和Tools、MCP到底什么关系我经常看到有人把Skills和Tools混着用这俩虽然最终目的都是扩展agent能力但粒度完全不一样。Tools更像是“点状能力”一个工具干一件事比如“查天气”“算个数学题”Skills则是“面状流程”它把感知、判断、执行串联起来比如“为新组件生成完整代码并跑测试”这个过程中可能要调用多个工具还要做多次判断。至于MCP它更底层一些解决的是“agent怎么连接外部数据源和系统”的标准协议。Skills可以理解为建立在agent之上的“行为包”它内部可以使用MCP服务也可以直接执行本地脚本。打个比方MCP是电器的供电接口标准Skills则是装在电器里的自动化程序它知道电饭煲什么时候该煮饭、什么时候该保温。1.3 目录结构一套skill长什么样我自己维护的skills目录大概是这样的skills/ ├── frontend-gen/ │ ├── SKILL.md │ └── scripts/ │ ├── generate_component.py │ └── lint_check.sh ├── database-review/ │ ├── SKILL.md │ └── src/ │ └── check_index.py └── release-notes/ ├── SKILL.md └── templates/ └── changelog.md每个目录里面SKILL.md是说明书模型会先读它理解这个skill负责什么、怎么用、有什么约束。其余文件是配套的脚本、模板、参考文档可以在说明里被引用。目录本身可以打包成zip或放进Git仓库实现跨设备、跨项目复用。2. 从零开始开发一个可用的Skill完整实操2.1 先定场景什么任务适合做成Skill不是所有任务都值得做成skill。我判断标准有三条流程是否稳定、是否反复出现、是否有明确检查点。比如“生成发布说明”就是一个典型场景每次流程都一样拉diff、读commit记录、按模块分类、写changelog、再更新版本号。相反“帮我看看这个bug为什么复现”这种探索式任务就不适合做成skill因为每次路径都不一样。我建议第一套skill选自己每周至少碰一次、且规则清晰的场景。这样既能快速验证流程也容易获得正向反馈。我最早做的就是从commit记录生成changelog因为公司对这个格式有硬性要求每次手动整理都极其痛苦。2.2 SKILL.md怎么写才能让模型真正理解SKILL.md是整件事的灵魂。模型读它的方式和你读一份操作手册差不多写得含糊模型执行就飘。我习惯用三段式结构--- name: release-notes description: 根据git提交记录生成标准格式的发布说明 --- # 用途 在发版前根据commit历史整理发布说明按模块分组。 # 使用步骤 1. 运行 git log --oneline lastTag..HEAD 2. 对每条commit判断所属模块 3. 按模板输出markdown # 输出规范重要 - 必须包含概述、变更列表、兼容性说明 - 每个模块用H2标题commit条目用列表 - 文件名规范release-notes-YYYY-MM-DD.mddescription字段一定要写得像“检索摘要”让agent在多个技能间判断时能准确匹配。我踩过的一个坑是description里写太多细节结果模型每次都在决策阶段纠结要不要调用。后来我把description压缩成一句场景描述把细节全放进正文决策准确率反而上来了。2.3 脚本编写什么时候用纯文本什么时候写代码skill里要不要带代码取决于任务性质。像changelog这种模型靠读git输出再整理纯文本说明就够了但像“批量重命名图片并压缩”这种任务就必须给一个python脚本因为模型自己写代码容易出边界问题比如不处理文件冲突、不检查磁盘空间。如果写脚本注意三点入口要简单参数用环境变量或命令行参数传给脚本脚本要容忍异常单张图片失败不能让整个过程崩溃输出走到标准输出让agent能直接读取结果下面是我写的一个组件生成器的核心片段供参考import os, re, sys def generate_component(name, props): base fsrc/components/{name} os.makedirs(base, exist_okTrue) content fimport React from react; interface {name}Props {{ {props} }} export function {name}({{}}: {name}Props) {{ return div className{name}{name}/div; }} with open(f{base}/index.tsx, w, encodingutf-8) as f: f.write(content) print(fGenerated component at {base}/index.tsx) if __name__ __main__: name sys.argv[1] props sys.argv[2] if len(sys.argv) 2 else generate_component(name, props)脚本越简单越好越通用越好因为模型是“按说明调用脚本”它不负责调参的智能智能都在你写的说明和脚本里。2.4 测试技能让模型自己当质检员skill写完必须测而且要在真实任务上下文里测。我会准备三个不同场景的测试用例比如changelog就分别测“只有普通commit”“有hotfix分支合并”“有revert记录”然后观察模型是否按说明执行。有个技巧在对话里故意说“你忘了用skill了吧”然后看模型能否主动发现自己跑偏并纠正这能验证技能描述是否足够强约束。如果模型频繁误解步骤大概率不是模型能力问题而是SKILL.md写得不明确。这时候就改说明不要指望模型自己领悟。3. 安装、分发与管理从本地到团队共建3.1 安装方式本地目录、Git仓库、官方市场目前skills的安装路径主要有三种本地目录式把skill文件夹丢到用户指定的skills根目录适用于个人开发测试改代码立刻生效不涉及网络和权限问题。Git仓库式把skills目录做成一个git repo团队成员clone到本地通过git pull一键同步。这是团队协作最常用的方式好处是天然有版本管理和review机制。官方市场式在agent平台自带的市场里一键安装。好处是省事但依赖平台方的上架审核更新节奏不一定跟得上。从我实践来看个人项目用本地目录就够了团队项目一定要上git仓库。之前我在团队里图省事直接共享文件夹结果有人改了一半的skill被另一个人拉到现场事故。3.2 官方市场与第三方平台怎么挑、怎么上架官方市场里能直接安装经过审核的skills但数量目前不算多。第三方平台更热闹比如社区维护的Awesome lists、开发者自建的skills仓库甚至有些产品已经推出了可视化的工作台直接把skill编排和obsidian笔记、任务管理软件联动起来。选第三方资源的时候我建议看三个指标最近更新时间、是否有issue反馈记录、SKILL.md是否完整。我见过不少skills脚本写得可以但SKILL.md只有一句话基本没法用下载纯粹浪费。如果你要上架自己的skill到市场我踩过的流程大致是先按平台要求的格式写好SKILL.md和目录结构然后提交到对应的仓库做PR审核重点是描述准确性和依赖可选性——也就是说即使没有skill里的脚本agent也应该能用文本说明完成任务而不是直接报废。3.3 版本管理为什么每个skill都要有自己的版本号skill一旦被团队使用版本管理就不是可选项了。我习惯在SKILL.md的metadata里写version字段升级时写CHANGELOG并在description里标注“兼容平台版本”。为什么这么麻烦因为agent平台本身在快速迭代某个skill依赖的模型能力今天可用下个版本可能就有变化。如果没版本记录你几乎无法排查“这个功能为什么突然不正常了”。另外建议大改动用新目录名比如frontend-gen-v2而不是原地覆盖。我试过原位升级结果老会话里的引用全部指向新逻辑行为不一致让人很难受。保留独立版本目录反而让迁移和过渡都平滑很多。4. 架构设计与进阶用法多技能如何协同4.1 多技能编排一个“路由技能”怎么分发任务当skills数量多了以后你会面临一个新问题模型怎么知道当前任务该用哪个技能。除了靠每个skill的description做检索经验做法是写一个“路由器”skill它本身不干具体活只负责判断任务类型然后递归调用其他skill。比如代码任务路由到frontend-gen文档任务路由到release-notes数据任务路由到db-review。路由skill的价值在于把“选择”集中管理避免模型到处试错。但别把它做成“万能解说员”说明越短越好本质是一张查表逻辑。4.2 安全边界skill不应该碰什么skills虽然强大但安全边界想清楚。我这边的铁律有三条skill脚本绝不读取模型对话之外的任意文件除非输入参数明确指定涉及写操作建文件、改文件、发请求必须通过“预演模式”先打印即将执行的动作等用户确认不把任何机密信息写进SKILL.md或模板文件密钥一律走环境变量之前社区流传过一个自动挖洞类的skills我看了看原理本质上就是用脚本批量探测目标这类型一定要避开一是法律风险极高二是就算在公司环境下也很容易越权。安全这件事在agent化开发里不是可用可不用而是要作为第一优先级写进scaffold里。4.3 记忆与上下文skill如何配合长期记忆skills和agent记忆是可以互补的。agent记忆负责“记住过往偏好”比如你喜欢的代码风格、常用库版本skills负责“执行既定流程”比如生成一个新组件时应该跑哪些步骤。建议把风格偏好从skills里剥离放进记忆文件里统一维护不然改风格就得改所有技能不现实。我自己的习惯是skills目录下放一个profile.md它是所有技能共享的“人设文件”里面记录语言偏好、代码风格、输出习惯SKILL.md的正文一开始就引用它。这样团队里每个人可以根据自己的profile获得不同风格输出但流程完全一致。5. 常见问题与排查技巧实录5.1 技能没被调用先查description的检索命中率最常遇到的问题就是“我明明装了skill但agent就是不调用”。我一开始也卡了很久后来发现关键在description字段。模型是在每个任务开始时对可用技能做语义匹配如果你的description是“这个技能很有趣很有用适合各种场景”那就是典型的混淆样本。改成明确的触发场景描述比如“只有当你需要根据git历史生成markdown发布说明时使用”命中率能高很多。5.2 脚本报错检查环境而不只检查代码Skill脚本跑挂时第一反应别去翻代码。先看运行环境是不是和开发时一致python版本、node版本、有没有装依赖。很多skill自带shell脚本但没写环境校验导致在macOS上好的到Linux就报错。我建议每个带执行脚本的skill都加一个环境检查步骤比如运行时先echo当前PATH和工具版本让agent看到输出后能自己判断。5.3 上下文膨胀SKILL.md写太多也会拖慢速度这个坑比较隐蔽。早期我为了让模型“理解透彻”把SKILL.md写得很长把所有可能的情况全列出来。运行是稳定了但每次会话光读这个技能就要耗掉一堆token数大任务做下来很容易触发上下文限制。后来我改成“说明留主干、细节放examples目录”模型需要时再额外读取示例文件速度快了约30%。动态加载比全文塞入更符合agent的运作方式。5.4 兼容性换了平台后skill失效怎么办如果你在不同的agent产品之间迁移大概率会遇到skill失效的情况因为各家对SKILL.md的细节字段不完全一致。排查流程是先看平台文档支持的metadata字段再检查脚本依赖是否默认安装最后看路径分隔符是否平台相关。别直接改SKILL.md格式去硬适配更好的办法是写一个转换脚本在克隆仓库时自动适配合前平台。虽然多一层但一劳永逸。6. 一些真实心得把Skills用好的底层逻辑我个人认为Skills本质上是在给模型“降噪”——把那些不该让模型花心思记的规范、步骤、格式都搬到外部文件里。所以开发skill的最高原则不是“写出聪明的代码”而是“写出不会让模型误解的说明书”。你越能把每一步说清楚、把边界说明白模型的整体表现就越稳定。另外一个体会是不要一上来就追求多技能协同。先从单技能做起跑顺了再考虑路由、编排、版本管理。很多人一开始就搭了一整套宏伟架构结果连一个技能都跑不通反而对这套机制失去了信心。最后分享一个小技巧给每个skill都配一个“演示任务”放在demo目录里。这样每次模型升级或者平台改动后你可以用一条命令快速回归测试而不是手动构造十几个场景。我的demo命令就一句话agent run skills/frontend-gen/demo --scenario basic它能直接告诉我这套skill在当前模型版本下是否还“听话”。这套机制你有没有用起来我和我的团队成员称之为技能库的“体检报告”实测下来很长一段时间里帮我拦下了不少升级事故。Skills这条路值得每一个正在做agent开发的人认真走一遍。