做 AI 编程和 agent 应用这段时间，我最大的感受是：真正让一个模型从“能聊”变成“能干”的，往往不是更长的上下文，而是一组设计良好的 skills。Skills，准确叫法是 Agent Skills，就是给 Claude Code、Codex 这类智能体准备的“专业技能包”。它把某一类任务的工作流、约束、示例、脚本全部打包成一个文件夹，让 agent 在需要时按需加载。以前我们得把规则一遍遍写进 system prompt，写了一堆，模型还不一定执行到位；现在一个 skill 就能让行为稳定下来。

今天我想从第一性原理拆一遍 Agent Skills：它到底是什么、为什么值得做、怎么写、怎么引入项目、怎么调试，以及社区里那些 skills 下载平台和技能库到底该怎么用。这里不会只讲概念，还会给一份可以直接抄作业的 SKILL.md 模板，以及我在实际项目中踩过的坑。适合正在写 agent 应用的人、重度使用 Claude Code 或 Codex 的开发者，还有想给团队搭建统一技能库的技术负责人。

1. Skills 到底是什么：先看懂设计意图，再谈功能

1.1 从 Tools、Plugins 到 Skills 的演进

很多刚接触的人会把 Skills 和 Tools 混在一起，这是第一个认知误区。Tools 就是一个个函数，比如“搜索网页”“读取文件”“执行 Python 代码”，agent 在需要时直接调用，输入输出都很明确。Skills 则是一个复合体：它同时包含了指令文本、参考文档、脚本、模板和验收标准，本质上是“一段任务上下文 + 一组相关工具 + 约定流程”的整体封装。

打个比方，Tools 就像工具箱里的一把螺丝刀，而 Skills 是一本“更换轮胎操作手册”：不仅告诉模型哪把螺丝刀在哪儿，还告诉它先拆哪个螺丝、扭矩打多少、怎么检查安装是否正确。模型拿到一本手册之后，才知道每一步该用哪把工具、按什么顺序执行。

所以你在 GitHub 上看到的 skills 仓库，内部通常是这样一个结构：

my-skill/ ├── SKILL.md ├── scripts/ │ └── run_check.py ├── references/ │ └── best_practices.md └── assets/ └── template.html

SKILL.md 是入口文件，其余都是资源。这个设计的聪明之处在于：agent 平时只会看到 SKILL.md 里简短的描述，当它判断当前任务和这个 skill 匹配时，才真正把整个技能包加载进来。这个机制叫“渐进式披露”，是后面要反复讲到的关键。

1.2 为什么 Agent 需要 Skills：从 token 成本和行为一致性两个角度看

在没有 skills 的那些日子里，我们怎么让 agent 稳定完成一件事？最常见的做法是在 system prompt 里写一大段规则和工作流程。但是随着任务变多，prompt 越来越长，每次请求都要重复消耗大量 token，而且模型在某些步骤上总会“自由发挥”，今天一个做法，明天另一个做法。

Skills 把这个问题拆掉了。第一，它只按需加载，不占用常驻上下文，多个技能可以并存而不会互相干扰；第二，它把工作方法固化成文件，模型每次调用看到的是确定性文本，执行路径自然稳定；第三，它可以做到跨会话复用，这个项目里沉淀的技能，下一个项目直接拿来用。

我自己的体会是，一个真正好用的 skill 能把任务成功率从“看运气”提升到“基本稳定”。比如代码审查这个动作，以前让 Claude 审查代码，它一会儿关注风格，一会儿关注性能，输出很不统一。后来我写了一个 code-review skill，明确规定检查顺序、输出格式、严重级别标注规则，效果立刻稳定了。后面我会给出这个 skill 的完整内容。

1.3 拆解 Claude Agent Skills 的设计核心：渐进式披露

Claude Agent Skills 的设计文档里最核心的概念就是 progressive disclosure。它不是拍脑袋想出来的，而是基于一个实际问题：模型上下文窗口再大也有限，不可能把所有 skill 的内容一次性塞进去。

所以设计上做了两层。第一层，只有每个 skill 的 name 和 description 会出现在一个索引里，模型看到的是精简的“技能目录”；第二层，当模型判断当前任务命中某个 skill 时，再加载完整 SKILL.md 正文和相关资源文件。

这就带来一个非常实际的启发：description 写得好不好，直接决定 skill 会不会被正确触发。我在后面第 2 章会专门讲怎么写 description，这里先记住一个原则：描述要写明“什么时候用、输入是什么、输出什么”，而不是简单说“这是一个写论文的 skill”。

