Agent Skills实战：从Prompt到可复用AI技能的全流程指南

1. 项目概述与核心思路拆解1.1 skills到底解决什么问题最近AI编程圈子里skills这个词出现的频率越来越高。尤其是一线用Claude、Cursor这类AI工具干活的人基本都绕不开它。如果只看字面意思skills就是技能但在AI Agent的语境下它指的是一套让AI助手能稳定复用复杂能力的结构化方案。先说清楚它到底解决了什么痛点。用过AI编程助手的人大概率都有过这种体验同一个AI你让它重构一个模块它表现得像个资深工程师但换一个稍微冷门的技术栈或者让它处理你没交代清楚格式需求的任务它就立刻变得笨拙甚至反复输出格式混乱的代码。问题出在哪本质上是缺少一套可以沉淀、复用、按需加载的操作规范。你把需求说得再详细都是一次性的对话下次换个任务AI的记忆基本归零。Agent Skills就是冲着这个问题来的。它本质上是一个开放规范允许你把一项AI能力的完整定义——包括任务描述、执行步骤、参考规则、脚本工具——打包进一个项目里然后让AI在遇到对应场景时自动加载并使用。用大白话说你不再需要每次都啰啰嗦嗦地告诉AI该怎么干活你只需要说一句按我仓库里的XX skill来处理它自己就会去读技能定义、按规范执行。我实际体验下来这套东西最值钱的地方不是某个具体技能而是它把AI的工作方法变成了像代码一样的资产可以版本管理、可以团队共享、可以跨项目迁移。1.2 为什么是现在从prompt到skill的演进逻辑要理解skills为什么会在这一轮爆发得往回看一眼AI工具的工作方式是怎么演变的。最早我们用AI编码靠的是prompt。你在对话框里写一段需求AI根据上下文给出代码。这种方式的问题在于prompt是一次性的且人和AI之间没有建立稳定的协作协议。同一个项目里你第一天让它按A规范写代码第三天换了话题它可能就忘了A规范。后来有人搞出system prompt系统提示词和preferences把常用规则塞进全局配置里算是进步了但粒度太粗——你不可能把所有工具的用法都写进全局配置那会互相干扰。再后来MCPModel Context Protocol出现解决了AI调用外部工具的问题。但MCP解决的是AI能不能调用某个工具并没有回答AI应该如何完成一个完整的任务这个问题。MCP更像给AI装了一堆手skills则是给AI装了一套怎么干活的心智模型。所以skills出现的时机恰好在三股力量交汇处第一上下文窗口变大了AI有足够的空间读取完整的技能定义第二Agent模式从对话式走向任务式AI需要自主规划步骤而不是每步等人类确认第三团队协作需求变强了大家希望把AI的使用经验沉淀成团队资产。这三股力量缺任何一个skills都不可能有今天的关注度。1.3 skills与MCP、prompt模板的本质区别很多人会把skills和MCP搞混我在实测之前也花了点时间才理清边界。做个表格对比一下就一目了然。维度Prompt/System PromptMCP ServerAgent Skills本质一段文本描述一个工具服务一个完整工作流解决什么问题约束AI的输出风格给AI提供外部工具能力告诉AI怎么做事的步骤可组合性低线性拼接中多个工具可调用高可嵌套引用其他skill版本管理难以管理按服务版本管理与仓库同版本管理复用方式复制粘贴服务端注册目录拷贝或引用执行主体AI对话本身AI调用的工具进程先读定义再执行任务一句话总结MCP解决的是AI的手够不够长skills解决的是AI的脑子够不够清楚。两者不冲突配合起来效果最好。我后面会专门写一节讲它们的配合方式这里先记住一个大原则——凡是需要完整执行步骤带分支决策的任务都值得做成skill凡是只需要一个API调用能力的优先考虑MCP。2. Skill文件结构与原理剖析2.1 SKILL.md一份自带执行说明书的目录先看一套典型的Skill目录结构应该长什么样。我前段时间为了给前端项目做代码审查建了一个叫frontend-review的skill目录是这样组织的frontend-review/ ├── SKILL.md # 技能定义文件核心中的核心 ├── scripts/ │ ├── detect_api.py # 检测项目中过时的API调用 │ └── complexity.py # 分析函数复杂度 ├── rules/ │ ├── coding-style.md │ └── security-checklist.md └── examples/ └── review-output.md这个结构有个关键点SKILL.md是整个skill的总控文件。Agent在加载一个skill时第一件事就是去找这个文件读里面的内容然后严格按里面的指令行事。SKILL.md可以理解为一个自带格式的说明书AI读完它之后才知道这个skill要干什么、怎么干、什么情况下不要干。SKILL.md内部有自己的规范结构。头部有YAML frontmatter包含name、description、version这些元信息正文则按行为逐步描述执行流程。选一个我写过的项目实际展开一段--- name: frontend-review description: 对前端项目执行代码审查检查API过时、性能风险和可维护性问题。 version: 1.0.0 ---然后正文会写什么时候应该使用这个skill、执行步骤分几步、每一部输出什么格式。注意这里有个反直觉的坑Agent读这些指令的方式和人不一样它不会领会精神而是按字面执行。所以指令描述必须尽可能明确材质性描述和主观描述尽量少用多用输出到chore/review.md如果文件超过200行则拆分这种靠谱的、可验证的指令。2.2 目录里除了MD文件还能放什么scripts与参考资源我一开始以为Skill就是一堆Markdown文档真正做了一个复杂点的skill之后才发现脚本和参考文件才是它威力真正起来的地方。比如我做的一个changelog-generatorskill它要做的事情是分析git提交记录自动生成changelog。纯靠提示词让AI去做结果往往是格式不稳定、分类逻辑混乱——因为每个AI模型对语义分类的理解都不太一样。后来我在skill里塞了一个Python脚本用规则加正则做第一道粗分类把handle到feature/bugfix/docs的标层再让AI基于脚本输出做二次润色和补充。效果一下就稳定了脚本负责确定性高的部分AI负责语义理解的部分分工明确。scripts目录的引入带来一个很大的思路转变——Skill不只是一个文字规则集它可以是规则代码的组合。这让它有了确定性输出的能力这恰恰是纯prompt方案做不到的。参考文件也很有用比如AI生成某种格式的代码时你可以把很少见的特殊情况参考这类内容放在examples目录里给AI拄着拐杖。几次实测下来带examples的skill初次使用时质量明显高于只有抽象描述的版本。原理不难理解AI是概率生成你给它具体样例相当于给它的概率分布加了约束条件。2.3 为什么开放标准比各家私有的方案更舒服Skills能这么快火起来有一个很容易被低估的原因它是一个开放标准不绑死在某一家工具里。最开始这个规范是Anthropic提出的但设计上刻意保持了工具无关性。你按规范写的skill在Claude里能用拿去给实现了同样规范的其他Agent也是可以跑的。这一点对我来说特别重要——我工作的项目中有人用Cursor有人用Claude Code命令行版如果用各家的私有配置团队协作就乱了。作为一个踩过私有方案坑的人我特别想说这个事。之前用某个AI IDE做项目团队统一维护了一套团队级指令文件看起来挺好用但换个人用另一个工具就失效了。Skills这种开放规范的好处是写一次到处跑而且因为是基于标准的MarkdownYAML脚本普通开发者也能看懂、能改、能审。这跟当年Docker用Dockerfile统一了容器镜像描述逻辑一样拔根上的开放性往往决定了一个技术能走多远。3. 实操全记录从零写出自己的skill3.1 选场景不是每个任务都值得做成skill开始写Skill之前先泼一盆冷水不是所有任务都适合做成skill。我早前犯过一个错误什么都想固化成skill结果维护成本比手动写prompt还高。选场景有一个简单的判断标准——这个任务你是否反复遇到、是否有相对稳定的执行流程、是否对输出格式有明确的预期。举个例子我团队每个迭代都要给QA写测试数据准备脚本每次写都差不多属于典型的稳定流程确定输出做进skill里收益极高。而帮我设计一下这个模块的架构这种创意型任务就不该机械固化固化出来的东西往往很死板。选场景还有一个考量因素任务的复杂度和错误成本。如果按AI瞎搞的代价是几行代码随便它发挥但如果是涉及生产环境的变更操作哪怕流程简单也值得做成skill让每一步都受控。我有个db-migration-checkskill就是干这个的——它每次改动前先把迁移脚本的逆向兼容性检查一遍。这个skill很简单就一个SKILL.md加一个Python检查脚本但它把一次本来要靠人工盯着的风险操作变成了可重复的自动流程。3.2 写SKILL.md三个关键段落怎么组织骨架搭好开始写SKILL.md。前面说过它有YAML frontmatter和正文这里展开讲讲正文的段落组织。我推荐用三段式结构下面逐一展开。第一段是什么时候用。这段要写得极度精确否则会出现AI在不该用的时候误用skill。比如我写changelog-generator时第一段明确写了仅当用户要求生成CHANGELOG或发布说明时使用日常提交代码时不要执行。这句话看似简单实际救了我好多次——有一次AI在正常写代码时居然也试图跑变更日志流程加上限制之后就没再犯。第二段是执行步骤。这里有个技巧把执行步骤写成AI需要自主决定顺序的流程而不是每步必须按顺序执行的呆板清单。比如我在frontend-review的步骤里写了先扫描项目结构确定技术栈再检测API再分析复杂度最后汇总报告但每个步骤内部都留了口子允许AI根据实际情况调整。这样既保证了流程的整体一致又保留了AI的灵活性。第三段是输出与验收标准。这是很多人会忽视的——skill做完任务后AI应该输出什么格式、写到哪个文件、成果物要达到什么标准。我习惯把这段写得像验收清单一条条列出报告必须包含概述、具体问题清单、问题等级、修改建议、参考代码。有了这段AI的输出基本不需要再二次加工可以直接拿去用。3.3 脚本开发与Skill联调一次跑通的经验Skill中带脚本时联调是最痛苦的。脚本跑出错误结果你很难判断是脚本问题还是AI调用方式问题。我的调试经验是先人后AI先把脚本放在终端里单独跑通用真实的样例数据检验输出再挂到skill里让AI去调用。直接让AI去调一个没验证过的脚本出了问题你根本定位不到原因。另一个经验是设计脚本接口时要照顾AI的习惯。AI在跑脚本时倾向于传JSON格式的输入然后期望收到JSON格式的输出包括正常结果和错误信息都要明确。我写过一个脚本用argparse接收参数AI传参方式跟我想象的不一样结果每次参数解析失败。后来我把脚本改成从stdin读JSON输出也统一回JSON配合边界错误处理就再没出过问题。这让脚本对AI非常友好也让调试成本大大降低。还有一步容易被忽略Skill目录里应该留一个test-fixture子目录里面放测试用的样例输入和预期输出。这样每次改完skill可以跑一个回归测试——让你的AI加载skill后处理固定的测试任务对比输出与预期是否有偏差。我干了几个月才发现这个做法之前吃过改了一行规则结果某个分支行为全变了的亏。3.4 发布与沉淀让Skill变成团队资产个人用的skill写完之后很多人就止步了。但如果想让Skill发挥更大的作用建议把它推进到团队协作层面。首先把skill目录放进项目的git仓库跟代码走同一个版本体系。这样每次改动都有记录出问题可以回溯。其次给每个skill写一个简短的README写清楚这个skill解决了什么问题、适用于什么场景、已知限制是什么。最后在团队内部定一个技能评审机制谁提出新skill、谁负责维护避免出现有人写没人管的僵尸skill。我团队现在有七八个公开skill和一堆个人skill。公开skill里最有价值的是一个dev-handover——每次人员交接时AI自动整理当前项目的关键信息、待办事项、文档位置。以前交接花一两天现在一个小时内能完成初步工作。这种价值会滚雪球因为每个参与维护的人都会往里补充自己的经验skill越用越厚团队整体的AI使用水平也被拉上去了。4. 常见问题与排查技巧4.1 AI没有按要求加载Skill最常见也最头疼第一个高频问题是——明明在项目里放了skill目录AI却视而不见。这种情况我第一次遇到时也一头雾水。排查思路分三步走。先检查目录结构是否规范。每个skill必须放在独立目录且SKILL.md必须在根目录下不能嵌套太深。有的工具对目录层级有硬性要求如果你把skill放到了config/skills/xxx/extra/SKILL.md这种深层路径AI根本找不到——注意不同的客户端对skill目录的查找深度不一样深了不一定能识别。再检查description字段是否写清楚。很多Agent是靠语义匹配来决定是否加载skill的description写得含糊AI就不认为自己需要用到它。我有个教训某个skill的description写的是提供相关工具函数结果从没被主动加载过。后来改成当用户需要分析网页SEO表现时使用包括关键词密度、meta标签检查、页面结构评估立刻生效。最后才是工具配置问题。如果你用的是Claude Code要在项目或用户级别的配置中显式声明skills目录位置。我一度以为把skill放对位置就能自动识别找了半天配置才发现需要在.claude/settings.json里加skills: {enabled: true}这种设置。这块不同工具差异较大别凭经验硬扛直接查对应工具的文档。4.2 Skill跑起来了但输出质量飘怎么稳定质量AI执行了skill步骤也都走了但输出质量忽高忽低。这是所有skill维护者迟早会遇到的问题。我的经验是——大概率是你SKILL.md里的输出与验收标准写得不够死。注意AI对高质量的主观理解非常不稳定。你写输出一份高质量代码审查报告它会给你发挥出十个版本。但如果你写报告必须包含六个部分1. 项目概述…2. 问题清单…3. 每个问题附上文件路径和行号…4. 严重等级P0-P3…5. 修改建议…6. 参考实现,AI的输出就会收敛很多。这正是AI工作流的独特性不是它不想给你稳定输出而是你的规范没有给它足够可执行的约束。另一个稳定质量的技巧是——在skill里加负面清单。写上不做什么比只写要做什么往往更有效。比如我写changelog-generator的时候明确标了不要把依赖升级单独分类列出来而应该归入feature或fix。AI模型对这种否定性约束的遵循率我实测下来相当高。如果以上都做完了输出还是飘那就不是SKILL.md的问题而是本身任务复杂度超过了语言模型的能力边界。这种时候就该引入脚本把部分高确定性的步骤从AI手里拿回来。我在处理db-migration-check时深有体会——让AI自己判断这个迁移是否逆向兼容经常出错但让AI跑一个写好的脚本去做静态分析结果就稳定得多。4.3 Skill与MCP的组合拳怎么搭配效率最高前面说Skill和MCP不冲突这里展开讲怎么搭配。我的经验是Skill负责流程编排MCP负责底层能力。Skill就像是项目经理MCP就像是执行团队中的专业工人。举个例子我写过一个api-compatibility-checkskill它要检查一个OpenAPI spec升级后服务的现有调用方有没有兼容性问题。这个任务里Skill负责制定整个流程先读spec文件、识别改动的端点、对比调用方代码、生成报告。而中间读取调用方代码这一步恰当地通过MCP服务器提供的代码搜索能力实现。Skill告诉AI调用xxx MCP工具的search_code方法搜索所有调用了被改端点的文件MCP就把底层搜索能力给到AI。老实说我踩过不少弯路。一开始要么MCP配置了一堆工具AI根本不知道什么时候用什么要么skill写得事无巨细把AI变成了死板的执行器。两者的正确关系应该是Skill里描述要做什么、按什么顺序做MCP负责每一步具体怎么做。有了分工整个系统才灵活又不混乱。4.4 实际项目里哪些场景收益最大三个实例复盘写了这么多理论最后复盘三个我真实投入使用的Skill场景供参考。第一个是code review。上面提过的frontend-review在团队推行后把每轮代码审查从等人力慢慢评审变成AI先跑一轮自动化加智能初筛。开发人员只需要看AI给的报告挑重点核验即可。我统计过加入了skill后一次常规review从原来差不多一小时缩短到二十分钟之内。关键是稳定性以前找不同的人review标准不一现在AI先过一遍标准高度统一。第二个是onboarding文档生成。我写了一个project-onboarding-docskill扫描项目结构、README、测试用例和代码注释自动生成一份新成员上手文档。这个需求市面上有别的工具能做但效果很套路。我这个skill因为读了自己项目的dotfiles和devcontainer配置能自动生成高度贴合我们技术栈的初始化流程。新成员入职当天就能照着文档把环境搭起来省了大量给环境怎么配的重复解释。第三个是release流程的自动化。我维护的一个开源小项目每次发版要做changelog、版本号更新、打tag、编译产物几条事烦得很。以前靠手工清单逐项检查容易漏。现在用了一个release-managerskill——先跑git log分析版本区间内所有commit判断是breaking/feature/fix自动生成changelog并更新版本号再按规则打tag。AI如果遇到搞不清的commit分类会列出候选让确认。说实话这套流程已经连续用了两个季度的发版一次都没漏过步骤。我实际用下来的体会是skills这个东西的价值不在某一瞬间的惊艳而在越用越值的积累。每次让AI干活过程中发现它有新的好招就顺手补充到对应skill里下一次所有人就都能用上这个经验。这个模式滚的时间越长团队在AI工具上的能力就差异化越大。如果你还在纠结要不要入坑skills我只说一句——先挑一个你最常重复的任务写一个最简单的skill跑起来比看任何攻略都管用。