打开任何技术社区近半年最热的词几乎都是同一个skills。严格来说这个词不算新但2025年10月Anthropic正式把Agent Skills概念化并落地之后整个AI Agent开发的方向都变了。我自己最直观的感受是以前我们拼命把提示词写得天花乱坠模型该迷路还是迷路现在把知识和动作打包成技能包放进目录模型反而老老实实按步骤干活。这篇文章把我这段时间在Agent Skills上的摸索完整摊开来讲从核心原理到落地代码再到我实际踩过的坑一次性说透。适合所有正在做Agent产品、或者准备入局AI工具开发的朋友参考。1. Agent Skills到底是个什么东西1.1 从一个“给模型装外挂”的思路说起Agent Skills最朴素的理解就是把某个领域的全部经验、操作步骤和工具代码打包成一个文件夹模型在对话中需要这个能力时会动态地把这个文件夹里的关键内容拉进上下文然后按照里面约定的逻辑去执行。我一开始看到这个概念时心想这不就是RAG加提示词模板吗真正动手之后才发现完全不是一回事。RAG是检索完把资料丢给模型自己发挥Skills则是把怎么做这件事直接变成一套可执行的剧本模型拿到的是方法论不是资料堆。举一个最容易理解的类比你请了一个实习生模型传统Prompt是你口头给他讲一遍工作流程他记不住也容易漏Skills等于你给他一本图文并茂的SOP手册外加一套自动化脚本他只需要照着手册一步步执行就行。这个思路在实战场景里效果非常明显。比如我做的SEO内容审核Agent以前靠一段超长system prompt反复声明不要漏掉Meta描述注意关键词密度模型每次还是会丢三落四。改造成Skills之后把审核标准写成SKILL.md把关键词密度计算逻辑做成Action脚本效果立刻稳定了。1.2 为什么传统的System Prompt玩法扛不住了要理解Skills为什么这么火得先说清楚传统方案的痛点。用过Agent的人都有这种体验System Prompt里塞了20条规则模型在简单任务上表现完美一遇到复杂的多步任务就开始顾此失彼前面记住了后面忘了。这其实是上下文窗口资源的分配问题——规则长度占了不少额度但真正执行时模型根本不会逐条翻看。更麻烦的是工具调用。传统方案里你注册一堆函数让模型自己选但模型一旦面对10个以上工具选错工具的几率会直线上升。我见过一个金融问答Agent工具列表里有获取股票价格和获取财报数据模型经常在两个工具之间犹豫甚至连续调用七八次才能找对。这是模型推理能力的天花板不是你提示词写得不够好。还有一个隐藏成本维护。每改一条业务规则就要重新编辑那段巨长的提示词改完后还得反复测试确认其他逻辑没被破坏。团队协作时更头疼不同人给出的规则之间有冲突没人敢删最后System Prompt膨胀到上万个token模型输出质量反而下降。所以问题的本质在于传统方案是把规则塞进对话里而Skills的思路是把规则组织成模型可以按需使用的模块。逻辑重心从让模型记住变成了让模型找到并执行这才是符合大模型工作方式的正确方向。1.3 和MCP到底什么关系很多人搞混了现在社区里最容易出现的误解就是把Agent Skills和MCP当成同一个东西。我刚开始接触时也困惑过有一次在群里脱口而出Skills就是MCP的本地版立刻被朋友纠正了。这两个东西解决的是不同层级的问题。MCPModel Context Protocol解决的是如何让Agent连接外部工具和数据的协议问题比如连数据库、调企业内部API、访问网页搜索。它对标的是曾经混乱不堪的插件协议核心贡献是把工具调用变成了标准化接口。Skills解决的是如何让Agent知道某个任务怎么做得更好的问题它打包的是经验、流程和本地逻辑不强制依赖外部服务。你可以把Skills理解为给特定任务写的专属操作手册。这里有一个容易混淆的点Skills里的Action脚本确实可以调用MCP服务两者可以嵌套使用。但产品定位上MCP是连接器Skills是方法论。如果你特别依赖某个外部系统该用MCP如果你想沉淀一套内部知识库和工作流Skills明显更合适。我的建议是从实际场景出发需要接外部数据系统优先解决MCP流程不稳定、提示词反复试都不对劲就考虑Skills。顺手列个对比表供参考对比维度MCPAgent Skills核心定位连接外部工具与数据的协议沉淀领域知识、流程、动作的技能包资产形式远程/本地服务经协议暴露接口本地文件夹包含指令、脚本和上下文加载方式运行时按需访问客户端注册的工具对话中动态匹配描述按需注入上下文适用场景接数据库、API、浏览器等外部能力把内部经验、操作逻辑、提示词模板标准化依赖关系可以被Skills中的Action调用可以拿来做编排层底层调用MCP工具2. 上手Skills第一件事理解文件夹即技能包2.1 SKILL.md是逆行代码的核心先别急着玩花活Agent Skills的物理形态就是一个文件夹里面最少要有一个SKILL.md文件。这个文件的命名是硬性规定当初我图省事存成skill.md结果Agent识别不到排查了半天才反应过来文件名字母必须大写。SKILL.md的写法规格已经比较成熟了最核心的部分是YAML格式的name和description字段别看就两行这里直接决定了你的技能会不会被模型正确调用。模型的运作方式是先看你所有技能包的description再根据用户请求去匹配最合适的那个所以description就是你的技能包的门面。我第一次写description的时候用了一个非常泛的描述代码审查工具。结果模型经常在该用的时候不调用不该用的时候乱用。后来改成动词对象场景的写法对Pull Request中的代码变更做安全性、性能、可维护性审查输出带严重级别标记的问题清单适用于代码合并前质量把关调用准确率立刻上来了。实测下来description里动词越具体、边界越清晰模型选技能的准确率越高。正文部分写步骤时也有讲究。模型对Markdown结构感很强但不要指望它像人一样从头到尾读一遍再执行它更像是一个滑动的焦点在文档上移动。所以正文里少写无关的废话把步骤拆成操作性强的清单每条步骤用祈使句开头比如读取src目录下所有Python文件对每个文件执行如下检查项。这种直接命令式的写法实测比长篇大论的效果好得多。2.2 动作脚本是技能包的四肢选型要看场景SKILL.md只是指令部分Action才是真正干活的代码。Action一般放在skills目录下的actions子目录里可以是Python、Node.js、Shell脚本甚至编译好的二进制。选择脚本语言时别跟风先想清楚这个动作通常要在什么环境里跑。我给自己的项目复盘后总结了三条选型心得如果你要处理的是文本分析、代码统计、JSON格式化这类纯本地的数据操作Python几乎是首选生态里什么库都有而且Claude的技能包对Python支持最完整。如果动作涉及网页DOM操作或者要配合Node生态那Node更顺手。如果只是简单文件批处理Shell脚本反而比前两个都靠谱不需要额外依赖。Action脚本的编写有一个核心设计原则跟Agent配合时脚本的输入和输出都要做严格的透传设计。你的脚本不应该是完整的独立程序它只做一件事把输入处理成输出并且输出尽量用结构化格式比如JSON这样模型拿到结果才能继续推理下一步。我踩过最典型的一个坑第一次写Action脚本时习惯性地在代码里加了个结果缓存心里想的是这样省得模型重复调我。结果有一次同一个价格连续调了三次模型拿到了三个不同的值。后来我把有状态的逻辑全删掉脚本改成纯函数式的无状态操作问题才消失。记住在Agent协作场景里可预测性比性能优化重要得多。2.3 上下文注入不是越详细越好拼的是取舍能力每个Skills目录下还可以放Context资源比如参考文档、模板文件、数据字典这些内容会在模型执行技能时被自动注入上下文。我一开始猛堆资料一个技能包放了十几个Context文件图文并茂觉得自己特别贴心。结果实测下来发现这完全是个坑。上下文窗口是有限资源你塞的Context越多模型用来思考核心任务的空间就越小。最夸张的一次我的合规检查技能的Context占了三万多个token模型在做判断时明显开始敷衍直接根据文件里的例子生搬硬套完全失去了灵活性。Context的取舍原则我现在总结成一句话只放模型自己查不到或容易查错的信息。比如某个API返回的JSON字段含义、公司内部的加密规则、某个特定客户喜欢的技术栈偏好这些值得放。但像Python基础语法、HTTP状态码定义这类模型脑子里已经有现成知识的东西就完全不需要浪费Context空间。另外建议给Context文件做优先级排序把高层级、必须遵守的内容放在靠前的位置。虽然现在的模型上下文注意力机制已经比早期版本好了很多但仍然存在中间遗忘问题。我见过把关键规则放最后一个文件的模型实际执行时就真的把它当成了可选的附录。3. 动手搭一个真正可用的技能完整实操记录3.1 场景拆解做一个代码审查技能目标别定太大理论讲再多都不如动手跑一遍。我选了一个几乎每个技术团队都需要的场景来做演示代码审查Code Review。这个场景足够典型因为它在很多团队里是纯体力活而且特别适合体现Skills的价值。先拆需求好的Code Review应该检查哪些东西我把代码审查分为四个维度安全性比如是否有SQL注入、硬编码密钥、危险的反序列化操作性能比如是否有O(n^2)循环、N1查询、大对象拷贝可维护性比如命名是否清晰、函数是否过长、有无明显代码异味兼容性比如是否依赖语法糖导致旧环境跑不起来、是否有破坏性变更。这些维度如果用传统Prompt大概得写两三千字而且每次审查结果质量都随模型心情波动。我决定做成一个技能包让AI自动读取diff检查已知问题模式最后输出规范化的审查报告。需要说明的是这里的代码审查技能先不看你的工程上下文重点是展示Skills的骨架怎么搭。真正要拿到生产环境用还得配合仓库的CI/CD流程那部分后面在踩坑实录里会展开讲。3.2 编写SKILL.md好的技能文档长这样下面这份是我精简后的SKILL.md内容核心结构就是声明信息、角色定义、执行步骤、输出格式。直接复制就能跑你也可以在它基础上加自己的检查规则。--- name: code-reviewer description: 对代码变更执行安全性、性能、可维护性、兼容性四个维度审查输出带严重级别标记的问题清单。适用于合并请求、Pull Request的代码评审场景需要输入变更文件列表及diff内容。 --- # Code Reviewer 你是一名经验丰富的高级工程师负责对代码变更做结构化的质量审查。 ## 执行步骤 1. 列出变更涉及的所有文件并读取每个文件对应的 diff 片段。 2. 对代码进行审查检查点包括 - 安全性硬编码密钥、SQL 拼接输入、eval() 或 exec() 等危险调用、不安全的反序列化。 - 性能多层嵌套循环、明显 O(n^2) 复杂度、频繁进行 IO 但无缓存策略。 - 可维护性函数过长超过100行、命名随意a/b/c 等无意义命名、重复代码块。 - 兼容性依赖过新的语言特性却未提供回退方案、破坏现有 API 的修改。 3. 逐项记录问题按严重程度分级Critical必须修复、Warning建议修复、Suggestion可选优化。 4. 输出最终审查报告。 ## 输出格式 严格以JSON结构输出后续由Action脚本做格式化渲染 { summary: 整体审查结论, issues: [ { severity: Critical|Warning|Suggestion, file: 文件路径, line: 行号, title: 问题标题, detail: 问题说明及修复建议 } ] }我特意在文档末尾写了一段看似简单的严禁事项比如不要忽略测试代码的异常路径不要在白名单文件中标记安全问题。这些负面约束非常有用模型在遇到模糊情况时会更倾向于保守不会自作主张乱给结论。3.3 Action脚本把规则变成能跑的机器Skill的Action部分我用Python来实现一个核心函数解析diff文本并统计可疑模式。这个脚本并不复杂但它展示了Skills里Action和模型之间的分工模型负责语义判断脚本负责精确计算和文本处理。import json import re import sys def parse_diff(diff_text: str): changes [] current_file None current_line 0 for raw_line in diff_text.split(\n): if raw_line.startswith( b/): current_file raw_line[6:] elif raw_line.startswith(): match re.search(r\(\d), raw_line) if match: current_line int(match.group(1)) elif raw_line.startswith() and not raw_line.startswith(): changes.append({ file: current_file, line: current_line, content: raw_line[1:].strip() }) current_line 1 elif not raw_line.startswith(-): current_line 1 return changes def detect_dangerous_patterns(changes): patterns { hardcoded_secret: re.compile(r(?i)(api[_-]?key|password|secret)\s*\s*[\][^\][\]), eval_or_exec: re.compile(r(?i)\b(eval|exec|system)\s*\(), raw_sql_concat: re.compile(r(?i)(SELECT|INSERT|UPDATE|DELETE).*?\\s*[\w_]), potential_issue: re.compile(rtodo|fixme|hack), } issues [] for c in changes: for name, pattern in patterns.items(): if pattern.search(c[content]): issues.append({ severity: Warning, file: c[file], line: c[line], title: f检测到{name}模式, detail: c[content][:120] }) return issues if __name__ __main__: input_text sys.stdin.read() changes parse_diff(input_text) issues detect_dangerous_patterns(changes) print(json.dumps(issues, ensure_asciiFalse, indent2))这个脚本的输入是通过stdin接收原始diff文本输出是JSON格式的问题数组。模型拿到这个工具之后做判断时非常游刃有余因为它们终于不用靠记忆去猜哪些行是新增的直接看脚本解析出来的结果就行。不过我也得提醒一句Action脚本的职责边界要想清楚不是所有检查都能靠脚本自动化完成。比如函数是否过长这种语义判断脚本只能做粗略的行数统计真正判断还是要靠模型读上下文。所以我的设计里面脚本定位是候选标记模型负责决策判断两者合作效率和质量都能兼顾。3.4 把技能交给Agent目录摆放与实测迭代技能包写完之后要放到模型能感知的目录里。按照目前主流的Agent Skills配置方式在Claude Desktop或Claude Code的配置里指定skills目录路径然后把整个技能文件夹放进去重启即可。我实际测试后确认模型只有在对话中明确判断需要该技能时才会真正加载它所以不要指望任何对话里都能触发这是正常行为。第一轮实测我就翻车了。我让模型审查一个JavaScript的Pull Request它倒是正确识别出了要调用code-reviewer技能但输出结果显示它给所有可能有问题的地方都标了Suggestion级别连明显的SQL拼接也只给了Warning。我翻看它的推理过程发现问题出在SKILL.md里对严重级别的定义不够明确建议修复和必须修复之间没有量化边界。我调整了SKILL.md给严重级别加了硬性标准比如SQL注入风险、密钥泄露一律Critical与现有代码风格不一致、包括性能隐患在内的常规问题给Warning纯风格偏好给Suggestion。这样改了之后输出质量立刻提升了一个档次模型的判断稳定多了。这个细节非常值得注意给模型的规则里模糊的形容词会直接被模型按自己的偏好解释标准的可量化和可操作性比文采重要得多。4. 踩坑实录与排查技巧4.1 技能包放了但Agent完全不调用排查三步走我身边十个玩Agent的人至少六个人问过skills放好了为什么模型不调用。这类问题基本都能靠下面三步排查解决。第一步确认存放路径。有些版本对目录名有要求比如必须是英文、不能带括号并且SKILL.md文件必须在该目录的顶层。有人把所有文件摊在同一个目录下然后告诉Agent技能在根目录模型找不到文件当然不会调用。第二步检查description。这是最容易出问题的环节。很多人description写得太泛比如这是一个代码审查技能模型在具体场景里根本没法判断该不该用。排查方法很简单把用户本次请求和技能描述同时在心里过一遍如果你都觉得这个描述没用模型自然也不会用。第三步看Agent的日志。Claude Code这类工具会打印出模型思考过程包括它是否扫描了技能目录、是否考虑过该技能又否决了。如果模型考虑了但否决了那说明触发标准不对重新改description就行。如果日志里压根没有技能的痕迹那大概率是目录配置路径出了问题。4.2 Action脚本老是执行失败别急着甩锅给AgentAction脚本和模型之间的配合最烦人的就是环境问题。模型生成代码、调用脚本、读取结果这套链路里任何一环出错都会有连锁反应。我在自己的多个项目中遇到的典型问题可以梳理成下面这张表推荐直接存下来症状大概率原因解决方案脚本报ModuleNotFoundError缺依赖在技能目录里加requirements.txt并检查Python环境是否为全局环境脚本执行超时模型生成的输入数据太大在脚本里加输入大小限制超出则返回错误提示不硬扛输出乱码或解析失败脚本和模型对编码理解不一致统一在脚本内强制UTF-8编码输出避免使用系统默认编码同一脚本结果不一致脚本依赖了外部不稳定资源去掉脚本里的网络请求或随机数保持纯函数权限不足目录或文件无执行权限检查技能目录的读写权限必要时chmod设置权限位特别提醒一件事脚本的无状态设计真的是第一原则。我一开始把项目根目录路径硬编码在脚本里换来的是换一台机器、换一个仓库就全部失效。改成接受命令行参数或环境变量传路径之后这个技能才真正有了通用性。给脚本写代码时要把自己当成一个今天第一次用这个技能的人来考虑。4.3 上下文被垃圾数据污染模型判断飘了这个问题是Skills应用中杀伤力最大的隐形杀手。很多人的技能包Context目录里塞满了各种文档结果模型在实际生成时被无关信息干扰输出质量明显波动一会儿用文档里的东西一会儿又不用。我做过一次极端测试同一个技能包Context里只放必要文件的时候模型输出稳定我在Context目录里塞了一个完全无关的团队OKR文档后模型开始在某些步骤上跑偏。这说明大模型无法精准忽略上下文中的无关信息它会被看起来相关的东西带跑。解决方案有两个方向一是严控Context质量只放模型需要但不掌握的内容二是给Context文件加上明确的用途标签在SKILL.md里约定只有在涉及合规检查时读取合规文档其他上下文一律不主动使用。后者实测非常有效相当于给了模型一张重点图。另外提醒一个很细节但很实用的坑Context文件名尽量用可读性强的名字比如company_security_policy.md不要用final_rev3_clean.md。你要让模型在文件间做决策时一下就能判断该不该打开某个文件。从我实测的情况来看文件名对模型决策的影响比想象中大得多。4.4 维护技能包的迭代心法小步验证胜过憋大招技能包开发完不是结束真正的坑往往在上线几周后才暴露。我维护代码审查技能的过程中每隔几天就要根据新出现的问题调整规则所以一个稳定的迭代流程是非常必要的。我的维护流程一般是先在SKILL.md里加一条验证集章节里面放两三个典型的代码片段和期望输出每次修改规则后先用验证集跑一遍确认不破坏原有逻辑。这招帮我躲过了一个大坑——有一次我在规则里加了强制使用TypeScript类型定义的检查结果导致所有JavaScript项目的审查都疯狂报警要不是有验证集兜底我可能把错误规则部署到生产环境好几天都不知道。另一个值得分享的心得是Skills的输出格式尽量在早期就确定下来后面迭代时只改规则内容不要老改结构。因为一旦其他组件开始依赖你这个技能的输出格式比如后续的动作要解析这个JSON结构改动格式就要动一连串代码返工成本太高。还有一个团队协作的注意点如果多个人维护同一个技能包建议把禁止改动现有规则输出级别作为一个硬约束写进README。我团队里就出现过一次一个同事把某个规则从Warning级别提到了Critical结果全组所有项目的审查报告突然大面积飘红排查了半天才知道是有人改了级别。5. 从Skills再往前走几个真实场景的延展思路做完了代码审查技能很多人会问然后呢。我自己的体会是Skills最大的价值不是单独做某一个技能而是你手里握着越来越多技能包之后它们之间可以产生组合效应。Agent在复杂任务中会自己选择合适的技能来调用所以你完全可以把场景拆得更碎更专。先说内容生成场景。我平时写技术方案时会把技术方案生成和架构评审做成两个独立技能包。生成阶段用产品需求文档做输入让模型按模板产出方案评审阶段用另一个技能包去检查方案里有没有遗漏非功能需求。传统上一个Agent干这两件事会混成一团拆成两个技能包之后各自输出质量都更稳定。其次是代码库维护场景。我做过一个依赖升级助手技能把升级步骤、兼容性检查清单、回归测试脚本全部打包进去。模型拿到这个技能后能自动分析当前项目的依赖关系按步骤完成升级最后跑一遍测试并输出报告。这个场景里的核心不是升级命令而是如何保证升级不破坏现有功能那套完整流程。第三类是知识型技能。我们团队有一个客户信息速查技能里面放的是查询外部CRM的MCP服务配置、字段映射关系、以及常见查询模板。之前新员工进来要培训两个月才能熟门熟路现在让Agent用这套技能几分钟就能查出结构化信息并生成摘要。这就是典型的内部经验外部化。如果你现在问我什么技能值得优先做我的建议是先从你每周重复操作三次以上的事情开始。比如部署前检查、报告生成、代码审查、数据清洗、日志分析、文档撰写。别一上来就搞那种全知全能的大技能每一个技能都要小而专注描述清晰验证集齐整。技能包的库积累到10个以上之后Agent的能力会有一个跃迁式的提升那时候你再回头看看最初的做法会有完全不一样的感受。