1.4 Codex Skills 与 Claude Skills 的生态差异

很多人同时用 Claude Code 和 Codex，也会问两边有什么不同。Claude 这边从 2025 年年初开始把 Agent Skills 作为正式功能推，目录约定是.claude/skills/，文件就是 SKILL.md。Codex 这边的生态更依赖 AGENTS.md 作为项目级指令文件，但社区也在把同样的 skills 模式迁移过去，很多开源仓库同时兼容两边。

我的建议是不要纠结于“哪个平台更正统”，而要把 skills 理解成一种“行为包”的通用模式。你在 Claude 里写好的 SKILL.md，只要做一些目录和 frontmatter 的调整，完全可以复用到其他支持自定义指令的 agent 工具上。先掌握方法和思路，工具差异只影响配置路径，不影响核心价值。

2. 手把手写一个能稳定触发的 Skill：以代码审查为例

2.1 目录放在哪里：全局目录与项目目录的选择

写 skill 之前先决定放哪。Claude Code 支持两个位置：一个是全局目录，通常叫~/.claude/skills/，所有项目通用；另一个是项目内目录.claude/skills/，只对这个仓库生效。

怎么选？我个人的习惯是：和工作流强相关的技能放项目内，比如“本项目的构建检查”“本项目的提交规范”；通用技能放全局，比如“代码审查”“写周报”“技术方案评审”。这样项目内技能能跟着仓库一起走，新人 clone 之后直接就能用，不用额外折腾环境。

Codex 那边类似，如果项目里有 AGENTS.md，可以在里面引用项目内 skills 目录，或者直接把工作流程片段写进 AGENTS.md。要注意的是，不要把 AGENTS.md 写得过长，否则又回到了“常驻 token 消耗”的问题，正确做法是让 AGENTS.md 保持精短，细节都放到 skill 里，按需加载。

2.2 创建目录结构和 SKILL.md 的 frontmatter

先建目录，名称使用 kebab-case，也就是小写加短横线，比如code-review。目录名就是 skill 的标识，同一个环境里不要和别的技能重名。然后创建 SKILL.md：

--- name: code-review description: 对前端/后端代码变更进行系统性审查。当用户要求审查代码、检查 PR、分析代码质量问题时使用。输入是一段代码或 diff，输出是按严重级别分类的问题清单和改进建议。 ---

frontmatter 只有两个字段：name 和 description。name 和目录名保持一致，description 就是之前提到的触发条件。这里我用了一个比较标准的写法：先一句话说明它是什么，再说明什么时候触发，最后说明输入输出。模型在索引阶段看到的就是这段描述，所以信息密度要高，但不要堆砌不相关的卖点词。

2.3 正文按“目标 + 步骤 + 验收标准”组织

正文是模型加载后会完整读到的部分。这里别用大段散文，要写成标准作业流程。我通常按三段来写：目标、执行步骤、验收标准与输出格式。

下面是我实际在用的一个简化版代码审查 skill 正文结构：

# 目标 对代码变更做结构化审查，发现功能性 bug、安全隐患、性能问题和可维护性问题，并输出可直接处理的问题清单。 # 执行步骤 1. 阅读 diff 或代码，先理解变更目的，不要一上来就挑格式问题。 2. 按以下优先级逐项检查： - 功能性：逻辑是否正确，边界条件是否覆盖 - 安全性：输入校验、注入风险、敏感信息泄露 - 性能：明显低效的循环、不合理的查询、重复计算 - 可维护性：命名、结构、重复代码 3. 对每个问题给出严重级别：Critical / Major / Minor。 4. 给出修改建议。建议要具体，直接给出示例代码或修复思路，不要只说“建议优化”。 # 验收标准 - 输出按严重级别分组的 Markdown 列表 - 每个问题包含：文件位置、问题描述、建议修复方案 - 不存在泛泛而谈的“代码质量有待提高”这类空话 - 如果代码没有明显问题，需要明确说“未发现明显问题”

你会发现这其实不是给模型看的“提示词”，更像给一个刚入职的初级工程师写的作业指导书。这正是 skill 的核心定位：它不增加模型的通用能力，而是把已知的好工作方法固化下来，让模型照着执行。

2.4 添加脚本、参考文档和模板：让技能具备执行能力

SKILL.md 只是文字指令，真正的落地能力靠 resources。scripts 目录放可执行脚本，references 放参考资料，assets 放模板文件。比如审查前端代码时，可以放一个scripts/check_secrets.py，扫描 diff 里的硬编码密钥；可以放一份references/frontend_rules.md，写明团队的前端规范。

