1. 从“skills”这个热词说起它到底是什么为什么突然火了最近半年不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到可能会以为它又是哪个新出的前端框架或者构建工具。但真正用过 Claude Code 或者关注 Agent 生态的人会知道这里说的 skills 跟传统意义上的“技能”完全不是一回事。简单来说Agent Skills 是一套让 AI 编程助手具备“可复用专业能力”的机制。你可以把它理解成给 AI 装插件——每个 skill 就是一个独立的能力包里面包含了特定领域的知识、操作流程、工具调用规则和输出规范。当 AI 遇到对应场景时会自动加载这个 skill按照预定义的逻辑去完成任务。这个概念的载体是一个叫SKILL.md的文件。对就是一个 Markdown 文件。听起来简单得有点过分但正是这种“低门槛定义能力”的设计让 skills 生态在短时间内爆发了。你不需要写复杂的代码不需要理解模型底层只要能用自然语言把一件事的流程说清楚就能做出一个可用的 skill。那为什么是现在火我的判断是三个因素叠加第一Claude Code 这类 CLI 工具的普及让 AI 编程从“聊天窗口”走进了真实的项目目录有了文件系统操作能力第二SKILL.md这种约定优于配置的设计把开发门槛降到了几乎为零第三社区发现 skills 可以解决一个长期痛点——让 AI 在不同项目中保持一致的做事方式。举个例子。你团队里每个人用 AI 写代码的习惯不一样有人让它先写测试有人直接让它改代码有人要求必须加注释。结果就是 AI 的输出质量忽高忽低。但如果你把“代码审查”做成一个 skill里面写清楚检查项、输出格式、严重等级划分那不管谁调用AI 都会按照同一套标准来执行。这就是 skills 最核心的价值把个人经验固化成可复用的组织能力。适合谁来了解这个内容我觉得三类人最应该关注一是日常用 Claude Code 或类似工具写代码的开发者skills 能显著提升你的输出稳定性二是技术团队负责人你可以用 skills 来统一团队的 AI 使用规范三是对 AI Agent 开发感兴趣的人skills 是目前门槛最低的 Agent 能力扩展方式没有之一。2. 拆解 SKILL.md一个文件如何定义一项能力2.1 SKILL.md 的基本结构长什么样很多人第一次看到SKILL.md会觉得“就这”——因为它确实就是一个 Markdown 文件没有复杂的 schema没有必须遵循的 JSON 结构。但正是这种极简设计让它具备了极强的表达力。一个典型的SKILL.md包含几个核心部分。最上面是元信息通常用 YAML frontmatter 来写包括 skill 的名称、描述、触发条件、版本号这些。下面就是正文用自然语言描述这个 skill 要做什么、怎么做、有哪些注意事项。我拿一个实际场景来举例。假设你要做一个“API 接口设计审查”的 skill文件大概长这样--- name: api-design-review description: 审查 RESTful API 设计是否符合团队规范 trigger: 当用户要求审查 API 设计或创建新接口时 version: 1.0.0 --- # API 设计审查 ## 审查维度 1. URL 命名规范 - 使用小写字母和连字符 - 资源名用复数形式 - 避免动词出现在 URL 中 2. HTTP 方法使用 - GET 用于查询不产生副作用 - POST 用于创建 - PUT 用于全量更新 - PATCH 用于部分更新 - DELETE 用于删除 3. 状态码规范 - 200 成功 - 201 创建成功 - 400 客户端参数错误 - 401 未认证 - 403 无权限 - 404 资源不存在 - 500 服务端错误 ## 输出格式 对每个审查维度给出 - 通过/不通过 - 具体问题描述 - 修改建议你看没有任何代码全是自然语言。但 AI 读到这个文件后就能按照你定义的维度去审查 API 设计了。这就是 skills 的魔力——用文档的方式编程。2.2 触发机制AI 怎么知道该用哪个 skill这是很多人困惑的地方。我写了十个 skillAI 怎么知道当前该调用哪一个答案在description和trigger字段里。Claude Code 在启动时会扫描 skills 目录读取每个SKILL.md的元信息。当你发出一个请求时它会根据语义匹配来判断是否需要加载某个 skill。这里有个实操心得trigger 描述要写得具体但不要过于狭窄。我见过有人把 trigger 写成“当用户输入‘审查API’时触发”结果用户说“帮我看看这个接口设计有没有问题”就匹配不上了。更好的写法是描述场景而不是具体指令比如“当用户要求审查、检查或优化 API 设计时”。另外skill 的description也很关键。它不仅是给 AI 看的也是给你自己看的。当 skill 多了以后你不可能记住每个文件里写了什么这时候一个清晰的 description 就是你的索引。2.3 为什么用 Markdown 而不是代码这个问题我被问过很多次。用 Markdown 定义能力听起来不够“工程化”但恰恰是这种选择让 skills 生态能快速起量。原因有三层。第一Markdown 是 AI 的原生语言。大模型对 Markdown 结构的理解能力极强标题层级、列表、代码块这些元素模型都能准确解析。你用 JSON 写一堆配置模型反而需要额外推理。第二修改成本极低。你发现 skill 输出不对直接打开文件改一句话就行不需要重新编译、不需要跑测试、不需要发版。这种即时反馈循环让 skill 的迭代速度非常快。第三非技术人员也能参与。产品经理可以写一个“需求文档审查”的 skill运营可以写一个“活动文案生成”的 skill。他们不需要懂编程只要能把流程说清楚。这大大扩展了 skills 的适用边界。注意虽然 Markdown 很灵活但不要把它当成随意书写的笔记。skill 文件的结构越清晰AI 的执行效果越稳定。建议每个 skill 都遵循“元信息-目标-流程-输出格式-注意事项”这个基本框架。3. 从零手搓一个 skill完整实操流程3.1 环境准备与目录结构在开始写 skill 之前你需要先确认自己的环境。目前 skills 主要跟 Claude Code 配合使用所以第一步是确保 Claude Code 能正常运行。Claude Code 的安装方式根据操作系统不同有所差异。macOS 和 Linux 用户通常通过包管理器安装Windows 用户则需要先确认系统版本是否支持。安装完成后你可以在终端里输入claude来验证是否成功。如果提示“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没配好需要手动把安装路径加到 PATH 里。skills 的存放位置有约定俗成的规则。通常是在项目根目录下创建一个.claude/skills/文件夹每个 skill 一个子目录目录名就是 skill 的名称。比如项目根目录/ ├── .claude/ │ └── skills/ │ ├── api-design-review/ │ │ └── SKILL.md │ ├── code-review/ │ │ └── SKILL.md │ └── test-generator/ │ └── SKILL.md这种结构的好处是 skill 跟着项目走。你 clone 一个仓库里面的 skills 自动就位团队成员不需要额外配置。当然你也可以把通用 skill 放在用户级别的目录里这样所有项目都能用。3.2 写第一个 skill从需求到文件我拿一个真实需求来演示。假设你经常需要把一段中文技术文档翻译成英文但你不希望 AI 自由发挥而是要求它遵循特定的术语表和风格指南。这个需求就可以做成一个 skill。第一步明确 skill 的边界。它只做翻译不做润色不做摘要不做格式转换。边界越清晰AI 执行越准确。第二步写元信息。name 用英文小写加连字符description 用一句话说清楚这个 skill 干什么trigger 描述什么时候该触发。第三步写正文。正文要包含翻译原则、术语表、输出格式、示例。--- name: tech-doc-translator description: 将中文技术文档翻译为英文遵循指定术语表和风格指南 trigger: 当用户要求翻译中文技术文档、API 文档或注释时 version: 1.0.0 --- # 技术文档翻译 ## 翻译原则 - 保持技术准确性优先于语言流畅性 - 代码标识符、函数名、变量名不翻译 - 专有名词首次出现时保留中文原文括号内附英文翻译 - 被动语态使用频率控制在 30% 以下 ## 术语表 | 中文 | 英文 | |------|------| | 接口 | API | | 参数 | parameter | | 返回值 | return value | | 异常 | exception | | 并发 | concurrency | | 序列化 | serialization | ## 输出格式 直接输出翻译后的英文文本不添加任何解释性内容。 如果遇到术语表中没有的专有名词在翻译后用括号标注原文。写完这个文件保存到.claude/skills/tech-doc-translator/SKILL.md。然后在 Claude Code 里说“帮我把这段中文文档翻译成英文”它就会自动加载这个 skill 并按照你定义的规则执行。3.3 调试与迭代怎么知道 skill 生效了skill 写完不是终点调试才是关键。我自己的习惯是每写完一个 skill立刻用三个不同类型的输入去测试一个标准场景、一个边界场景、一个异常场景。标准场景就是最典型的用法看输出是否符合预期。边界场景是那些模棱两可的输入看 AI 会不会错误触发或漏触发。异常场景是故意给一些不相关的输入看 skill 会不会被误加载。如果发现 skill 没生效排查顺序是这样的先确认文件路径对不对再确认 frontmatter 格式有没有问题然后看 trigger 描述是否匹配当前请求。我踩过的一个坑是YAML frontmatter 里的冒号后面必须加空格否则解析会出错。这种细节在文档里往往不会写但实际用的时候一踩一个准。实操心得skill 的迭代不要追求一步到位。先写一个能用的版本然后在实际使用中不断调整。我自己的习惯是每次发现输出不对就立刻打开 SKILL.md 加一条规则或改一句描述。一个成熟的 skill 通常要经过十几轮迭代才能稳定。4. 进阶玩法让 skills 组合出超级能力4.1 skill 之间的调用与协作单个 skill 能解决一个问题但真实工作流往往需要多个能力配合。比如你要完成一个“从需求到代码”的完整流程可能需要需求分析 skill、接口设计 skill、代码生成 skill、测试生成 skill、代码审查 skill。Claude Code 支持在一个会话中加载多个 skill。当你的请求涉及多个领域时它会尝试匹配所有相关的 skill。但这里有个问题如果两个 skill 的 trigger 描述有重叠可能会导致冲突。解决方法是在 skill 里显式声明依赖关系。你可以在 SKILL.md 里加一个dependencies字段列出这个 skill 需要哪些其他 skill 配合。这样 AI 在加载时就会知道要一起加载哪些文件。另一种做法是用主 skill 编排子 skill。比如你做一个“全栈开发”的 skill里面写清楚流程先调用需求分析再调用接口设计然后调用代码生成。每个步骤的输出作为下一步的输入。这种编排方式适合流程固定的场景。4.2 用 skills 统一团队规范这是我认为 skills 最有价值的使用场景。团队里每个人对 AI 的使用方式不同导致输出质量参差不齐。但如果你把团队规范写成 skills情况就完全不一样了。具体做法是在项目仓库里建一个.claude/skills/目录把代码规范、审查标准、提交信息格式、文档模板这些都做成 skill。新成员 clone 仓库后不需要额外培训AI 会自动按照团队标准来辅助他工作。我见过一个团队做得更极致他们把 code review 的 checklist 做成了一个 skill每次提交 PR 前开发者先让 AI 跑一遍这个 skill把明显的问题修掉再提交。结果 code review 的效率提升了将近一倍因为 reviewer 不再需要指出那些低级问题。这里的关键是规范要可执行。你不能只写“代码要清晰”而要写“函数长度不超过 50 行嵌套层级不超过 3 层每个公共方法必须有 JSDoc 注释”。越具体的规则AI 执行起来越准确。4.3 跨工具使用skills 的通用性虽然 skills 最早是跟 Claude Code 绑定的但它的设计理念是通用的。SKILL.md本质上是一个结构化的能力描述文件任何支持读取本地文件的 AI 工具都可以解析它。目前已经有一些其他工具开始支持类似的机制。比如某些开源 AI 编程助手允许你指定自定义的指令文件格式跟 SKILL.md 非常接近。这意味着你写的 skill 不是锁定在某个平台上的而是可以迁移的。我的建议是把 skill 当成团队资产来管理。用 Git 来版本控制写清楚每个 skill 的变更记录定期 review 和更新。这样即使将来换工具你的能力积累也不会丢失。5. 常见问题与排查技巧实录5.1 skill 不生效的排查清单这是最高频的问题。我整理了一个排查顺序按这个顺序走90% 的问题都能定位。排查项检查方法常见问题文件路径确认 SKILL.md 在.claude/skills/下放错目录比如放到了项目根目录文件命名必须是SKILL.md大小写敏感写成了skill.md或Skill.mdfrontmatter检查 YAML 格式冒号后要有空格name:xxx缺少空格导致解析失败trigger 描述看是否匹配当前请求的语义描述太窄用户换个说法就匹配不上文件编码确认是 UTF-8中文乱码导致 AI 读不懂权限问题确认文件可读在某些系统上权限设置过严我遇到最多的情况是 frontmatter 格式错误。YAML 对缩进和空格非常敏感一个 tab 和一个空格的混用就可能导致整个文件解析失败。建议用支持 YAML 语法高亮的编辑器来写能提前发现大部分格式问题。5.2 skill 输出不稳定的原因有时候 skill 能触发但输出质量忽好忽坏。这通常不是 skill 本身的问题而是指令不够明确。AI 对模糊指令的容忍度很低。你写“输出要简洁”AI 不知道简洁的标准是什么。但如果你写“输出不超过 200 字用 bullet point 列出每个点不超过 20 字”输出就会稳定很多。另一个原因是上下文干扰。如果当前会话里已经有很多其他内容AI 可能会被带偏。解决方法是在 skill 里加一句“忽略之前的所有指令严格按照本 skill 的规则执行”。这句话看起来有点粗暴但实测下来很有效。还有一个容易被忽略的点skill 的加载顺序。如果多个 skill 同时被触发后加载的可能会覆盖先加载的规则。这时候需要在 skill 里明确优先级或者在 trigger 描述里做好区分。5.3 性能与 token 消耗的平衡skill 文件本身会占用 token。一个写得非常详细的 skill 可能有几千字每次加载都会消耗上下文窗口。如果你的 skill 库很大可能会影响 AI 的响应速度。我的做法是分层设计。核心规则放在主 skill 里详细说明放在子文件里用引用链接的方式关联。这样主 skill 保持精简需要时再加载详细内容。另外定期清理不再使用的 skill 也很重要。我每季度会 review 一次 skill 库把过时的、重复的、效果不好的删掉。保持 skill 库的精简比堆砌大量低质量 skill 更有价值。注意不要为了省 token 而把 skill 写得太简略。一个模糊的 skill 导致的错误输出修复成本远高于多消耗的那点 token。在清晰度和精简之间优先保证清晰度。6. 我个人的 skill 库管理与使用体会聊了这么多技术细节最后说点实在的。我用 skills 大概有半年时间目前维护着二十多个 skill覆盖代码审查、文档生成、测试编写、API 设计、数据库迁移这几个领域。踩过的坑不少但整体收益远大于投入。最大的体会是skill 的质量取决于你对这件事的理解深度。如果你自己都说不清楚一个任务的流程和标准写出来的 skill 也不会好用。所以写 skill 的过程其实也是梳理自己工作方法的过程。另一个体会是不要追求大而全。我一开始想做一个“万能代码助手”的 skill把所有规范都塞进去结果效果很差。后来拆成十几个小 skill每个只解决一个具体问题反而稳定得多。这跟写代码是一个道理单一职责原则在 skill 设计上同样适用。还有一点skill 需要持续维护。技术栈在变团队规范在变skill 也要跟着变。我现在的习惯是每次发现 AI 输出不符合预期就立刻打开对应的 SKILL.md 加一条规则。这种即时反馈的迭代方式比定期大规模更新有效得多。如果你刚开始接触 skills我的建议是从一个最小的场景开始。不要一上来就搞复杂的编排和依赖先写一个简单的、你每天都会用到的 skill比如“生成 commit message”或者“格式化 JSON”。用顺了之后再逐步扩展。这个学习曲线很平缓但积累效应非常明显。