上周帮同事梳理前端工程规范的时候我突然意识到自己很久没有“手把手教”Claude 做事了。以前要让模型按团队规范审查代码我得先把几十条规范粘进对话框再附上两个正面例子、一个反面例子折腾半天才能换来一份勉强能用的结果现在我只输入一条命令它会自己去翻一份叫 SKILL.md 的文件然后按部就班地把活干完。这个变化的核心就是 Agent Skills——一种把“如何做一件事”的方法论打包成 agent 能自主读取、按需调用的能力单元。这篇文章不是官方文档的翻译而是我把 Claude Agent Skills、Codex Skills 以及整个技能生态里的主流玩法摸了一圈之后的实战总结适合已经在用 Claude Code、Codex或者想把自己的重复性工作沉淀成可复用技能的开发者。先说结论Skills 不是一个新插件格式也不是简单的“提示词合集”它是介于“临时对话指令”和“完整外部程序”之间的一种轻量能力封装。理解了这个定位你才能知道什么时候该写 Skill、什么时候该用 MCP、什么时候干脆写个独立脚本。1. 先搞清楚 Skills 的本质它不是插件也不是提示词合集1.1 为什么越聊越乱对话式 agent 的上下文困境用过 Claude 或 ChatGPT 写代码的人应该都有这个体验刚开始几轮对话质量很高聊到后面模型会逐渐“忘记”你最早给它的约束条件。这不完全是模型能力问题更核心的原因是上下文窗口的资源分配。你每次把一套完整的工作流程、代码规范、输出格式塞进对话里这些内容就会和其他对话内容抢空间窗口一旦接近上限模型要么截断早期信息要么回复质量肉眼可见地下降。Skills 解决的就是这个矛盾。它把一套工作流程固化成文件放在 agent 能访问的固定位置。模型不会在每一轮对话里都背着这整本“操作手册”只有当它判断当前任务匹配某个技能的描述时才会去读取对应的 SKILL.md。换句话说手册不背在身上放在工位上需要的时候再翻。这个机制对 token 的节省是立竿见影的——尤其当你手上有十来个高频复用流程的时候。1.2 Skill 与 Prompt、MCP、Plugin 的本质区别很多初次接触 Skills 的人会把它和另外几个概念混在一起我最初也绕了一段时间。Prompt 是被动的。你把一大段提示词写进系统配置它就是静态文本无论当前任务是否相关它都占着上下文。Skill 是主动触发的它有一套基于描述信息的匹配机制任务不匹配就不加载。MCPModel Context Protocol解决的是“agent 如何实时访问外部数据和服务”的问题。比如连数据库、调内部接口、读文件系统这类需要鉴权和实时响应的操作MCP 是更合适的选择。Skill 解决的是“agent 如何按照既定的方法和步骤完成任务”的问题。它更像一份包含检查清单、步骤说明、示例输出和可选脚本的流程文件。两者可以配合使用Skill 定义流程流程中需要外部数据时再用 MCP 的工具去取。Plugin 通常指带有独立 UI、生命周期甚至独立运行时的扩展体系比如编辑器的插件、浏览器的扩展。Skill 更轻很多时候就是一个 Markdown 文件加若干辅助脚本没有 UI没有后台进程完全靠 agent 读取后执行。我自己的判断标准很简单如果这件事靠“讲清楚步骤”就能完成优先做成 Skill如果需要实时数据交换或外部系统联动才考虑 MCP如果要做成面向终端用户的独立产品功能那才上升到 Plugin 的范畴。1.3 第一性原理把“能力”打包成 agent 能自助读取的操作手册说到底Skills 的第一性原理是“文档即能力”。一个模型没有真正执行某个任务的能力之前你给它的支持本质上是一段高质量的过程性知识。Skills 的巧妙之处在于它把这段知识结构化并且让 agent 自己决定何时查阅它。这里要强调一点Skill 的价值高度依赖描述信息的质量。模型不是靠技能的名字来触发技能而是靠 description 里的语义信息来判断。你写“用于前端代码规范审查”模型遇到“帮我看看这段代码是否符合团队规范”时触发的概率会比写成“审查工具”高得多。这一点后面我会单独展开讲。2. 拆开一个 Skill 看内部结构SKILL.md 的正确打开方式2.1 最小可用的技能目录长什么样一个标准的 Agent Skill本质上就是一个目录里面必须有一个 SKILL.md 文件。以 Claude 的约定为例常见的布局是这样my-skill/ ├── SKILL.md └── scripts/ ├── check.sh └── report.pySKILL.md 是这个技能的主文档agent 会完整读取它。scripts 目录放辅助脚本SKILL.md 里可以指导模型在合适的时机调用它们。目录名一般用小写加连字符的风格因为目录名通常会作为技能的标识符使用。2.2 YAML frontmatter 的写法直接决定触发率SKILL.md 的开头有一段 YAML frontmatter格式如下--- name: frontend-code-review description: 当用户需要对前端项目代码进行规范审查、风格检查或提交前自检时使用。适用于 React/Vue 等现代前端工程。 --- # 前端代码规范审查 ## 任务说明 ...name 是技能的唯一标识description 是触发条件。我见过很多新手在这里犯同样的错误description 写得像产品宣传语比如“一个强大的代码审查工具”而不是明确说明“什么时候该用它”。模型是做语义匹配的不是做关键词匹配的你要把触发场景、适用对象、边界条件都写清楚它才能在正确的时机把技能翻出来。2.3 正文部分怎么组织才高效SKILL.md 的正文没有强制模板但根据我测试多版的经验高效的结构通常包含这几块任务目标用两三句话说明这个技能要达成什么结果。执行步骤按顺序列出步骤必要时给代码示例或命令。检查清单收尾前的核对项防止模型漏步骤。常见误区列出容易出错的地方让模型主动规避。正文长度没有硬性限制但我不建议写得过长。技能是给模型读的“方法论摘要”不是给你自己写的毕业论文。如果一个技能超过几百行大概率是你把它做成了百科全书这时候应该拆成多个更聚焦的技能。2.4 Claude Code 的加载路径与优先级在 Claude Code 中技能有两个默认的存放位置用户级全局目录~/.claude/skills/和项目级目录.claude/skills/。全局目录下装的技能对所有项目生效项目级目录下的技能只对当前项目生效。两个目录都存在同名技能时以项目级为准。这个设计很实用团队可以把项目特有的规范放进仓库的.claude/skills/跟着代码一起走个人通用技能则放在全局目录不必每个项目复制一份。注意每次新增或修改技能后建议重启当前会话或执行一次目录刷新命令否则 agent 可能拿不到最新的技能列表。这个问题我在第 6 部分会详细讲。3. 手把手开发一个“前端代码规范审查”技能从需求到测试3.1 为什么拿前端审查当例子热搜词里“前端开发 skills”热度很高我也确实认为这是最典型的 Skill 应用场景代码规范审查是规则明确的重复性工作流程固定、产出确定、不同项目之间差异小。这种“流程大于创造”的任务正是 Skill 最擅长的领域。想象一下团队里刚来了个新人你希望他提交代码前自己先做一轮自检。你会给他一份规范文档加一个检查清单。Skill 干的完全是同一件事只是把“你”换成了“agent”。3.2 需求拆解与 SKILL.md 初稿我建议把需求拆成三块输入、处理、输出。输入待审查的前端文件或整个目录。处理读取文件内容逐项核对团队规范规范项包括命名约定、目录结构、样式方案、TypeScript 类型使用、提交前清理项等。输出一份按严重程度分级的问题清单每条问题带文件定位和修改建议。基于这个拆分SKILL.md 的第一版可以这样写--- name: frontend-code-review description: 对前端项目代码进行规范审查。当用户要求检查代码是否符合团队规范、提交 PR 前自检、或对指定目录执行代码审查时使用。适用于 React、Vue 等现代前端技术栈。 --- # 前端代码规范审查 ## 执行步骤 1. 确定审查范围。如果用户没有指定默认审查当前工作目录下 src/ 目录。 2. 扫描目录结构对照项目约定确认目录组织是否合理。 3. 逐个读取源文件检查以下内容 - 组件命名是否使用 PascalCase - 变量和函数命名是否使用 camelCase - 是否存在未使用的导入 - 样式是否遵循项目的原子类约定 - TypeScript 中是否存在 any 滥用 4. 汇总问题按严重程度输出清单。 ## 输出格式 - [严重] 明确违反规范且可能导致运行问题 - [建议] 不影响运行但降低可维护性 - 每条问题包含文件路径、行号、问题描述和修改建议 ## 注意 - 只输出真实存在的问题不要臆造。 - 不确定的规范项标记为待确认不要直接断言。3.3 配套脚本让技能具备自动化能力纯 Markdown 的 Skill 只负责“讲步骤”但如果想让流程更自动化就可以加入辅助脚本。前端审查的例子中最值得自动化的是文件枚举和基础统计因为模型直接遍历目录容易遗漏隐藏目录或忽略被 gitignore 的文件。我用 Node 写了一个简单的文件收集脚本scripts/list-files.jsconst { execSync } require(child_process); const path require(path); const target process.argv[2] || src; try { const result execSync(find ${target} -type f \\( -name *.ts -o -name *.tsx -o -name *.js -o -name *.jsx -o -name .vue \\), { encoding: utf-8 }); const files result.trim().split(\n).filter(Boolean); console.log(files.join(\n)); } catch (e) { console.error(扫描目录失败请检查路径是否存在); process.exit(1); }然后在 SKILL.md 的执行步骤里把“扫描目录结构”改为“先运行node scripts/list-files.js [目标目录]获取文件清单再逐文件读取”。这样就形成了一个带工具链的技能而不是纯粹的“嘴炮指南”。3.4 Agent Skills 测试怎么确认它真的被调用技能写完最怕的事情是“看起来没问题但模型根本不用”。我的测试方法分三步第一步用命令列出当前会话可用的技能确认你的技能已经被加载。Claude Code 里可以直接用/skills相关命令查看或者直接问模型“你现在有哪些可用技能”。第二步用一段典型任务去触发它。比如“帮我对当前项目 src 目录做一次代码审查”。然后观察模型的思考过程里是否出现了“根据 frontend-code-review 技能”之类的表述。这一步能确认触发链路是通的。第三步测试边界情况。故意提出一个不匹配的问题比如“帮我写一首诗”看模型是否会被误触发。误触发说明 description 写得太宽泛需要收敛条件。根据我自己的经验第一次开发技能时大概率会卡在第二步。这不是你的技能有问题而是 description 的语义匹配需要迭代。你要像调广告关键词一样去调整措辞把用户“会怎么说”都覆盖到。4. 安装、更新与查找官方市场之外的野生态4.1 官方渠道一行命令安装和手动安装现在主流的 AI 编程工具大多支持直接从插件市场安装技能。以 Claude Code 为例你可以通过/plugin相关命令管理插件市场从官方市场里检索需要的能力包然后直接安装。官方市场的好处是经过一定审核质量和安全性相对有保障。手动安装也很简单把技能目录下载下来放进~/.claude/skills/或项目级.claude/skills/目录即可。我经常这么干因为很多社区技能只放在 GitHub 仓库里并没有上架官方市场。4.2 社区渠道GitHub 与第三方下载平台社区是目前技能最丰富的来源因为技能本质上是文本加脚本天然适合放在 Git 仓库里维护。GitHub 上可以搜到不少聚合类仓库有人维护了按场景分类的技能清单比如写作辅助、数据分析、论文润色、前端开发、自动化运维等方向。你可以在这些聚合仓库里看到每个技能的源码、README 和使用示例。还有一些第三方网站专门收录技能包按下载量或评分排序体验类似应用商店。不过这类网站良莠不齐要多留意维护时间和更新频率。除了通用技能包还有一类是“超级整合包”一个仓库里塞了几十个技能覆盖从日常办公到开发的完整场景。这类整合包很诱人但我建议按需抽取不要一整包全装进全局目录。技能装得越多模型在匹配时越容易出错反而不如精简。4.3 第三方技能的审计建议先看再装这里必须多说一句技能本质上是可执行指令的组合SKILL.md 里写的步骤会让模型去执行命令行操作。一个恶意技能完全可以诱导模型读取敏感文件、执行危险命令、把数据外传。所以从非官方渠道下载技能时我会先做三件事通读 SKILL.md检查里面让模型执行了哪些命令是否涉及删除、上传、网络请求。检查配套脚本留意有没有在后台向外部地址发起请求的代码。先在一个隔离目录或临时环境中运行一次观察它都做了什么。社区里有不少原创的优质技能但也有一些是从别的仓库改名搬运、甚至夹带了私货的“打包货”。你自己至少要能看懂下载的东西在做什么这是底线。下表是我常用的三种获取方式对比获取方式优点风险建议官方市场有审核质量稳定数量有限首选GitHub 聚合仓库数量多源码可见质量参差按需抽取注意维护时间第三方技能站检索方便有评分审核不明安装前完整审计5. Codex Skills 与 Claude Agent Skills同一套思路下的两种实现5.1 规范的相似与差异OpenAI 的 Codex 也支持技能机制而且从结构上看和 Anthropic 的 Agent Skills 非常相似同样使用 SKILL.md 作为主文件同样按目录组织同样通过描述信息触发。两个生态都在往“标准化技能包”的方向靠这对使用者来说是好事——写一份技能两边都能用。差异主要体现在触发和执行方式上。Claude 的技能触发更依赖对话语义匹配Codex 的技能加载机制则更倾向于在指定 Agent 能力范围中主动装载。实际体验上两者没有特别本质的区别都是“模型根据任务选择合适的技能读取技能文件后执行”。值得注意的是技能内脚本的运行环境。Claude Code 默认在执行命令前会请求确认Codex 则在权限配置上有所不同有的模式允许自动执行预设命令。这会影响你在技能里写脚本的方式尤其是命令执行那一环最好针对目标环境做好判断。5.2 各自适合什么场景从我的实际感受看Claude Agent Skills 更适合流程型、方法论型任务因为它的上下文注入方式对长步骤脚本的遵循度更好Codex Skills 则更适合开发任务中的规则复用尤其是你深度使用 Codex 的自动化工作流时。如果你两边都在用共享技能时要注意脚本的可移植性。尽量把脚本写成 Node 或 Python避免使用某个工具特有的 shell 命令。这样同一份技能目录拷到另一边改改路径就能跑。5.3 一个容易混淆的概念GitHub Skills 不是 Agent Skills搜索时你可能会看到大量“GitHub Skills”的内容误以为是 agent 技能。其实那是另一回事GitHub Skills 是 GitHub 官方的交互式学习课程用于教用户使用 GitHub 的功能比如 Actions、Copilot、代码安全等。它和 agent 的技能机制没有关系。还有一种叫“Nature Skills”的类型多指自然语言处理方向相关的技能包侧重点和这里讨论的 Agent Skills 也不同。搜索和下载的时候注意区分关键词避免装错东西。6. 实测中的高频坑技能没生效、装错目录、上下文被撑爆6.1 技能没被加载的完整排查链路这是我被问得最多的问题“技能放进去了但模型就是不认。”根据我踩过的坑排查顺序应该这样来第一确认目录层级。常见错误是直接把 SKILL.md 放进了.claude/skills/正确的是.claude/skills/skill-name/SKILL.md。中间那层技能目录不能省。第二确认文件名和扩展名。必须是 SKILL.md大小写通常不敏感但如果你的文件系统是敏感的建议严格按规范写。第三检查 YAML frontmatter 是否合法。常见的错误是 name 里面用了空格或特殊符号、description 没有闭合引号、冒号后面漏了空格。这些都会导致技能解析失败。第四确认是不是缓存问题。改动技能后没有重启会话导致模型拿到的还是旧列表。重启对话或重开项目再试一次。第五用命令验证技能是否在列表中。如果列表里没有你的技能基本可以确定是路径或解析问题回到前几步继续查。这套链路我整理成了自己的固定步骤每次排错不超过五分钟。6.2 description 写得不好导致“该用的时候不用”技能没有被加载和技能被加载但没被触发是两回事。后者几乎全是 description 的问题。我之前写过一个文档生成技能description 写的是“生成文档”。结果模型经常在用户随口说“写个说明”时触发它而在真正需要它处理复杂文档结构时反而没触发。后来我把 description 改成“当用户需要根据代码目录生成项目说明文档、API 文档或 README且文档需要包含模块结构、接口列表和贡献指南时使用”触发准确率立刻上来了。我总结的规律是description 里要写清楚“触发场景”和“任务边界”甚至可以把用户可能说的问法也列进去比如“适用于以下类型的请求生成项目文档、检查缺失的 README、导出 API 清单”。这样模型匹配起来就省力很多。6.3 技能内容太长把上下文窗口撑爆最后一个坑是我在给技能加了大量示例之后踩到的。示例越多SKILL.md 体积越大模型一旦加载它就要把整份文档读进上下文。如果你同时挂载了五六个大体积技能token 开销立刻上去模型反而变得迟钝。解决办法有两个。一是严格控制单个 SKILL.md 的体积把范例从正文里移出去放到单独的 examples 文件中只在正文里保留链接和摘要。二是把技能拆细一个技能只服务一个主要场景避免把多个相关流程塞进同一个技能。我个人的建议是单个 SKILL.md 控制在 150 到 300 行之间描述阶段给出足够信息执行阶段列出步骤和检查点示例只给关键危险边界的而非完整输出。6.4 关于权限与自动执行的提醒最后提一个容易被忽略的点。部分技能会指导模型直接执行脚本如果你的工作环境里关闭了命令确认机制技能中的脚本将以较高权限直接运行。这会带来安全风险。我处理这类问题时会为高敏感场景单独建一个技能目录并在 SKILL.md 开头明确写出“本技能的所有命令必须经过用户确认后执行”从流程层面兜底。我自己现在开发技能的流程已经固化下来了先写 SKILL.md再写脚本再反复打磨 description最后在隔离环境里跑一遍完整流程。每次从一个高频重复的痛点出发把做过的操作沉淀成一份结构化文档这比收藏几十个别人的技能有用得多。下次我打算把团队里的部署发布检查清单也做成一个技能让模型在每次发版前自动跑一轮预检。你也完全可以按这个思路从自己最常做的三件事开始。