调用方式很简单：在 SKILL.md 里写明“先用脚本扫描密钥，再按参考文档逐项对照”。模型读到指令后会自己去对应目录找文件执行。这个机制让 skill 不仅会“说”，还真正能“做”。

我当时给前端项目写审查技能时，就在 references 里放了一份很详细的团队规范，覆盖组件写法、API 调用方式、错误处理约定。效果非常明显：之前 Claude 按通用经验审查，经常建议一些不符合团队习惯的写法；之后它先读规范，再给建议，贴合度完全不一样了。

2.5 不要把 Skill 写成 AGENTS.md：职责边界要清晰

很多人会有疑问：既然 SKILL.md 能写指令，那和 AGENTS.md 有什么区别？区别在于加载时机和作用范围。

AGENTS.md 是每次对话都会加载的常驻指令，适合放全局性的项目约定，比如构建命令、目录结构、代码规范摘要。SKILL.md 是按需加载的技能包，只在任务匹配时激活，适合放完整的工作流程和详细操作手册。

如果把所有细节都塞进 AGENTS.md，就会遇到两个问题：一是每次请求都在消耗上下文 token，二是指令太长之后模型反而抓不住重点。把流程细节拆到 skill 里，AGENTS.md 只保留“什么时候用哪个 skill”这样的索引信息，才是正确用法。

3. 引入现成 Skills：从官方市场到开源社区

3.1 三种引入方式：文件复制、Git 仓库、自动安装工具

如果你不想从零写，社区里已经有很多现成的技能可以直接引入。引入方式大致有三种。

第一种是手动复制。从 GitHub 上 clone 或下载某个 skill 目录，放到自己的~/.claude/skills/或项目.claude/skills/下，重启会话就能生效。这种方式最原始，但最可控，因为你仔细看过内容之后才放进环境。

第二种是 Git 仓库直接引用。很多人的做法是把 skills 统一托管的仓库 clone 到本地，然后用软链接把需要的技能链接到 skills 目录。比如ln -s ~/my-skills-repo/code-review ~/.claude/skills/code-review，这样更新仓库时技能自动跟着更新，不用反复复制粘贴。

第三种是使用平台自带的安装入口。比如 Claude 生态里通过/plugin或 Marketplace 方式安装插件，也可以把某个 GitHub 地址作为插件源添加。具体命令不同版本有差异，我建议先查对应版本的 CLI 帮助，核心思路就是让 CLI 知道一个远程仓库地址，然后它自动把里的技能模块拉下来。

3.2 怎么判断一个仓库里的 Skills 是否靠谱

开源社区里技能质量差距极大，有的非常专业，有的就是把一句话提示词包了个壳。我评估一个 skill 是否可用，主要看四点。

第一，SKILL.md 是否真实存在且结构完整。如果一个“技能”只是长篇文章，没有 frontmatter、没有明确的执行步骤，那它可能只是普通的 prompt 收集，不是真正的 skill。

第二，执行步骤是否具体到可以复现。好技能里的步骤一定包含明确的判断条件和动作，比如“如果 errors 数组非空，先输出错误摘要再继续”，而不是“仔细分析代码并输出建议”这种空话。

第三，资源文件是否真的有用。有些仓库放了一堆脚本，但脚本内容质量很低，甚至只是打印一段文字。一个合格的脚本应该有明确的输入输出边界，比如接收 diff 路径、返回扫描结果。

第四，是否注明适用场景和限制。靠谱的技能作者会写明这个技能适用于什么项目、不适配什么情况。如果一个技能宣称“适用于所有项目”，反而要警惕。

我踩过一个比较典型的坑：从某个“awesome skills 合集”里下载了一个自称“自动生成单元测试”的技能，结果 SKILL.md 里就是一句“请为以下代码编写全面测试”。加载之后 Claude 的产出和直接问它没有任何区别，白白占用了目录位置。这类“伪技能”在社区里不少，看到的时候要会辨别。

3.3 值得关注的技能类型和典型场景

虽然不能一一枚举所有仓库，但几个被高频下载的类型可以重点介绍一下，方便你按需搜索。

第一类是代码理解与审查类。除了我上面写的 code-review，还有“解释这段代码”“生成 API 文档”“检测技术债”等。这类技能最适合团队统一代码评审标准，让每个成员得到同样深度的反馈。

