最近我一直在折腾 Agent Skills就是 Claude 在 2025 年推出的那套 skills 机制。最开始是在社区里看到有人把一套代码审查规范写进SKILL.md然后每次让 Claude Code 做 review它都能严格按同一套标准执行。这比我过去把一长段 Prompt 复制来复制去要高效太多了。后来我自己的项目里也开始逐步铺开 skills从代码审查、写周报、生成视频分镜脚本到给论文搭框架凡是“流程稳定、标准明确”的活儿我都往 skills 里塞。这篇文章不是什么官方教程是我自己从零开始研究、安装、开发、踩坑的记录。如果你也好奇 Agent Skills 到底是个什么东西、为什么社区里突然都在讨论它、以及怎么把自己重复性的工作流固化成 skill那这篇文章应该能帮到你。我会先聊清楚它的底层逻辑再给出一套可以直接落地的实操路径最后把我在真实项目里踩过的坑也一并说透。1. 为什么说 Skills 是 Agent 应用的“方法论插件”1.1 从一段反复复制的 Prompt 说起先说一个我自己的真实场景。几个月前我经常让 Claude Code 帮我做代码审查每次都得在后面补一大段要求“请重点检查资源泄漏、并发安全问题、错误处理是否有遗漏输出的时候按严重程度分级给出具体文件位置和修复建议。”这套话我复制粘贴了无数次稍微改一个词就得重新调。更烦的是如果中途换了对话窗口这段话就是一张白纸模型完全不记得之前约定好的审查标准。我也试过把规则写进项目里的CLAUDE.md但问题又来了CLAUDE.md是全局规则不管我让它写文案还是查 bug这些审查规则都躺在上下文里。如果项目再大一点规则文件动辄几百行每次对话都白白烧掉大量 token而且系统提示词越长模型对具体任务的注意力反而越分散。Skills 恰好就是来解决这个矛盾的。它把“怎么做好某件事”的过程性知识比如审查标准、写作风格、分析框架封装成一个独立的、可以被按需加载的包。用的时候才加载不用的时候完全不占上下文。这个设计思路其实和前端开发里的按需引入很像不把整个组件库塞进首屏用到哪个模块再动态 import 哪个。所以我才会说Skills 是 Agent 应用里的“方法论插件”。1.2 Skills、MCP、普通 Prompt 和插件的边界我知道很多人第一次接触 skills 的时候会把它和 MCP、插件、普通 Prompt 搞混。我也花了挺长时间才把这几者的边界理清。直接看对比表形态本质解决什么问题不解决什么普通 Prompt一次性指令单次任务的行为控制无法跨对话复用CLAUDE.md / AGENTS.md全局规则项目级的行为约束无法按任务按需触发常驻上下文占 tokenMCP Server工具与数据连接让模型能调用外部 API、数据库、文件系统不替模型决定“怎么用工具”Skills可复用的任务流程与方法论把完成一个任务的标准步骤沉淀下来不提供新工具工具能力还是要靠 MCP我用一个比方来理解它们的分工MCP 是给模型装上了“手”和“眼睛”让它能拿文件、查数据库、调接口而 Skills 是给模型一本“操作手册”告诉它拿到工具之后先干什么、后干什么、按什么标准验收。两者不是竞争关系是上下游关系。一个 skill 完全可以依赖某个 MCP Server 提供的工具来完成步骤比如 skill 里写了一步“调用地图服务获取距离”真正执行的时候还是得靠对应的 MCP 工具。这个区分很重要因为它决定了你的预期管理装了一堆 skills 但没配 MCP模型照样“手无寸铁”反过来只配了 MCP 但没有 skills模型虽然有工具却每次都要重新摸索一套做事流程输出质量极不稳定。2. 第一性原理拆解一个 SKILL.md 在运行时经历了什么2.1 按需加载不是所有技能都塞进上下文网上有一篇很火的文章叫《Claude Agent Skills: A First Principles Deep Dive》标题里的“第一性原理”我很喜欢。因为 skills 这个东西表面上是多了个文件夹格式但本质上它改变了 Agent 处理知识的方式。在没有 skills 之前模型的知识要么来自训练数据要么来自对话里的上下文。训练数据是“死”的对话上下文是“临时”的两者都没法很好地承载“经过沉淀的、可复用的方法论”。而 skills 引入了一种新的知识注入方式模型会先看一眼当前用户请求再扫一遍所有已安装技能的description字段判断哪个技能与当前任务相关。一旦命中系统才会把那个技能文件夹里的SKILL.md内容注入到上下文里。这个机制说白了就是检索 注入或者叫“上下文工程的懒加载”。它最直接的好处是技能数量可以很多但任意时刻真正占用上下文的只有被命中的那一两个。装 50 个 skills 和装 5 个日常对话的 token 消耗几乎没有差别差别只发生在任务触发的那一瞬间。2.2 Frontmatter 是门面正文是操作手册一个标准的 skill 文件夹结构是.claude/skills/ └── code-review/ ├── SKILL.md └── scripts/ └── scan.py.claude/skills是 Claude Code 默认读取的目录code-review是技能名技能文件夹里必须有一个SKILL.md文件其他脚本、模板、资源文件都可以放在同目录下按需引用。SKILL.md的开头是一段 YAML frontmatter长这样--- name: code-review description: 对代码变更做系统性审查重点关注资源泄漏、并发安全、错误处理遗漏。当用户要求 review、复查、检查代码时优先使用。 ---name是技能的唯一标识一般要求跟文件夹名一致description是模型的“检索索引”决定了这个技能什么时候会被命中。我在后面会专门讲 description 写不好会带来多大的坑这里先记住一句话description 写的是“什么场景下用我”而不是“我是什么”。官方文档里还支持额外声明一些可选字段用于控制技能允许调用的工具范围。我建议碰到不认识的字段先查文档确认再用不要照抄第三方项目里充满自定义字段的模板。frontmatter 下面是正文格式就是普通的 Markdown。正文写的是具体的操作流程用哪些工具、按什么顺序执行、每个步骤的验收标准是什么、最终输出长什么样。我习惯在正文里放三块执行步骤、强制检查清单、输出格式模板后面开发示例那节会给出完整骨架。2.3 一次调用的完整时间线我实测下来一次 skill 调用大致经历这么几步用户在对话里输入一句“帮我 review 一下这次改动”。模型开始扫描所有已安装技能的 description做相关性匹配。命中code-review技能后系统读取该技能目录下的SKILL.md注入上下文。模型按正文里的步骤执行过程中可以调用辅助脚本比如 scan.py和 MCP 工具。最终按正文规定的输出格式返回审查结果。整个过程用户能感知到的只有第 1 步和最后的结果中间发生了什么几乎是无感的。这种“一句话触发一个完整工作流”的体验确实是以前靠复制粘贴 Prompt 得不到的。我第一次跑通这个流程的感受就四个字打开新世界。3. 安装与选型我在官方市场和 GitHub 淘 skills 的实操记录3.1 存放目录与安装步骤先解决最基础的问题skills 从哪来、装到哪去。Claude 的 skills 有两个层级项目级放在当前项目根目录的.claude/skills/下跟着仓库走团队成员 clone 下来就能共用。用户级放在~/.claude/skills/下对你机器上的所有项目生效。Codex 的机制类似目录换成了.codex/skills。我自己的习惯是偏向全流程通用的技能放用户级比如“写周报”“代码审查”跟具体业务强绑定的放项目级比如“初始化新服务”“生成某个规范文档”。安装方式无非两种从官方市场一键装或者从 GitHub 上clone/ 下载压缩包释放到对应目录。以从 GitHub 安装为例一条命令就能完成mkdir -p ~/.claude/skills git clone https://github.com/yourname/code-review-skill.git ~/.claude/skills/code-review装完之后在 Claude Code 里输入/skills可以列出当前环境所有可用的技能输入/skill 技能名可以直接指定调用某个技能不用等模型自动触发。我建议每次装完新技能都先跑一遍/skills确认目录被正确识别免得后面排查半天发现是路径拼错了。3.2 我筛选第三方 skills 的三个硬性标准现在社区里 skills 数量已经很多了GitHub 上一搜一大把合集类仓库也遍地都是。但“数量多”不代表“质量高”我自己筛选第三方 skills 有三条硬性标准最近是否还在维护。看仓库最后 commit 时间超过三到六个月没动静的默认按弃坑处理。Agent 相关的技术栈更新极快半年不更新的技能很可能已经跟当前模型版本的行为对不上了。依赖是否可控。有的技能会在正文里写着“调用 XX 云服务”“需要配置 OPENAI_API_KEY”这种我一律不装。我偏好只依赖模型自带工具和轻量本地脚本的技能依赖越少出问题的可能性越低。内容是否可审计。安装后我会把SKILL.md从头到尾读一遍。凡是出现“读取 ~/.ssh 下的密钥”“递归删除目录”“把文件上传到指定服务器”这类指令的直接丢弃。这跟信任不信任作者没关系纯粹是安全底线问题后面专门讲。3.3 打开新世界的那几类 skills我把我实际用过、觉得真正提升效率的技能类型整理了一下类型典型用途我的使用频次代码质量类代码审查、重构建议、提交信息生成每天内容生产类论文框架搭建、博客大纲、分镜脚本生成每周数据整理类网页正文转 Markdown、CSV 分析、批量重命名每周流程规整类新项目初始化、接口文档生成、周报汇总每天这里特别说一下内容生产类。比如写视频分镜脚本好的 skill 和差的 skill 差距非常明显。差的就给你一个模板然后说“请根据主题填写”好的会把景别、时长、运镜、台词、音效、转场方式全部拆成检查清单还会附带两三个参考示例。我第一次用一套质量高的分镜 skill 生成脚本直接就能拿去拍摄比我自己写的还细。这也是为什么我会说skills 的价值不在数量而在单个技能封装的“方法论厚度”。4. 手把手开发一个可复用的 skills以代码审查为例4.1 先写“使用场景说明”再写正文很多人第一次开发 skill 上来就写正文写着写着就变成了一个大杂烩。我的经验是顺序反过来先明确两件事——用户会在什么场景下触发它以及每次执行必须稳定输出的标准是什么。以代码审查技能为例。触发场景很清晰用户说“帮我看看这次提交”“review 一下这个 PR”“检查这段代码有没有问题”。必须稳定输出的标准是覆盖资源释放、并发安全、错误处理、可观测性这几个固定维度输出按严重程度分级每条问题都要指出具体文件位置和修改建议。这些就是技能的核心价值正文围绕它们展开就够了贪多反而稀释重点。判断一个任务适不适合做成 skill我有个简单标准同一个要求如果你已经用手动 Prompt 重复做过三次以上就可以做 skill 了。反过来一次性任务、流程高度不确定的任务做成 skill 就是自讨苦吃。4.2 SKILL.md 的完整骨架下面是我自己写的一个精简版代码审查技能你可以直接抄过去改--- name: code-review description: 对代码变更做系统性审查重点关注资源泄漏、并发安全、错误处理遗漏。当用户要求 review、复查、检查代码、分析提交时使用。 --- # 代码审查指南 ## 何时使用 - 用户提交了一段代码、一个 diff、一个 PR 或一次 commit要求做审查。 - 用户在调试问题时希望定位潜在隐患。 ## 审查流程 1. 先读取目标代码或 diff理清变更范围和涉及模块。 2. 运行 scripts/scan.py 获取静态扫描结果作为审查输入之一。 3. 按下列检查清单逐项核对记录所有发现的问题。 4. 汇总输出按严重程度排序。 ## 强制检查清单 - [ ] 资源是否在 all paths 下都被正确释放文件句柄、数据库连接、网络请求。 - [ ] 并发场景是否存在共享可变状态锁的粒度是否合理。 - [ ] 异常是否被捕获但未记录是否吞掉了关键错误信息。 - [ ] 是否硬编码了密钥、IP、账号等敏感信息。 - [ ] 是否有明显的边界遗漏空值、越界、超时、重试。 ## 输出格式 按以下 Markdown 模板输出 ### 审查结果严重程度P0/P1/P2 - **文件与位置**xxx.py:42 - **问题描述**连接未关闭 - **修改建议**使用 with 语句或 try/finally 确保释放注意几个细节。正文里的“审查流程”是给模型看的执行步骤不是给人看的文档所以要写成明确、可执行的动作。强制检查清单是防止遗漏的关键模型在某些情况下很擅长偷懒你写了五条它可能只检查三条但如果清单是显式的命中率会高很多。我在开头的 frontmatter 里把 description 写成了两句话第一句说明技能能力第二句列出触发词。这是我自己测试下来命中率最高的写法比只写一句“对代码做审查”要稳得多。4.3 让脚本真正参与干活一个纯文本的 skill 已经能解决很多问题但如果想让 skill 输出更可靠我强烈建议给它配一个辅助脚本。比如代码审查技能里我放了一个scripts/scan.py用来扫描一些模型仅靠肉眼容易忽略的模式import re import sys from pathlib import Path target_dir Path(sys.argv[1]) if len(sys.argv) 1 else Path(.) patterns [ (open(, 文件句柄疑似未关闭), (except:, 裸捕获异常缺少错误类型), (TODO|FIXME, 遗留标记), (password\s*\s*[\][^\][\], 硬编码密钥), ] for path in target_dir.rglob(*.py): text path.read_text(encodingutf-8, errorsignore) for pattern, label in patterns: for match in re.finditer(pattern, text): line_no text[:match.start()].count(\n) 1 print(f{path}:{line_no} [{label}] {match.group(0)[:80]})脚本本身很简单但它解决的问题很实际模型在审查长文件时可能漏掉某些模式脚本可以做一个机械化的兜底扫描把所有可疑点喂给模型再让模型结合上下文判断真伪。这里有个容易踩的坑脚本放在 skills 目录里但 SKILL.md 正文里没有明确告诉模型“先运行脚本”那么这个脚本基本等于白放。模型不会主动去探索技能目录里有什么文件你必须显式地在流程里写清楚。所以我第 3 步专门写了“运行 scripts/scan.py 获取静态扫描结果”。4.4 用真实改动验证开发完 skill 不等于结束必须做一次完整的验证。我的做法是准备一个测试仓库故意制造三类典型问题——一个没关闭的文件对象、一个裸except:、一个硬编码的密钥然后触发技能。验证时重点观察三件事模型是否成功加载了这个 skill可以在对话里直接问它“你现在按什么标准审查”或者观察 Cli 的日志输出。模型是否按正文步骤执行有没有跳过检查清单里的某几项。脚本的输出有没有被模型实际引用还是模型完全无视了脚本结果。第一次验证我基本都会发现问题最常见的是流程跳跃。正文写了六步模型只走了三步剩下完全靠猜。这时候不要急着改模型回来改 SKILL.md 的表达把步骤再拆细、把动作写得更明确。开发 skills 的核心工作不在写文件而在反复打磨“模型能否按你设计的流程走完”。这个理念和写单元测试很像先定验收标准再反推设计最后迭代到稳定。5. 实测避坑描述写不好、正文太空、脚本不生效5.1 Description 宽泛触发全靠缘分这是我在第三方 skills 里见到最多的问题。很多作者把 description 写成“检查代码质量”或“生成文章大纲”看起来没毛病但模型在面对一个具体请求时根本没法判断这个技能是否适用。我对比测试过的正例是“对代码变更做系统性审查重点关注资源泄漏、并发安全、错误处理遗漏。当用户要求 review、复查、检查代码时使用。”反例就是“检查代码质量”。前者让模型知道什么时候用和用了之后重点管什么后者只有一句模糊的能力描述。另外注意技能名冲突。如果有人给你一个叫writer的技能你本地已经有一个writer后者会把前者覆盖掉而且不会报错。安装之前先看一眼~/.claude/skills/目录避免同名覆盖导致旧技能静默失效——这个坑我踩过一次排查了很久。5.2 正文里的“祈使句幻觉”我给这一类问题起了个名字叫“祈使句幻觉”正文里写满了“要仔细检查”“要认真分析”“要注重细节”这类话全是祈使句但模型看完依然不知道该做什么。问题在于“认真”“仔细”这类形容词无法被转换成具体动作。比如我让模型审查错误处理它确实会“认真”地看但看完可能只给出“异常处理方面需加强”这种毫无信息量的结论。正确的写法是把形容词翻译成动词模糊表达可执行表达要仔细检查资源泄漏逐文件核对 open() / connect() 是否在 all paths 下被关闭认真分析并发安全检查是否存在共享可变状态锁的粒度是否覆盖所有写路径注意错误处理定位所有 except 块确认是否记录日志并向上传递关键错误这条原则不仅适用 skills也适用任何想稳定约束模型行为的场景。模型不擅长从抽象要求里推导具体标准但它很擅长照着明确 checklist 执行。5.3 上下文不是无限的SKILL.md 越长触发时越拖累我一开始写技能有个毛病什么都往里塞。一份 SKILL.md 写到两三百行美其名曰“全面”结果实测发现技能一触发两三百行直接注入上下文多轮对话中每次技能被调用都会反复占用窗口。到后面对话里其他任务的质量明显下滑。后来我学到的原则是SKILL.md 正文只保留“步骤 检查清单 输出格式”把大段的参考资料、示例代码、详细规则放到同目录下的references/或examples/文件夹里让模型按需读取。正文控制在 80 到 150 行左右既能完整承载流程又不至于喧宾夺主。这点对长会话尤其重要。一个 session 里如果既要做代码审查又要写周报每个技能都是精简版的话上下文余量就还很充裕如果每个技能都塞一大堆背景知识后半段对话质量会肉眼可见地下降。5.4 安全审查安装第三方 skills 前必须做的事最后是这个话题里最重的一部分。SKILL.md不是什么被动文档它是一份给模型的行动指南。装了一个恶意或粗糙的 skill相当于你把模型的行动手册交到了别人手里。模型看完里面的步骤之后完全有可能执行rm -rf、读取你的密钥文件、把项目里的代码上传到某个服务器。它不一定真的会做但如果 skill 的步骤里写了模型在高权限模式下执行这些命令的可能性就是存在的。我安装第三方 skills 的安全流程是先读全文再安装。下载下来先别急着解压进目录先看 README 和SKILL.md出现“读取 ~/.ssh”“上传文件”“删除目录”“执行任意 shell 命令”之类的字眼直接扔。在隔离目录里跑一次。把它装到临时项目下随便给个测试文件让它触发同时盯着它调用了哪些命令、有没有产生网络请求。最小权限。不要给模型挂载整个家目录。我自己日常开发用的目录都是显式指定的避免某个技能把无关文件一锅端载入上下文造成敏感信息泄露。提示官方市场里的技能相对有审核但也不能默认完全可信。GitHub 上的个人项目更是参差不齐安全审查这一步无论如何不能省。6. 生态对比与下一步Skills、GitHub 学习课程与各平台现状6.1 Claude、Codex 与 GitHub Skills 的差异聊到这儿有几个概念需要拉出来对比一下不然很容易混。首当其冲的是 GitHub Skills。你在 GitHub 上搜 “skills”看到的很大一部分是 GitHub 官方出的系列化交互课程教你怎么用 Actions、怎么用 Copilot 的那是学习平台不是 Agent skills。虽然都叫 skills但跟 Claude Agent Skills 或 Codex Skills 是两码事。真正的 Agent skills 生态目前公认的起点是 Anthropic 在 2025 年推出的 Claude Agent Skills 机制它配套了官方市场和一个收录社区技能的仓库让我这种普通用户能在一个相对统一的地方发现和安装技能。值得关注的是OpenAI 的 Codex 也已经把 skills 目录纳入到它的 Agent 体系里目录结构和文件格式与 Claude 的做法高度一致。这种“格式对齐”是好事——它意味着SKILL.md这套抽象的标准化程度在提高未来跨平台迁移一个技能的迁移成本可能会变得很低。我不确定 Codex CLI 的调用指令跟 Claude 是否完全一致但目录级的规则是公开的你按.codex/skills去放技能基本不会错。放在更长的时间尺度看我觉得 skills 才是这轮 Agent 竞争的真正焦点。模型能力本身会趋向同质化各家比拼的将是“谁能让模型更好地按照你的方法论稳定干活”。skills 提供的就是这层支持而且它有潜力发展成类似“订阅源”的开放交换生态——你今天写的一套审查方法论明天换个工具、换个平台、换个团队依然可以继续用。6.2 从“用 skills”到“写 skills”最后聊点我个人的体会。我目前装了四十多个 skills日常高频使用的其实就十个左右。装了这么多之后最大的感受是真正有价值的技能不是从网上淘来的而是把你自己反复在做、又一直做不稳定的流程沉淀成 SKILL.md。网上那些通用技能给你的是别人的方法论你拿到手要调、要改、要适配最后往往还是得自己写最顺手。所以我现在给自己定了一条规矩同一个手动 Prompt 重复出现三次就强制自己写一个 skill 来取代它。不追求一次写对先写一个粗糙版本跑通再根据失败案例不断打磨。做这个事有点像给团队写培训手册也像写单元测试它逼你把自己脑子里的模糊经验变成一套可执行的明确标准。这份约束力对个人或团队来说都是一种底层能力的提升。我最近正在把自己的博客写作流程做成一整套 skills选题分析、素材整理、初稿生成、事实核查、SEO 检查每个环节一个技能串成一条流水线。等项目再跑一跑我再把实际效果和数据分享出来也算给这篇记录留个续集。