第一次用AI Agent写代码的朋友大概率都经历过这种场面需求发过去等了好几分钟它跑出一个看起来自认为完美、实际上装都装不起来的项目。你让它改它道歉再跑又跑出另一个错误。三五个来回之后你开始怀疑是不是自己表达能力有问题或者这模型天生就爱“翻车”。我的看法是大部分时候都不是你的问题也不是模型笨而是你少给Agent配了一套Skills。Skills这个概念最近在AI圈里讨论度极高Claude Code、Codex、Cursor、OpenCode这些主流工具全都在支持。今天我不讲空话直接从我自己踩过的坑出发聊聊Skills到底是什么、怎么装、怎么写以及怎么用它把一个“动不动翻车”的Agent调教成稳定输出的得力搭档。1. 先聊AI Agent最常见的“翻车现场”1.1 新手最容易遇到的三种翻车第一种同一个需求每次跑出来的结果都不一样。上午让它写一个用户登录页它用了表单校验下午再问一次它改成接口直连连基本的防重复提交都没了。这种“薛定谔的输出”让很多人觉得AI根本不可控实际上是因为每次对话都在重新“自由发挥”。第二种让它调用工具它自己编造函数名。比如明明项目里只有getUserInfo它能一本正经地调fetchUserData然后告诉你“接口报错了”。这种问题不是模型知识不够而是它没经过工具验证纯靠训练数据里的“相似记忆”在猜。第三种输出格式不稳定。写JSON的时候少个括号生成代码的时候漏掉import让它给Markdown表格它偏偏给你塞进代码块里。这些格式问题单独看都是小事但在自动化流程里就是致命的脚本一旦解析失败整条流水线直接崩。1.2 翻车的根因短期记忆差加上每次都在“临时发挥”Agent的工作链路是一个“思考—行动—观察—再思考”的循环。每一步它都要依赖上下文窗口里的信息做判断而上下文窗口是有限的。当对话越来越长、项目文件越来越多早期交代过的规则就会被“挤”出有效注意力范围。这时候它不是故意犯错而是真的忘了你之前说过什么。更关键的是大模型本身带有随机性。同一个prompt你在不同时间问它会给出概率分布里不同的结果。这就好比把一个新来的实习生丢进项目里不给他任何文档全靠他自己临场猜。他心情好的时候能蒙对几次心情不好、信息又乱的时候交出来的东西就千奇百怪。所以我才觉得让Agent稳定发挥的关键不是换个更贵的模型而是给它配“岗位说明书”让它一接手任务就知道标准流程、操作规范、避坑要点。这套“岗位说明书”就是Skills。2. Skills到底是什么从“一次性指令”到“可复用技能包”2.1 一个Skills包长什么样Skills说白了就是把一组完成特定任务的指令、示例、代码规范、工作流程提前写进一个结构化的文件夹里让Agent在遇到对应任务时自动加载并遵循。目前社区最通用的格式是在一个目录里放一个SKILL.md文件文件头部用YAML写元信息正文用Markdown写具体操作流程。一个最小的Skills长这样my-first-skill/ └── SKILL.md打开SKILL.md内容大概是--- name: frontend-component-review description: 用于审查React/Vue组件代码确保符合团队规范。当用户提交前端组件代码、要求代码审查或验收组件质量时使用。 --- # 前端组件代码审查流程 1. 先检查组件是否使用了项目中统一封装的按钮、输入框等基础组件。 2. 再检查样式是否引用了Tailwind配置里的设计令牌禁止写死颜色值。 3. 如果发现图片资源必须提示使用CDN地址不允许本地静态资源。 4. 输出审查结果时必须标注问题所在文件、行号和修改建议。这里最关键的部分就是开头的description。Agent不是每时每刻都把技能库里的所有内容加载进上下文而是根据description判断“当前这个任务跟哪个技能匹配”。描述写得越精准触发成功率越高。2.2 Skills、MCP、Prompt之间到底是什么关系很多人刚接触时容易把这几个概念搞混我做一个简单区分维度PromptMCPSkills本质一次性的口头交代工具/数据连接协议可复用的流程和规范生命周期单次对话长期配置按需自动加载解决的核心问题告诉Agent“这次要做什么”让Agent“能调用哪些外部能力”告诉Agent“这件事按什么标准做”使用方式每次手动写配置服务端和客户端放在指定目录自动识别用一个生活化的类比Prompt是“你今天帮我把这份文件翻译一下”MCP是“给你开一个能查词典、能访问数据库的权限”Skills则是“以后凡是翻译任务按这个格式输出专业术语先查词典译文必须保留原文格式”。三者的关系不是替代而是互补。MCP解决“能连接什么”Skills解决“怎么做才好”Prompt解决“这次具体做什么”。真正稳定的Agent往往三个都用上。2.3 为什么Skills能“救场”Skills最大的价值在于把“隐性经验”变成“显性文件”。你在项目里积累的代码规范、踩坑记录、客户偏好、历史最佳实践过去分散在文档和聊天记录里模型每次只能碰运气式地“看到”一部分。现在你把它们固化成一个技能包每当相关任务出现Agent就会自动把这一整段经验载入上下文相当于给模型做了一次“考前划重点”。我自己试过之后最明显的感觉是过去让Agent写一个组件我需要反复强调“用Tailwind”“按钮用Ant Design的”“风格参照现有页面”写完还要Review三遍。现在技能包里写清楚一次它每次执行都会遵守。这些规则不是靠模型“记住”而是靠技能文件“每次喂进去”所以不会随着对话变长而失效。3. 从0到1搭建自己的第一个Skills实操3.1 第一步挑一个值得写成技能的任务不是所有任务都适合做成Skills。选任务的标准有三个高频、重复、结果可以标准化。高频意味着你经常遇到值得投入时间沉淀重复意味着每次操作流程大同小异结果可以标准化意味着你能把“好”和“不好”的边界写清楚。符合这三个条件的例子很多写周报、生成前端组件、做代码审查、整理会议纪要、跑数据清洗流程、做数学建模的基线实验。我的建议是新手不要一上来就做一个月度计划表先从“下一次马上能用到”的小技能开始。比如你每天都要写日报那就写一个日报生成Skills让它按“今日进展—阻塞问题—明日计划”的结构输出顺便把敏感项目标成只写摘要。3.2 第二步动手写你的第一个SKILL.md拿“写产品周报”举例新建一个目录比如weekly-report/SKILL.md然后往里面写--- name: weekly-report description: 根据提供的本周工作记录生成面向团队的产品周报。当用户提到“写周报”“本周总结”“weekly report”时使用。 --- # 周报生成指南 ## 输入要求 - 用户可能提供聊天记录、工作日志、已提交的commit、关掉的issue列表。 - 如果没有提供足够信息先询问项目的目标、本周重点、下周计划。 ## 输出要求 1. 周报标题格式【周报】产品组W第几周周报 2. 按“本周核心目标与完成情况”“风险与阻塞”“下周关键计划”“需要跨团队协调的事项”四段式输出。 3. 每条内容限制在50字以内尽量量化不写“优化了性能”写“首屏加载从3.2s降到1.8s”。 4. 最后用一行总结本周整体进度颜色标记正常/预警/延期。写完保存这个Skills就算初步成型了。注意description里我特意写了中英文触发词这是为了让Agent在不同表达方式下都能识别出来。你还可以在目录里放额外的参考文件比如template.md存放周报模板examples/放几个历史优秀周报作为示例。Agent加载技能时正文里没有提到的细节可以去参考这些附加文件。3.3 第三步测试、迭代、正式使用写完之后最重要的环节是测试。把Skills放进Agent的全局或项目技能目录新开会话用各种不同的说法去触发它。比方说你直接说“帮我写这周周报”看它是否主动加载再说一次“我把这几条工作内容整理成周报”看它是否也能反应过来。如果触发失败先别急着怀疑模型。多数情况下是description写得太窄或者和任务之间缺少关键关联词。把用户可能用的说法都列一遍然后扩展描述。还要注意一个细节修改SKILL.md之后一定要新开一个会话再测试。大多数Agent工具是在会话启动时扫描技能目录修改文件不会热更新到当前会话不重开会话的话你会觉得“明明改了啊怎么还是老样子”。这个坑我踩过不止一次现在凡是动过技能文件我都会强制自己重开对话验证。4. 主流Agent工具里的Skills安装与配置4.1 Claude Code手动安装GitHub上的SkillsClaude Code是目前对Skills支持最完善的工具之一。它支持全局技能目录和项目技能目录全局目录通常是~/.claude/skills/项目目录是.claude/skills/。全局目录里的技能对所有项目生效项目目录里的技能只对当前仓库生效。如果你的某个技能包含公司敏感信息或团队特有规范一定要放项目目录别手滑放进全局。手动安装GitHub上的Skills的步骤很简单在GitHub上找到目标技能仓库一般长成skills或者awesome-skills这样的名字。把仓库clone到本地技能目录或者下载ZIP解压进去git clone https://github.com/owner/repo.git ~/.claude/skills/skill-name如果只需要其中一个子目录技能就只把对应的文件夹拷进去。重启Claude Code让它在启动时重新扫描技能目录。新开会话直接说“你有哪些可用技能”或者在任务里用自然语言描述看能否触发。我在实际使用中有一个小技巧如果电脑上同时装了CodeBuddy和Claude Code而你想让它们共用一套技能库可以把技能放到一个公共目录然后在各自的配置目录里做软链接。这样做的好处是团队规范只需要维护一份不用在两个工具里各复制一遍更新时也不会出现两边版本不一致的问题。4.2 Codex让Skills接管命令行AgentOpenAI的Codex同样可以玩Skills。它的原理和Claude Code类似都是在一个特定目录里放置技能文件例如常见的~/.codex/skills/或项目里的.codex/skills/。社区里已经有不少现成的聚合包比如superpowers、codex-nature-skills这些包往往把一个完整的工作流拆成多个子技能装好之后就能在命令行里指挥Agent跑起一套复杂流程。这里我想多说一句很多人用Codex跑数学建模类任务比如“华为杯”这种竞赛场景常需要做数据清洗、特征工程、基线模型、结果可视化。这类任务非常适合装一套数学建模Skills把从原始数据到最终图表的完整管线固定下来Agent每次拿到赛题后就能按标准流程推进而不是从头拍脑袋。安装方式同样很简单把GitHub上的仓库clone到对应技能目录重启Codex然后直接在需求里提到“用你的数模技能处理这份数据”。如果你看到Agent主动读取了技能文件说明安装成功。4.3 Cursor和OpenCode编辑器里的Agent同样需要技能包Cursor的Agent模式现在非常常用它同样支持Skills。我通常会在项目根目录下建立.cursor/skills/skill-name/SKILL.md把“项目代码规范”“前后端联调契约”“测试用例编写标准”这些内容做成技能包。这样当我用Cursor的Agent写代码时它会自动了解项目约定而不是凭训练数据里的通用习惯乱写。OpenCode的配置逻辑也类似它支持在项目的.opencode/skill/目录下放置技能文件。如果你经常用OpenCode做AI辅助编程可以花点时间把团队规范和常用代码模式沉淀成技能尤其是前端开发场景页面结构、组件命名、样式方案这些规则写清楚后Agent产出的代码质量会明显上台阶。不管是Cursor还是OpenCode都要注意设置里是否开启了“读取技能目录”的开关。有些工具默认只读项目根目录的配置没开启的话技能包放了也没用。4.4 企业级场景Spring AI和Jenkins中也能借鉴Skills思路Skill这个概念不只是在个人开发工具里好用在企业级AI Agent平台上同样值得借鉴。我自己接触过几个用Spring AI Spring Cloud搭Agent中台的团队他们面临的最大问题不是模型能力而是“每个业务方都在各自为战地写prompt”导致同一个业务问题在不同团队里有完全不同的处理方式。这时候可以借鉴Skills的思维方式把企业内的高频业务任务固化成标准技能包比如“客户工单分类”“合同关键条款提取”“内部知识库问答”“审批流摘要生成”。每个技能包包含任务描述、输入输出格式、必须调用的服务接口、合规检查项。在Spring AI的框架里这些技能包可以表现为一组规则模板决策配置Agent每次处理业务时先加载对应模板再结合大模型的判断力。在Jenkins这类CI系统里集成AI Agent时同样可以把“提交信息规范”“代码静态检查规则”“单元测试覆盖标准”做成技能集让Agent在流水线里的行为有章可循。说白了企业级应用远比个人开发更需要Skills因为团队协作的核心就是“统一标准”而Skills正是把标准从人脑搬到代码里的好办法。5. 值得收藏的Skills来源与推荐清单5.1 开源仓库里有哪些好东西如果你不想从零开始写最省力的方式是去GitHub上抄现成的。Anthropic官方维护的anthropics/skills仓库里就放了不少官方示例涉及文档处理、代码分析、信息提取等场景适合用来理解技能包的标准写法。社区里知名度很高的obra/superpowers也是一个宝藏仓库它把一套完整的项目管理、代码审查、任务拆解流程做成了多个Skills的集合装上之后Agent就像是接受过系统训练一样。还有一个方向是各种“awesome”聚合库里面整理了某一类场景下的技能清单前端开发、数据科学、写作助手都有覆盖。你在GitHub搜索关键词skills加上你的领域名基本能找到一堆现成的。5.2 垂直场景应该装哪些技能前端开发场景装“组件规范”“UI还原流程”“Tailwind样式配置”相关的技能包。这些技能能让Agent写出来的代码风格与项目现有代码一致而不是每次都“另起炉灶”。数学建模场景装“数据探索”“特征工程”“模型基线”“论文图表生成”类技能包。比赛时间紧张时Agent按固定管线跑通流程能帮你省出大量调参时间。AI漫剧场景漫剧创作经常涉及角色一致性、分镜脚本、画面风格控制、配音节奏这些环节特别适合做成技能包。把“角色设定表”“分镜模板”“画风关键词库”固化下来Agent生成的内容就会稳定很多。Java企业开发场景在Spring AI或Spring Cloud的Agent平台里把业务FAQ、API调用规范、数据权限规则、代码提交规范做成技能包能有效降低多个Agent协作时的混乱程度。5.3 国内Agent产品里的“Skills影子”如果你还不想折腾命令行和文件目录也可以先在成熟的国内Agent平台上理解这个思路。现在主流的智能体平台比如文心智能体、字节的豆包、月之暗面的Kimi生态、阿里的通义它们普遍提供“工作流”“知识库”“插件”“技能市场”这些能力。这些东西本质上就是Skills的平民化版本工作流把任务步骤固定知识库把经验资料喂给模型技能市场则是别人封装好的技能包你点一下就能用。我的建议是如果你是完全的新手先去这些平台把“搭一个工作流”的流程玩一遍理解清楚“什么时候让模型自由发挥、什么时候固定规则”等你理解了这套理念再到Claude Code或Codex里用文件方式管理技能会顺手很多。两种路径殊途同归都是在做同一件事把Agent的行为从“随机发挥”变成“有章可循”。6. 一场典型翻车的排查复盘从“反复返工”到“技能包一次过”6.1 现场还原一个前端落地页的三小时拉锯战有一次我需要Claude Code帮我写一个产品落地页技术栈是TailwindCSS加一个内部组件库。我给了它一个很简单的需求“做一个包含导航、Hero区、功能特性、轮播图、定价表和CTA的营销页面风格参考官网。”它第一次跑出来的页面导航能看Hero区能看但功能特性区域的卡片全部宽度不一致轮播图直接变成三张静态图片堆叠。我让它改它说“好的已修复”重新跑一遍卡片宽度正常了但页面的主题色全变了按钮从直角变成了圆角跟我当初给的参考完全不是一回事。三四个来回之后我已经不想再看它跑出来的东西了。当时脑子里只有一个想法这模型怎么回事明明需求说得很清楚为什么越改越乱6.2 完整排查链路问题到底出在哪一步我后来冷静下来用了排查链路把问题拆开看。第一步我打开Claude Code的调试信息把Agent每一步的Thought、Action、Observation完整展开。结果发现它每次行动之前确实“思考”了但思考的依据不是项目里的实际文件而是它自己记忆中“类似落地页应该长什么样”。第二步我发现它反复在做同一件事设计按钮样式。第一轮它没用组件库而是自己定义了按钮类我让它改它把Tailwind的默认样式和组件库样式混着用导致颜色和圆角对不上。这一步暴露了一个真相没有人告诉过它“这个项目的按钮组件是已经封装好的应该直接引用而不是每次重新发明”。第三步轮播图的问题更典型。它把轮播图做成静态图是因为它在项目里压根没找到可用的轮播组件。它没有去翻阅依赖包里的组件列表也没有去看项目的入口文件而是选择“简化处理”。第四步我翻看整个对话的上下文窗口发现模型确实在前几轮被反复“教育”但到了后面规则已经挤出了有效注意力范围。它并不是态度不好是真的没“记住”我最初提的参考风格。排查到这里结论已经清楚了问题不在模型在于整个执行过程中缺少一个“稳定加载”的规范文件。我每一次的修改反馈都是临时的用完即丢模型下次又要重新猜。6.3 技能包入场把项目规范变成强制加载项我先在项目根目录建了.claude/skills/frontend-policy/SKILL.md把这个项目从零开始执行就必须遵守的规则写进去--- name: frontend-policy description: 项目级前端开发规范。所有涉及页面开发、组件修改、样式调整的任务都必须加载本技能。 --- # 前端开发强制规范 1. 按钮、输入框、卡片等基础组件必须直接引用项目封装的UI组件禁止在页面内重写样式。 2. 颜色一律使用Tailwind配置中的设计令牌不允许出现硬编码的十六进制颜色值。 3. 页面中的轮播图、弹窗、表格必须优先使用依赖包内已有组件。 4. 页面整体间距参考官网现有页面的间距体系比例为4的倍数。 5. 完成开发后必须检查页面在移动端宽度下的显示效果并给出去掉横向滚动条的处理方案。然后我重新开启了一个会话只给了一句话“用frontend-policy技能按官网风格做这个落地页。”这一次它没有“重新发明”任何东西按钮用了组件库颜色来自设计令牌轮播图从依赖包里找到了现成组件页面间距和官网保持了一致。最重要的是整个开发过程我只沟通了一轮它交出来的页面基本能直接进入微调阶段。6.4 前后效果对比差距并不是一点半点维度没有Skills时使用Skills后完成一个页面需要的沟通轮数5-8轮1-2轮按钮样式与设计规范一致性时好时坏经常混用始终一致组件复用情况极少主动复用自动使用现有组件输出格式错误每两轮出现一次基本消除移动端适配经常被忽略每次主动检查这次经历给我的触动很大。过去我总觉得“让AI干活”的重点是“提示词写得细”但这次之后我明白了一次性的“提示词写得细”远不如“让正确技能自动加载”靠谱。临时交代会随上下文滚动被遗忘技能文件则每次任务开始时都能稳稳地注入上下文。7. 新手避坑清单与我的调教心得7.1 五个最容易踩的坑坑为什么会发生怎么解决Skills描述不精准触发不到description里没有覆盖用户可能的说法把日常表达列出来写进描述里SKILL.md正文太长上下文被占满想“一次性教会”Agent所有事正文控制在一次任务能消化的范围参考细节放附加文件同名技能覆盖了旧技能多个仓库里的技能重名给技能目录加上前缀比如team-fe-frontend目录路径放错技能没生效工具只扫描特定目录不是随便放哪都行先确认工具的文档再放全局或项目目录更新技能后不重开会话当前会话没有重新扫描技能目录改完文件后强制新开会话再测试7.2 新手该怎么安排学习顺序先别急着写自己的技能。第一步是“抄”去GitHub找几个口碑好的技能包装进工具里用两周感受一下一个“正确”的技能长什么样第二步是“改”把别人的技能改成适合你自己项目的规则第三步是“写”从你最熟练、最频繁的小任务开始独立写第一个SKILL.md第四步是“沉淀”每隔一段时间把你踩过的新坑补进对应技能文件里让技能包跟着项目一起迭代。要注意的是技能数量不是越多越好。我见过有人一口气装了四五十个技能结果Agent每次启动都要扫描一遍目录响应变慢而且因为技能之间相互重叠触发经常混乱。我个人的经验是一个项目里保持10到20个高质量的技能包已经能覆盖绝大多数日常需求。与其贪多不如把几个核心技能打磨到“扔给任何人用都不会出错”的程度。7.3 一点个人体会我搭自己的Skills库到现在差不多有快一年的时间最大的体会是AI Agent其实不太怕“能力不行”反而很怕“没规矩”。你给它的规则越明确它发挥得越稳定你让它全靠临场理解它就把随机性全还给你。Skills这个东西本质上是把你脑子里的“项目常识”外化成文件让模型每次开工前先读一遍。它不是魔法但它是把AI的“超能力”真正落到项目里的基础设施。所以别在“换哪个模型更好用”这件事上无限纠结。花一个下午把你那个最容易翻车的任务整理成一份SKILL.md装上重开会话再跑一次。你会回来感谢那个愿意动手写技能包的自己。