第二类是写作与研究类。很多人用 agent 写论文、写博客、做行业研究，skill 可以把“文献检索 → 大纲生成 → 初稿 → 查证 → 改写”这个完整流程固化下来。热词里有 workbuddy skills 写论文、codex 写论文的 skills，本质上就是这个场景。我自己试过把论文写作流程拆成一个 skill：先让它检索相关主题、生成立场大纲、标注证据缺口、最后才写正文，质量和直接让它写完全不一样。

第三类是创意与内容生产类。比如分镜脚本、短视频脚本、品牌文案。这里 skill 的优势是可以把“角色设定、结构模板、表达风格、自检清单”全部打包，让产出保持稳定风格，而不是每次换一种文风。

第四类是效率工具类。比如“批量重命名文件”“整理会议纪要”“自动生成周报”。这些技能不用太复杂，但能把日常琐事变成一句指令直达结果，实测下来非常值。

3.4 把多个 Skills 组合成一条工作流

单个 skill 能解决一个环节的问题，真正的效率提升来自组合。我的做法是围绕一个完整交付目标，把任务拆成多个原子技能，然后串成链路。

举个例子，一个“从需求到代码交付”的标准链路可以是：先用requirement-analyzer把模糊需求拆成条目；再用tech-design-writer生成技术方案；然后code-generator按方案生成代码；最后code-review做质量把关。每个技能只负责一个环节，模型在步骤之间传递输出结果。

链路组合最怕的是技能之间职责重叠。我在早期把“技术方案生成”和“代码生成”写在同一个技能里，结果模型每次都会在方案环节就开始写代码，逻辑混乱。拆成两个独立技能之后，边界清晰了，整个流程也稳定了。这个教训是：技能设计要遵循单一职责原则，一个技能只解决一个问题。

4. 测试与调试：让 Skills 真正可靠起来

4.1 核心测试方法：制造一个最小触发场景

写完 skill 之后不是直接用，而是要先做一轮验证。最简单的测试方法是构造一个最小任务，主动触发这个技能。比如刚写完 code-review，就找一段真实 diff 让 Claude “审查这段代码”，观察它是否按技能里的步骤执行。

如果模型没有触发技能，或者触发了但没有按正文走，重点检查两个地方。一是描述里是否包含明确的触发信号：如果我把 description 写得过于狭窄，比如只写“前端项目代码审查”，那模型遇到“帮我看看这段后端代码逻辑有问题吗”就不会触发。二是正文步骤是否具备可操作性：描述触发模型只是第一步，真正决定执行质量的是正文里的步骤是否清晰、有无歧义。

还有一个很多人容易忽略的角度：技能在后台执行脚本时，要给脚本做独立测试。SKILL.md 里的逻辑可以通过对话验证，但 scripts 里的 Python 脚本如果有 bug，模型调用了只会得到错误结果。我一般会把脚本先单独跑一遍，确认入参出参符合预期，再让 skill 去调用它。

4.2 常见问题速查表：症状与解决方案

我用表格整理一下高频问题的排查思路，方便对照检查。

4.3 日志与可观测性：看到模型到底在干什么

调试技能时最怕的就是“黑盒”——你不知道模型有没有加载技能、有没有读 references、有没有执行脚本。不同客户端的观测手段不一样，但基本思路是让模型把“决策过程”显式化。

我自己的习惯是在 SKILL.md 正文开头加一句：“如果本技能被触发，请先简要说明识别到的任务类型与技能匹配原因。”这样模型一旦按技能执行，第一句话就会解释它为什么选择了这个路径。看起来多了一步动作，实际上对调试帮助巨大，它能直接告诉你触发是否准确、描述是否清晰。

在 Claude Code 里还可以用 verbose 模式观察 token 使用和工具调用情况，看某个 skill 是否在上下文中被加载。Codex 端也有类似日志。如果发现加载了但行为模式跟 skill 无关，那大概率是正文写得不够有约束力，要么步骤太笼统，要么缺少执行顺序和输出格式。

4.4 安全边界：来路不明的技能不要直接执行

这个必须单独强调。Skills 不仅包含文本，还包含可执行脚本。如果你从不知名的仓库下载技能并放到全局目录，等于让模型有了执行陌生代码的能力。这个问题在社区里已经被讨论了多次，我的原则很明确：只放经过审查的技能，尤其是 scripts 目录。

