1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。你如果只看字面意思可能会以为是“技能”这种泛泛而谈的东西但实际在 Claude Code、Codex、各类 agents 生态里skills 已经变成了一个非常具体的工程概念。简单说skills 就是把一段可复用的能力封装成标准化的模块让 AI agent 在需要的时候能直接调用而不是每次都要重新写一遍提示词或者重新教它怎么做。我最早接触这个概念是在折腾 Claude Code 的时候。当时我有一堆重复性的任务比如每次都要让模型按照固定的格式生成 commit message、按照固定的规范审查代码、按照固定的模板生成 API 文档。一开始我的做法很笨就是把这一大段提示词存在一个文本文件里每次手动粘贴。后来发现这样效率太低而且容易漏掉细节。再后来我开始把这些提示词拆成独立的文件用目录结构管理起来这就是最原始的 skills 雏形。现在 skills 已经演变成了一套相对成熟的规范。在 Claude Code 里skills 通常是一个目录里面包含一个SKILL.md文件描述这个 skill 的名称、触发条件、执行逻辑还可以附带脚本、模板、参考文档。Codex 那边也有类似的概念虽然叫法可能不太一样但核心思路是一致的把能力模块化、可发现、可组合。你可以在项目里放一堆 skillsagent 在执行任务时会自动判断该调用哪个或者你也可以手动指定。为什么这件事值得单独拿出来讲因为 skills 解决了一个非常实际的痛点AI agent 的“最后一公里”问题。大模型本身很聪明但它不知道你项目的具体规范、不知道你们团队的代码风格、不知道你那个内部系统的 API 长什么样。你每次都要把这些上下文塞给它既费 token 又容易出错。skills 就是把这些“私有知识”和“固定流程”固化下来变成 agent 可以随时查阅的操作手册。适合谁来参考这篇内容如果你是刚接触 Claude Code 或者 Codex 的新手想搞清楚 skills 到底怎么用、怎么装、怎么自己写那这篇就是写给你的。如果你已经在用这些工具但还在靠复制粘贴提示词过日子那更应该看看因为 skills 能帮你省下大量重复劳动。如果你是在团队里负责推广 AI 编码工具的那 skills 的标准化管理思路对你会有直接帮助。2. skills 的核心设计思路为什么不是简单的提示词模板2.1 从“提示词工程”到“能力工程”的转变很多人第一次听说 skills 的时候会觉得这不就是提示词模板吗我一开始也这么想。但用了一段时间之后发现两者有本质区别。提示词模板是静态的你写好一段话每次原样发给模型。skills 是动态的它包含触发条件、执行逻辑、依赖资源甚至可以在执行过程中调用外部脚本。举个例子。假设你要让 agent 帮你做代码审查。如果用提示词模板你可能会写“请审查以下代码检查是否有安全问题、性能问题、风格问题。”然后每次把代码贴进去。但如果你把它做成一个 skill你可以定义得更细当用户提到“review”或者“审查”时触发这个 skillskill 内部先读取项目根目录下的.eslintrc和CONTRIBUTING.md了解项目的代码规范然后按照固定的检查清单逐项过一遍最后按照指定的格式输出报告包括问题等级、文件位置、修复建议。这个区别很关键。提示词模板只解决了“说什么”skills 解决了“怎么说、按什么顺序说、说之前要准备什么”。它更像是一个可执行的工作流而不是一段静态文本。2.2 skills 的目录结构与文件规范在实际操作中skills 通常以目录形式存在。以 Claude Code 为例你可以在项目的.claude/skills/目录下放多个 skill每个 skill 一个子目录。子目录里至少有一个SKILL.md文件这是入口。除此之外你还可以放脚本文件、模板文件、参考文档。SKILL.md的格式一般是 YAML frontmatter 加 Markdown 正文。frontmatter 里定义 skill 的名称、描述、触发关键词、允许使用的工具等元信息。正文部分就是具体的执行指令可以用自然语言写也可以嵌入代码块、表格、列表。我自己的习惯是每个 skill 目录下再分几个子目录scripts/放可执行脚本templates/放输出模板references/放参考文档。这样结构清晰agent 在需要的时候可以按路径去读取。比如一个生成 API 文档的 skill它的templates/里可以放一个 Markdown 模板agent 生成时直接套用保证格式统一。注意不同工具对 skills 的目录位置和文件命名要求可能不一样。Claude Code 默认读.claude/skills/Codex 那边可能是.codex/skills/或者通过配置文件指定。动手之前先确认你用的工具版本对应的规范别放错地方导致 skill 不生效。2.3 为什么选择 Markdown 加 YAML 的组合你可能会问为什么不用 JSON 或者纯代码来定义 skill我实际用下来Markdown 加 YAML 的组合有几个明显优势。第一可读性强。YAML frontmatter 负责结构化元数据Markdown 正文负责自然语言描述两者分工明确。你打开一个SKILL.md文件一眼就能看出这个 skill 是干什么的、什么时候触发、具体怎么做。如果换成 JSON嵌套几层之后可读性直线下降。第二模型友好。大模型对 Markdown 格式的理解能力很强标题层级、列表、代码块这些元素它都能准确解析。你用 Markdown 写执行指令模型更容易抓住重点。YAML 虽然模型也能读但不如 Markdown 那么自然。第三易于版本管理。Markdown 和 YAML 都是纯文本放在 Git 里 diff 很清晰。你改了哪条指令、加了哪个触发词一目了然。这对团队协作很重要因为 skills 往往需要多人维护和迭代。2.4 skills 与 agents、plugin 的关系热词里还出现了 agents 和 plugin这里顺便理一下它们的关系。Agent 是执行者skills 是能力包plugin 是扩展机制。一个 agent 可以加载多个 skills根据任务需要动态调用。Plugin 则更偏向于工具层面的扩展比如给 IDE 加一个插件来支持 Claude Code 的界面操作。你可以这样理解agent 是一个新员工skills 是员工手册和操作指南plugin 是给他配的办公软件。新员工很聪明但如果没有员工手册他不知道自己该按什么规范做事如果没有办公软件他很多活干不了。三者配合起来才能让 AI 编码助手真正融入你的工作流。在实际配置中你通常先安装好 Claude Code 或者 Codex 的插件比如 VS Code 扩展然后在项目里配置 skills最后 agent 在执行任务时会自动加载这些 skills。整个链路是打通的但每一环都需要正确配置。3. 实操从零开始搭建你的第一个 skill3.1 环境准备与工具安装在开始写 skill 之前你得先把基础环境搭好。这里以 Claude Code 为例Codex 的流程类似只是命令和路径略有不同。首先确认你的 Node.js 版本。Claude Code 对 Node 版本有要求建议用 18 以上。你可以用node -v检查如果版本太低用 nvm 或者直接去官网下载新版本。Windows 用户注意某些命令在 PowerShell 和 CMD 下的行为可能不一样建议统一用 PowerShell 或者 WSL。安装 Claude Code 的方式取决于你的使用场景。如果你是在终端里用可以通过 npm 全局安装如果你是在 VS Code 里用直接装扩展就行。安装完成后第一次运行需要登录按照提示走完授权流程。提示如果你在国内网络环境下遇到安装慢或者登录失败的问题可以尝试配置镜像源或者调整网络设置。具体方法这里不展开但核心思路是确保你的包管理器和工具能正常访问所需的资源。安装完成后你可以在项目根目录下创建一个.claude/skills/目录。如果这个目录不存在手动建一个。然后里面再建一个子目录比如code-review/这就是你的第一个 skill 的家。3.2 编写 SKILL.md从触发条件到执行逻辑现在开始写SKILL.md。我用一个实际的代码审查 skill 来演示。frontmatter 部分大概长这样--- name: code-review description: 对指定代码文件进行审查检查安全、性能、风格问题 trigger: 当用户提到审查、review、检查代码时触发 tools: - read_file - search_code ---name是 skill 的唯一标识建议用英文小写加连字符。description是一句话说明agent 在决定是否调用这个 skill 时会参考它。trigger定义触发条件可以是关键词也可以是更复杂的模式。tools列出这个 skill 需要使用的工具比如读文件、搜索代码等。正文部分就是具体的执行指令。我一般会分成几个小节检查清单、输出格式、注意事项。检查清单列出要检查的项比如“是否有硬编码的密钥”、“是否有未处理的异常”、“是否有性能瓶颈”。输出格式定义报告的结构比如用表格列出问题等级、文件、行号、描述、建议。注意事项写一些边界情况比如“如果文件超过 500 行分段审查”。写这部分的时候指令要具体不要含糊。不要说“检查代码质量”而要说“检查函数是否超过 50 行、是否有重复代码块、变量命名是否符合 camelCase 规范”。模型需要明确的判断标准越具体越容易执行到位。3.3 添加辅助资源脚本、模板与参考文档一个成熟的 skill 往往需要辅助资源。还是以代码审查为例我可以在 skill 目录下放一个templates/report.md定义报告的 Markdown 模板。agent 生成报告时直接套用保证每次输出格式一致。如果审查逻辑比较复杂我还可以写一个 Python 脚本放在scripts/目录下比如用 AST 解析代码结构提取函数列表和复杂度指标。然后在SKILL.md里指示 agent 先运行这个脚本再根据脚本输出做进一步分析。参考文档也很重要。比如你们团队有一份内部的代码规范文档可以把它放在references/目录下在SKILL.md里让 agent 先读取这份文档再开始审查。这样审查结果就会贴合你们团队的实际规范而不是泛泛而谈。实操心得辅助资源不要贪多。我见过有人把一个 skill 目录塞了几十个文件结果 agent 加载时反而不知道该看哪个。建议每个 skill 的辅助文件控制在 5 个以内每个文件都有明确的用途并且在SKILL.md里写清楚什么时候读哪个文件。3.4 测试与调试让 skill 真正跑起来写完 skill 之后别急着高兴先测试。测试的方法很简单在 Claude Code 里输入一个会触发这个 skill 的请求比如“帮我审查一下 src/utils.js 这个文件”然后观察 agent 的行为。如果 skill 没有被触发先检查目录位置对不对、SKILL.md的 frontmatter 格式有没有问题、触发关键词是否匹配。如果 skill 被触发了但执行结果不对就去看 agent 的中间输出看它读了哪些文件、执行了哪些步骤在哪一步偏离了预期。调试的时候我习惯在SKILL.md里临时加一些console.log式的指令比如“在开始审查前先输出‘正在加载代码审查 skill’”。这样能快速确认 skill 是否被加载。确认没问题后再把这些调试指令删掉。还有一个常见问题是 skill 之间的冲突。如果你装了多个 skill它们的触发条件可能有重叠导致 agent 不知道该用哪个。解决办法是在description和trigger里写得更精确或者用优先级标记来区分。4. 进阶玩法让 skills 组合出真正的生产力4.1 多 skill 协作串联与并联单个 skill 能解决的问题有限真正厉害的是多个 skill 组合使用。我举一个实际的例子我有一套 skill 组合用来处理“从需求到代码”的完整流程。第一个 skill 叫requirement-analysis负责把模糊的需求描述拆解成具体的功能点和技术任务。第二个 skill 叫code-generation根据任务列表生成代码骨架。第三个 skill 叫code-review对生成的代码进行审查。第四个 skill 叫test-generation根据代码生成单元测试。这四个 skill 可以串联使用你先触发第一个得到任务列表然后把任务列表传给第二个得到代码再触发第三个审查代码最后触发第四个生成测试。整个过程你只需要在关键节点做决策大部分重复劳动都由 skill 完成。并联使用也很常见。比如你同时有security-check和performance-check两个 skill可以在审查代码时同时触发让 agent 从两个维度分别检查最后合并报告。4.2 动态参数与条件分支高级一点的 skill 会用到动态参数。比如一个部署 skill可能需要根据环境不同执行不同的命令。你可以在SKILL.md里定义参数占位符让 agent 在调用时填入实际值。条件分支也很实用。比如“如果检测到项目使用 TypeScript则执行类型检查否则跳过”。这种逻辑用自然语言写在SKILL.md里模型基本都能正确执行。关键是条件要写得明确不要让模型去猜。我自己的经验是条件分支不要超过三层。超过三层之后模型出错的概率明显上升。如果逻辑真的很复杂不如拆成多个 skill用组合的方式来实现。4.3 团队协作中的 skills 管理如果你在团队里推广 skills管理就成了一个大问题。我的建议是把 skills 当作代码来管理。放在 Git 仓库里有版本号有变更记录有 review 流程。可以建一个专门的skills仓库每个 skill 一个目录用 README 说明用途和用法。团队成员可以提交 PR 来新增或修改 skill经过 review 后合并。这样既能保证质量又能让知识沉淀下来。另外建议给 skills 打标签比如frontend、backend、testing、deployment。这样在项目里配置时可以按需加载不用把所有 skill 都塞进去。加载太多 skill 会拖慢 agent 的响应速度也会增加误触发的概率。注意团队共享的 skill 里不要放敏感信息比如内部 API 密钥、数据库连接串。这些应该通过环境变量或者配置文件注入而不是硬编码在SKILL.md里。5. 常见问题与排查技巧实录5.1 skill 不生效的几种典型情况这是最常见的问题。你写好了 skill但 agent 好像完全不知道它的存在。根据我的排查经验原因通常有这几类问题现象可能原因排查方法skill 完全不被触发目录位置不对确认.claude/skills/在项目根目录下skill 偶尔触发偶尔不触发触发关键词太模糊把 trigger 写得更具体增加同义词skill 触发但执行结果不对指令描述有歧义检查SKILL.md正文把模糊表述改具体skill 加载报错frontmatter 格式错误用 YAML 校验工具检查格式多个 skill 冲突触发条件重叠调整 description 和 trigger区分优先级我踩过最坑的一次是目录名写错了把skills写成了skill结果折腾了半天才发现。所以第一步永远是确认路径。5.2 模型不按 skill 指令执行的应对策略有时候 skill 被正确加载了但模型没有严格按照指令执行。比如你让它输出表格它输出了列表你让它先读配置文件它直接开始分析代码。这种情况通常是因为指令不够强硬。模型在多个任务之间会做权衡如果你的指令语气比较弱它可能会“偷懒”。解决办法是在SKILL.md里用更明确的措辞比如“必须”、“严格按照以下格式”、“在执行任何分析之前必须先读取配置文件”。另一个技巧是把关键步骤拆成编号列表让模型按顺序执行。模型对有序列表的遵循度比无序列表高。如果还是不行可以在 skill 里加一个自检步骤让模型在输出前先确认自己是否完成了所有要求。5.3 性能优化减少 skill 加载时间skill 多了之后加载时间会变长。我实测下来如果一个项目里放了 20 个以上的 skillagent 的首次响应时间会明显增加。优化方法有几个第一按需加载。不是所有 skill 都需要一直可用可以把不常用的 skill 放在单独的目录里需要时再手动启用。第二精简SKILL.md内容。把详细的参考文档放到references/里正文只保留核心指令。第三合并相似 skill。如果两个 skill 的触发条件和执行逻辑很接近考虑合并成一个。实操心得我一般会把最常用的 5 到 8 个 skill 放在主目录其他的按项目类型分组存放。切换项目时只加载当前项目需要的 skill 组。这样既保证了响应速度又不会丢失能力。5.4 跨工具兼容性Claude Code 与 Codex 的差异如果你同时用 Claude Code 和 Codex会发现它们的 skill 规范不完全一样。Claude Code 的SKILL.md格式相对固定Codex 那边可能更灵活一些但也有一些自己的约定。我的做法是尽量把 skill 的核心逻辑写成工具无关的形式然后用一个小的适配层来处理差异。比如核心指令用 Markdown 写触发条件和工具配置分别放在不同的 frontmatter 里。这样迁移的时候只需要改配置部分不用重写整个 skill。不过说实话完全兼容很难做到。我的建议是先在一个工具上把 skill 跑通再考虑迁移。不要一开始就追求跨工具通用那样会陷入过度设计的陷阱。6. 我个人的一些经验和建议用了大半年 skills 之后我最大的体会是不要为了用而用。skills 确实能提升效率但前提是你真的有重复性的任务需要封装。如果你只是偶尔用一次某个功能写个提示词就够了没必要专门做个 skill。另外skills 的维护成本不低。你写了一个 skill过两个月项目规范变了你得记得去更新它。如果忘了更新agent 就会按照过时的规范执行反而添乱。所以我现在只把那些稳定的、高频的、有明确规范的任务做成 skill其他的还是用临时提示词解决。还有一个建议是从最简单的 skill 开始。不要一上来就搞复杂的多 skill 协作先写一个单文件的SKILL.md跑通了再逐步加辅助资源。我见过有人一开始就设计了一套十几个 skill 的体系结果调试成本太高最后不了了之。最后分享一个小技巧你可以把 skill 的description写得稍微“主动”一点。比如不要写“用于代码审查”而写“当用户需要审查代码质量、安全检查、性能分析时使用”。这样模型在判断是否触发时会更积极减少漏触发的情况。当然也别太夸张否则会频繁误触发那就适得其反了。