我在引入第三方 skill 时，一定会把 SKILL.md 从头到尾读一遍，把 scripts 里每一条命令都确认清楚。凡是包含 curl 远程下载并执行、删除文件、修改全局配置这类动作的，哪怕用途解释得再合理，我也不会直接放进去。真要测试新技能，就放到一个隔离的临时目录，用一个干净项目去跑，跑完没问题再转正。

另一个安全细节是不要把敏感信息写进 SKILL.md。比如有些团队把内部运维脚本密钥写在技能里，这样仓库一旦外泄，风险很大。技能内容要做到“不包含机密，只包含方法”，密钥和凭据走 agent 环境变量或密钥管理工具。

5. 经验心得：从“会写”到“写好”的几次跨越

5.1 写技能前先回答一个问题：这件事我会重复做三遍吗

技能不是越多越好，每多一个技能，模型在索引阶段就多一条描述要判断。我给自己定了一个标准：只有在“同样的任务我会重复做三遍以上”时才值得写成一个技能。一次性任务直接提示词解决，不值得额外维护。

按这个标准，我的全局 skills 数量一直控制在 15 个以内，每个都是高频、稳定、有明确输出的任务。数量少的另一个好处是维护成本低，description 的措辞调整、正文步骤迭代都更容易追踪。当你发现某个技能长期没有触发，应该删掉或者重构，而不是让它躺在目录里占位。

5.2 把技能分享出去的心得：仓库结构、文档和示例

如果你写了一个不错的技能想开源分享，结构上建议参考上面的目录模板，并额外加一个 README.md 和一个例子的 demo 目录。README 里写清楚适用场景、依赖环境和示例调用方式，demo 目录放一个输入样本和对应的预期输出样本。

社区里很多技能仓库的问题就是 README 好看但 SKILL.md 很薄。反过来的正确做法是：README 只当索引，核心内容放在 SKILL.md 和 references 里。这样用户用起来是加载 SKILL.md，不是看 README。另一个细节是许可证声明，开源 skills 涉及内容包分发，加上一个标准许可证能避免很多后续纠纷。

我在维护自己的技能仓库时，还会为每个 skill 写一个最小测试样例：比如test-cases/review-input.diff和test-cases/expected-output.md。这样后续修改 SKILL.md 时，可以快速回归验证描述和正文是否依然有效，避免改一个词导致触发行为全变。

5.3 从个人技能库到团队技能库：还需要配置和版本管理

个人用 skills 和管理层落地是两回事。团队场景下，除了技能本身，还需要解决三个问题：技能统一存放在哪、如何更新、如何保证质量校验。

我的建议是建立一个团队内部仓库，用 Git 管理所有技能，按项目或角色分目录。项目内的.claude/skills/只放软链接或者只放项目专属技能；通用技能都从内部仓库安装。更新机制上用定时拉取或发布流程，确保大家用的版本一致，不要出现“我本地改了没推上去”的情况。

技能的质量校验也应该有门槛。我见过不少团队把“模型生成的一段文字”直接当作技能入库，结果就是大家的 agent 都学会了跑偏。建议加一个简单的 review 流程：至少两人确认 SKILL.md 的结构完整、触发描述准确、执行步骤可复现，才允许合并到主分支。这个门槛听着不高，但能把团队技能库的整体质量兜住。

5.4 我现在的使用习惯：先定能力边界，再做技能沉淀

最后分享一个我现在的工作习惯。接到一个比较复杂的任务时，我不会立刻让 agent 直接干，而是先想清楚这个任务需要哪些能力边界，哪些部分是通用能力可以直接做，哪些部分是重复性工作值得沉淀成一个 skill。任务结束后，凡是过程中发现“这部分如果下次还能同样处理就好了”的环节，我就会把它从临时指令里抽出来，固化成技能。

这个习惯坚持一段时间后，积累下来的技能都是经过真实任务打磨的，不是拍脑袋设计的。回头看你写的第一个粗糙 skill，会明显感受到差距：好的技能并不是字数多，而是每一步都精准、约束有力、输出可复用。

我遇到过一次比较深刻的场景：给一个客户做项目交接，对方要求把代码审查和经验总结都沉淀下来。我直接把项目里的 code-review 技能和知识库结构导出成一个公开仓库，对方团队拿到后，只要配置好 skills 目录，每个新成员生成的代码审查意见就和老成员风格一致。那一刻我意识到，skills 本质上不是在教模型，而是在把团队的方法论编码成可执行协议。开发者会换，模型会更新，但只要这份协议还在，团队的作业标准就能延续下去。这也是我后来愿意花大量时间打磨技能的原因。