1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是各种开发者群聊里skills这个词出现的频率高得离谱。很多人第一次看到它的时候会一脸懵——这玩意儿到底是插件是脚本还是某种新的包管理机制其实把它拆开来看就很好理解了skills 本质上是一套写给 AI 编码助手看的操作说明书它用结构化的 Markdown 文件通常叫SKILL.md告诉 AI 在特定场景下应该怎么做、按什么顺序做、注意哪些坑。你可以把它想象成给一个新来的实习生准备的岗位手册。这个实习生很聪明学习能力极强但他不知道你们团队内部的约定——比如提交代码前必须跑哪几个检查、某个目录下的文件不能随便动、生成某个类型的代码时要遵循什么命名规范。skills 就是把这些隐性知识显性化写成 AI 能读懂的文档让它在干活的时候自动加载。为什么这个东西突然火了核心原因在于通用大模型的能力已经足够强但通用恰恰是它的短板。一个模型可能什么都懂一点但在你的具体项目里它不知道你的技术栈偏好、不知道你的目录结构约定、不知道你踩过哪些坑。skills 就是用来填补这个最后一公里的。它不改变模型本身而是通过上下文注入的方式让模型在特定任务上表现得像一个熟悉你项目的老手。从热词里能看出来大家关心的方向非常集中怎么安装、怎么写、怎么管理、有哪些好用的现成 skills 可以拿来就用。数学建模、前端开发、AI 漫剧、嵌入式比如 STM32这些领域都有人在整理自己的 skills 库。这说明 skills 不是一个纯技术概念而是一种跨领域的知识封装方式——任何有固定流程、有经验积累的工作都可以被写成 skill。这篇文章我会从零开始把 skills 的来龙去脉、文件结构、编写方法、安装管理、实战技巧全部讲清楚。不管你是刚听说这个词的新手还是已经用过几个现成 skills 想自己动手写的老手都能从这里找到能直接用的东西。2. SKILL.md 的文件结构一个 skill 到底由什么组成2.1 最小可用结构三个部分缺一不可一个能跑的 skill最核心的就是一个SKILL.md文件。别看它只是个 Markdown里面的结构是有讲究的。我见过太多人上来就写一大段自然语言描述结果 AI 读完之后该干嘛还是干嘛完全没起作用。问题就出在结构上。一个合格的SKILL.md通常包含三个部分元信息头frontmatter用 YAML 格式写在文件最顶部用---包裹。这里定义 skill 的名称、描述、触发条件等。这是 AI 判断什么时候该用这个 skill的依据。正文说明用自然语言描述这个 skill 的目标、适用场景、前置条件。这部分是给 AI 建立整体认知的。操作步骤具体的执行流程通常用有序列表或者分节的代码块来写。这是 skill 的干货部分。我拿一个实际例子来说明。假设你要写一个生成 React 组件的 skill元信息头大概长这样--- name: react-component-generator description: 当用户要求创建新的 React 函数式组件时使用此 skill确保组件遵循项目的目录结构和命名规范 version: 1.0.0 tags: - frontend - react - codegen ---这里有个细节很多人会忽略description 字段的写法直接决定了 skill 能不能被正确触发。如果你写得太笼统比如用于前端开发那 AI 几乎不会主动调用它因为太宽泛了。正确的做法是把触发场景写具体——当用户要求创建新的 React 函数式组件时这样 AI 在遇到类似请求时才能精准匹配。2.2 正文部分把隐性知识翻译成可执行指令元信息头之后就是正文。这部分最容易犯的错误是写成介绍性文档而不是操作指令。区别在哪介绍性文档会说React 组件应该遵循良好的命名规范而操作指令会说组件文件名使用 PascalCase例如UserProfile.tsx组件内部导出的函数名与文件名保持一致。后者才是 AI 能直接执行的东西。我总结了一个原则每一条指令都应该是可验证的。也就是说AI 执行完之后你能明确判断它做对了还是做错了。模糊的描述只会让 AI 自由发挥而自由发挥的结果往往不是你想要的。正文里我建议包含这几类信息前置检查执行这个 skill 之前需要确认什么。比如确认当前目录下存在src/components文件夹。执行步骤按顺序列出每一步做什么。步骤之间如果有依赖关系要明确写出来。输出规范最终产物应该长什么样。可以给一个模板或者示例。异常处理如果某一步失败了怎么办。比如如果目标文件已存在先询问用户是否覆盖。2.3 一个完整的 SKILL.md 示例光说理论没意思直接看一个完整的例子。下面这个 skill 是用来规范新增 API 接口的--- name: api-endpoint-adder description: 当用户要求在现有后端项目中新增一个 REST API 接口时使用确保接口遵循项目的分层架构和错误处理约定 version: 1.0.0 --- ## 目标 在现有项目中新增一个符合团队规范的 REST API 接口。 ## 前置检查 1. 确认项目根目录存在 src/routes、src/controllers、src/services 三个文件夹 2. 确认 src/routes/index.ts 存在且已注册路由聚合逻辑 ## 执行步骤 1. 在 src/routes/ 下创建路由文件文件名使用 kebab-case例如 user-profile.ts 2. 在 src/controllers/ 下创建对应的控制器文件名与路由文件保持一致 3. 在 src/services/ 下创建业务逻辑文件同样保持命名一致 4. 在 src/routes/index.ts 中注册新路由 5. 所有接口必须使用统一的响应包装函数 wrapResponse()该函数位于 src/utils/response.ts ## 错误处理约定 - 参数校验失败返回 400错误码格式为 ERR_INVALID_PARAM - 资源不存在返回 404错误码格式为 ERR_NOT_FOUND - 服务端异常返回 500错误码格式为 ERR_INTERNAL ## 输出示例 路由文件应包含 - 导入控制器 - 定义路由路径和方法 - 导出 router 实例这个例子的价值在于它把团队约定这种平时只存在于老员工脑子里的东西变成了 AI 可以直接读取和执行的指令。新人或者 AI拿到这个 skill不需要问任何人就能产出符合规范的代码。提示写 skill 的时候尽量用必须禁止统一使用这类明确的词避免建议可以考虑最好这类模糊表达。AI 对模糊词的处理方式是不可预测的。3. 安装与加载skill 是怎么被 AI 助手看见的3.1 目录约定放在哪里才能被识别写好了SKILL.md下一步是让 AI 助手能找到它。不同的工具对 skill 的存放位置有不同的约定但核心逻辑是一样的AI 助手会在启动时扫描特定目录把符合条件的 skill 加载到上下文中。常见的存放位置有这么几类项目级目录放在项目根目录下的.skills/或者.claude/skills/文件夹里。这种 skill 只对当前项目生效适合项目特有的规范。用户级目录放在用户主目录下的配置文件夹里比如~/.config/skills/或者~/.claude/skills/。这种 skill 对所有项目生效适合个人通用的工作习惯。全局共享目录有些团队会维护一个共享的 skill 仓库通过 git submodule 或者包管理工具同步到本地。我个人的建议是项目特有的规范放项目级个人通用的习惯放用户级。不要把项目相关的 skill 放到用户级否则你在别的项目里工作时AI 会加载一堆不相关的指令反而干扰判断。3.2 加载机制AI 是怎么决定用哪个 skill 的这里涉及一个很多人关心的问题如果我有几十个 skillAI 每次都会全部加载吗答案是否定的。AI 助手通常采用按需加载的策略——启动时只读取所有 skill 的元信息头name、description、tags建立一个索引。当用户的请求匹配到某个 skill 的 description 时才把完整的SKILL.md内容加载进上下文。这个机制意味着两件事第一description 的质量至关重要。它是 skill 被触发的唯一入口。如果 description 写得不好skill 写得再详细也没用因为根本不会被加载。第二skill 数量多了之后要注意去重和分层。如果你有五个 skill 的 description 都涉及代码生成AI 可能会在多个 skill 之间犹豫甚至同时加载多个导致指令冲突。解决办法是给 skill 分层次——通用的放一层具体的放一层description 里明确写清楚适用边界。3.3 手动安装第三方 skill 的完整流程热词里有很多人在问怎么手动装 GitHub 上的 skills我在这里给一个通用的流程。假设你在某个开源仓库里看到了一个想要的 skill确认 skill 的目录结构。通常一个 skill 是一个独立的文件夹里面至少包含SKILL.md。有些还会附带examples/、templates/等辅助文件。下载或克隆到本地。可以直接下载 zip 解压也可以用 git clone。如果只是单个 skill直接复制文件夹就行。放到正确的目录。根据你要让它生效的范围放到项目级或用户级的 skills 目录下。检查元信息头。打开SKILL.md确认 frontmatter 格式正确没有语法错误。YAML 对缩进很敏感一个空格错了整个文件就废了。重启 AI 助手。大多数工具只在启动时扫描 skill 目录运行中新增的 skill 不会自动加载。验证是否生效。发一个应该触发该 skill 的请求观察 AI 的行为是否符合 skill 里定义的流程。注意从网上拿到的 skill 不要直接就用。先通读一遍SKILL.md确认里面的指令不会和你项目的实际规范冲突。我见过有人装了一个 skill结果它要求所有文件都用 tab 缩进而项目规范是空格导致 AI 生成的代码格式全乱。4. 自己动手写一个 skill从需求到落地的完整过程4.1 选对场景什么样的工作适合写成 skill不是所有事情都值得写成 skill。我判断的标准有三个重复性高这件事你每周至少要做一次每次流程都差不多。有明确的规范存在正确做法和错误做法的区分而且这个区分不是显而易见的。容易出错新人或者 AI 在没有指导的情况下大概率会做错或者漏掉某些步骤。三个条件同时满足的场景就是写 skill 的最佳候选。比如新增数据库迁移文件发布 npm 包生成 API 文档这类工作流程固定、有约定、容易漏步骤非常适合写成 skill。反过来那些一次性的、探索性的、没有标准答案的工作就不适合。比如设计系统架构这种事每次情况都不一样写成 skill 反而会限制 AI 的发挥。4.2 把流程拆解成原子步骤确定场景之后下一步是拆解流程。这里的关键是拆到足够细细到每一步都是一个不可再分的动作。我拿发布 npm 包举例。粗粒度的流程可能是构建、测试、发布三步。但这样写 AI 执行起来还是会出问题因为每一步里面都藏着细节。正确的拆法是这样的确认当前分支是main且工作区干净运行npm run lint确保没有 lint 错误运行npm run test确保所有测试通过运行npm run build生成产物用npm version patch/minor/major更新版本号检查package.json中的files字段确保产物目录被包含运行npm publish --access public推送版本号变更到远程仓库拆到这个粒度AI 才能一步步执行而且每一步都有明确的成功/失败判断标准。如果某一步失败了也能精确定位问题出在哪。4.3 用检查点代替假设写 skill 的时候有一个思维陷阱默认 AI 会自己检查前置条件。实际上不会。如果你不明确写确认 X 存在AI 很可能会跳过检查直接往下走然后在某个地方报错。所以我的做法是在关键节点插入显式的检查点。检查点的写法很简单就是一句确认……如果……则……。比如确认package.json中的version字段与 git tag 一致如果不一致则先修正确认目标目录为空如果不为空则询问用户是否清空确认环境变量NODE_ENV已设置如果未设置则默认为production这些检查点看起来啰嗦但它们能避免 90% 的AI 跑偏问题。我自己的经验是一个 skill 里检查点的数量和它的可靠性成正比。4.4 给 skill 加上反例这一点很少有人提到但我觉得特别重要。在 skill 里明确写出不要做什么比只写要做什么更有效。原因是AI 在缺乏明确指令时会倾向于自由发挥而自由发挥的方向往往是它训练数据里最常见的做法不一定是你项目里的做法。如果你只写使用函数式组件AI 可能会用箭头函数也可能用function声明。但如果你写使用箭头函数禁止使用function声明AI 就不会犹豫了。反例的写法通常是这样的## 禁止事项 - 禁止在组件内部直接调用 API所有数据请求必须通过 src/services/ 下的服务函数 - 禁止使用 any 类型如果确实无法确定类型使用 unknown 并添加类型守卫 - 禁止在路由文件中写业务逻辑路由文件只负责路径映射这些禁止条款本质上是在给 AI 划定边界。边界越清晰输出越可控。5. 实战中踩过的坑skill 不生效、冲突、失效的排查思路5.1 skill 完全不触发从 description 开始查最常见的问题就是明明写了 skillAI 却像没看见一样。排查顺序是这样的第一步检查文件位置和命名。SKILL.md的文件名必须完全一致大小写敏感。有些工具要求文件夹名和 skill 的name字段一致不一致就不会加载。第二步检查 frontmatter 格式。YAML 对格式极其严格。常见的错误包括---前后有多余空格、缩进用了 tab 而不是空格、字符串里包含特殊字符没有加引号。我建议用在线 YAML 校验工具过一遍。第三步检查 description 的触发匹配度。这是最容易被忽略的。如果你的 description 写的是用于处理数据而用户的请求是帮我写个查询接口AI 很可能匹配不上。解决办法是把 description 写得更贴近实际请求的表达方式。第四步检查是否有多个 skill 竞争。如果两个 skill 的 description 都匹配当前请求AI 可能会选择其中一个或者两个都不选。这时候需要调整 description让每个 skill 的适用范围更明确。5.2 skill 加载了但行为不对指令冲突的识别与解决有时候 skill 确实被加载了但 AI 的行为和预期不符。这通常是指令冲突导致的。冲突的来源有两种一种是 skill 内部自相矛盾比如前面写使用分号后面写遵循 Standard 风格不用分号。另一种是多个 skill 之间的冲突比如项目级 skill 说用 4 空格缩进用户级 skill 说用 2 空格缩进。排查方法很简单把当前生效的所有 skill 列出来逐条对比指令。如果发现冲突优先级规则通常是项目级 用户级 全局级。但为了保险最好在 skill 里显式写明优先级比如本 skill 的指令优先于用户级通用规范。5.3 skill 突然失效环境变化导致的隐性依赖还有一种情况是 skill 之前用得好好的某天突然不生效了。这种突然失效往往和环境变化有关目录结构变了skill 里引用的路径不存在了导致前置检查失败。依赖的工具升级了比如 skill 里写的命令在新版本里改了参数。AI 助手本身更新了加载机制或者 frontmatter 的字段定义发生了变化。我的建议是给每个 skill 标注一个最后验证日期定期回顾。特别是那些依赖外部工具或特定目录结构的 skill环境一变就要重新验证。问题现象最可能的原因排查动作完全不触发description 不匹配用实际请求语句测试匹配度触发但行为不符指令冲突列出所有生效 skill 对比指令之前正常突然失效环境变化检查路径、命令、工具版本时好时坏多个 skill 竞争精简 description明确边界6. 让 skill 真正好用的几个进阶思路6.1 分层组织把大流程拆成多个小 skill一个 skill 不要试图覆盖太多内容。我见过有人写了一个全栈开发规范的 skill里面从数据库设计到前端样式全都有结果 AI 加载之后反而不知道该关注哪部分。更好的做法是按职责拆分。比如新增功能这个大流程可以拆成数据库迁移API 接口前端组件测试用例四个独立的 skill。每个 skill 只关注自己那一块description 也写得更精准。AI 在处理具体任务时只会加载相关的那一个。分层还有一个好处复用性更高。API 接口这个 skill 在多个项目里都能用而全栈开发规范这种大而全的 skill 换个项目就废了。6.2 版本管理skill 也需要迭代skill 不是写完就完事了。项目在变规范在变skill 也要跟着变。我建议把 skill 纳入版本管理和代码一起提交。每次修改 skill 的时候在 frontmatter 里更新version字段并在文件末尾加一个简单的变更记录。## 变更记录 - 1.2.0: 新增对 TypeScript 5.0 装饰器的支持 - 1.1.0: 调整错误码格式与后端新规范对齐 - 1.0.0: 初始版本这样做的好处是当 AI 行为出现异常时你可以快速定位是不是最近改了 skill 导致的。6.3 用真实任务验证 skill 的有效性写完一个 skill怎么知道它好不好用唯一的办法是拿真实任务去跑。而且不能只跑一次要跑不同类型的任务观察 AI 在不同情况下的表现。我的验证清单是这样的标准场景完全符合 skill 描述的任务看 AI 是否按步骤执行边界场景部分符合的任务看 AI 是否会误触发异常场景前置条件不满足的任务看 AI 是否正确处理冲突场景同时有其他 skill 生效的任务看 AI 是否优先执行本 skill跑完这四类场景基本就能判断一个 skill 的成熟度了。如果边界场景和冲突场景表现不好说明 description 还需要打磨。6.4 从社区 skill 中学习写法最后说一个快速提升 skill 写作水平的方法去读别人写的高质量 skill。GitHub 上有很多开源的 skill 仓库覆盖数学建模、前端开发、数据处理等各种场景。读的时候不要只看内容要关注它的结构——元信息头怎么写的、步骤怎么拆的、检查点放在哪里、反例怎么列的。我自己的很多写法都是从别人的 skill 里学来的。比如用检查点代替假设这个思路就是看到一个数学建模的 skill 里每一步之前都有确认数据格式正确的检查才意识到这个做法的重要性。提示参考别人的 skill 时注意区分通用写法和特定项目约定。通用写法可以直接借鉴特定约定要根据自己项目的情况调整。7. 关于 skills 的一些个人体会用了这段时间的 skills我最大的感受是它改变的不是 AI 的能力上限而是 AI 的稳定性下限。没有 skill 的时候AI 可能偶尔能做出符合规范的东西但你不确定它下次还能不能做到。有了 skill 之后只要 skill 写得够清楚AI 的输出就变得可预期了。另一个体会是写 skill 的过程其实是在梳理自己的知识。很多规范你平时做的时候是下意识的不会刻意去想。但当你需要把它写成 AI 能读懂的指令时就必须把每个细节都想清楚。这个过程本身就有价值哪怕你最后不用 AI这些整理出来的规范对团队新人也是有用的。还有一个坑我想提醒一下不要过度依赖 skill。skill 是辅助工具不是万能药。有些任务就是需要人的判断硬要写成 skill 反而会限制发挥。我的原则是流程性的工作写成 skill判断性的工作留给人。分清楚这两类skill 才能真正帮到你。最后分享一个小技巧如果你不确定某个流程该不该写成 skill先试着用自然语言把它完整描述一遍。如果描述过程中你发现这里要看情况那里不一定那说明这个流程还不够标准化暂时不适合写成 skill。等流程稳定了再写效果会好很多。
AI编码助手Skills完全指南：从SKILL.md编写到实战避坑
1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是各种开发者群聊里skills这个词出现的频率高得离谱。很多人第一次看到它的时候会一脸懵——这玩意儿到底是插件是脚本还是某种新的包管理机制其实把它拆开来看就很好理解了skills 本质上是一套写给 AI 编码助手看的操作说明书它用结构化的 Markdown 文件通常叫SKILL.md告诉 AI 在特定场景下应该怎么做、按什么顺序做、注意哪些坑。你可以把它想象成给一个新来的实习生准备的岗位手册。这个实习生很聪明学习能力极强但他不知道你们团队内部的约定——比如提交代码前必须跑哪几个检查、某个目录下的文件不能随便动、生成某个类型的代码时要遵循什么命名规范。skills 就是把这些隐性知识显性化写成 AI 能读懂的文档让它在干活的时候自动加载。为什么这个东西突然火了核心原因在于通用大模型的能力已经足够强但通用恰恰是它的短板。一个模型可能什么都懂一点但在你的具体项目里它不知道你的技术栈偏好、不知道你的目录结构约定、不知道你踩过哪些坑。skills 就是用来填补这个最后一公里的。它不改变模型本身而是通过上下文注入的方式让模型在特定任务上表现得像一个熟悉你项目的老手。从热词里能看出来大家关心的方向非常集中怎么安装、怎么写、怎么管理、有哪些好用的现成 skills 可以拿来就用。数学建模、前端开发、AI 漫剧、嵌入式比如 STM32这些领域都有人在整理自己的 skills 库。这说明 skills 不是一个纯技术概念而是一种跨领域的知识封装方式——任何有固定流程、有经验积累的工作都可以被写成 skill。这篇文章我会从零开始把 skills 的来龙去脉、文件结构、编写方法、安装管理、实战技巧全部讲清楚。不管你是刚听说这个词的新手还是已经用过几个现成 skills 想自己动手写的老手都能从这里找到能直接用的东西。2. SKILL.md 的文件结构一个 skill 到底由什么组成2.1 最小可用结构三个部分缺一不可一个能跑的 skill最核心的就是一个SKILL.md文件。别看它只是个 Markdown里面的结构是有讲究的。我见过太多人上来就写一大段自然语言描述结果 AI 读完之后该干嘛还是干嘛完全没起作用。问题就出在结构上。一个合格的SKILL.md通常包含三个部分元信息头frontmatter用 YAML 格式写在文件最顶部用---包裹。这里定义 skill 的名称、描述、触发条件等。这是 AI 判断什么时候该用这个 skill的依据。正文说明用自然语言描述这个 skill 的目标、适用场景、前置条件。这部分是给 AI 建立整体认知的。操作步骤具体的执行流程通常用有序列表或者分节的代码块来写。这是 skill 的干货部分。我拿一个实际例子来说明。假设你要写一个生成 React 组件的 skill元信息头大概长这样--- name: react-component-generator description: 当用户要求创建新的 React 函数式组件时使用此 skill确保组件遵循项目的目录结构和命名规范 version: 1.0.0 tags: - frontend - react - codegen ---这里有个细节很多人会忽略description 字段的写法直接决定了 skill 能不能被正确触发。如果你写得太笼统比如用于前端开发那 AI 几乎不会主动调用它因为太宽泛了。正确的做法是把触发场景写具体——当用户要求创建新的 React 函数式组件时这样 AI 在遇到类似请求时才能精准匹配。2.2 正文部分把隐性知识翻译成可执行指令元信息头之后就是正文。这部分最容易犯的错误是写成介绍性文档而不是操作指令。区别在哪介绍性文档会说React 组件应该遵循良好的命名规范而操作指令会说组件文件名使用 PascalCase例如UserProfile.tsx组件内部导出的函数名与文件名保持一致。后者才是 AI 能直接执行的东西。我总结了一个原则每一条指令都应该是可验证的。也就是说AI 执行完之后你能明确判断它做对了还是做错了。模糊的描述只会让 AI 自由发挥而自由发挥的结果往往不是你想要的。正文里我建议包含这几类信息前置检查执行这个 skill 之前需要确认什么。比如确认当前目录下存在src/components文件夹。执行步骤按顺序列出每一步做什么。步骤之间如果有依赖关系要明确写出来。输出规范最终产物应该长什么样。可以给一个模板或者示例。异常处理如果某一步失败了怎么办。比如如果目标文件已存在先询问用户是否覆盖。2.3 一个完整的 SKILL.md 示例光说理论没意思直接看一个完整的例子。下面这个 skill 是用来规范新增 API 接口的--- name: api-endpoint-adder description: 当用户要求在现有后端项目中新增一个 REST API 接口时使用确保接口遵循项目的分层架构和错误处理约定 version: 1.0.0 --- ## 目标 在现有项目中新增一个符合团队规范的 REST API 接口。 ## 前置检查 1. 确认项目根目录存在 src/routes、src/controllers、src/services 三个文件夹 2. 确认 src/routes/index.ts 存在且已注册路由聚合逻辑 ## 执行步骤 1. 在 src/routes/ 下创建路由文件文件名使用 kebab-case例如 user-profile.ts 2. 在 src/controllers/ 下创建对应的控制器文件名与路由文件保持一致 3. 在 src/services/ 下创建业务逻辑文件同样保持命名一致 4. 在 src/routes/index.ts 中注册新路由 5. 所有接口必须使用统一的响应包装函数 wrapResponse()该函数位于 src/utils/response.ts ## 错误处理约定 - 参数校验失败返回 400错误码格式为 ERR_INVALID_PARAM - 资源不存在返回 404错误码格式为 ERR_NOT_FOUND - 服务端异常返回 500错误码格式为 ERR_INTERNAL ## 输出示例 路由文件应包含 - 导入控制器 - 定义路由路径和方法 - 导出 router 实例这个例子的价值在于它把团队约定这种平时只存在于老员工脑子里的东西变成了 AI 可以直接读取和执行的指令。新人或者 AI拿到这个 skill不需要问任何人就能产出符合规范的代码。提示写 skill 的时候尽量用必须禁止统一使用这类明确的词避免建议可以考虑最好这类模糊表达。AI 对模糊词的处理方式是不可预测的。3. 安装与加载skill 是怎么被 AI 助手看见的3.1 目录约定放在哪里才能被识别写好了SKILL.md下一步是让 AI 助手能找到它。不同的工具对 skill 的存放位置有不同的约定但核心逻辑是一样的AI 助手会在启动时扫描特定目录把符合条件的 skill 加载到上下文中。常见的存放位置有这么几类项目级目录放在项目根目录下的.skills/或者.claude/skills/文件夹里。这种 skill 只对当前项目生效适合项目特有的规范。用户级目录放在用户主目录下的配置文件夹里比如~/.config/skills/或者~/.claude/skills/。这种 skill 对所有项目生效适合个人通用的工作习惯。全局共享目录有些团队会维护一个共享的 skill 仓库通过 git submodule 或者包管理工具同步到本地。我个人的建议是项目特有的规范放项目级个人通用的习惯放用户级。不要把项目相关的 skill 放到用户级否则你在别的项目里工作时AI 会加载一堆不相关的指令反而干扰判断。3.2 加载机制AI 是怎么决定用哪个 skill 的这里涉及一个很多人关心的问题如果我有几十个 skillAI 每次都会全部加载吗答案是否定的。AI 助手通常采用按需加载的策略——启动时只读取所有 skill 的元信息头name、description、tags建立一个索引。当用户的请求匹配到某个 skill 的 description 时才把完整的SKILL.md内容加载进上下文。这个机制意味着两件事第一description 的质量至关重要。它是 skill 被触发的唯一入口。如果 description 写得不好skill 写得再详细也没用因为根本不会被加载。第二skill 数量多了之后要注意去重和分层。如果你有五个 skill 的 description 都涉及代码生成AI 可能会在多个 skill 之间犹豫甚至同时加载多个导致指令冲突。解决办法是给 skill 分层次——通用的放一层具体的放一层description 里明确写清楚适用边界。3.3 手动安装第三方 skill 的完整流程热词里有很多人在问怎么手动装 GitHub 上的 skills我在这里给一个通用的流程。假设你在某个开源仓库里看到了一个想要的 skill确认 skill 的目录结构。通常一个 skill 是一个独立的文件夹里面至少包含SKILL.md。有些还会附带examples/、templates/等辅助文件。下载或克隆到本地。可以直接下载 zip 解压也可以用 git clone。如果只是单个 skill直接复制文件夹就行。放到正确的目录。根据你要让它生效的范围放到项目级或用户级的 skills 目录下。检查元信息头。打开SKILL.md确认 frontmatter 格式正确没有语法错误。YAML 对缩进很敏感一个空格错了整个文件就废了。重启 AI 助手。大多数工具只在启动时扫描 skill 目录运行中新增的 skill 不会自动加载。验证是否生效。发一个应该触发该 skill 的请求观察 AI 的行为是否符合 skill 里定义的流程。注意从网上拿到的 skill 不要直接就用。先通读一遍SKILL.md确认里面的指令不会和你项目的实际规范冲突。我见过有人装了一个 skill结果它要求所有文件都用 tab 缩进而项目规范是空格导致 AI 生成的代码格式全乱。4. 自己动手写一个 skill从需求到落地的完整过程4.1 选对场景什么样的工作适合写成 skill不是所有事情都值得写成 skill。我判断的标准有三个重复性高这件事你每周至少要做一次每次流程都差不多。有明确的规范存在正确做法和错误做法的区分而且这个区分不是显而易见的。容易出错新人或者 AI 在没有指导的情况下大概率会做错或者漏掉某些步骤。三个条件同时满足的场景就是写 skill 的最佳候选。比如新增数据库迁移文件发布 npm 包生成 API 文档这类工作流程固定、有约定、容易漏步骤非常适合写成 skill。反过来那些一次性的、探索性的、没有标准答案的工作就不适合。比如设计系统架构这种事每次情况都不一样写成 skill 反而会限制 AI 的发挥。4.2 把流程拆解成原子步骤确定场景之后下一步是拆解流程。这里的关键是拆到足够细细到每一步都是一个不可再分的动作。我拿发布 npm 包举例。粗粒度的流程可能是构建、测试、发布三步。但这样写 AI 执行起来还是会出问题因为每一步里面都藏着细节。正确的拆法是这样的确认当前分支是main且工作区干净运行npm run lint确保没有 lint 错误运行npm run test确保所有测试通过运行npm run build生成产物用npm version patch/minor/major更新版本号检查package.json中的files字段确保产物目录被包含运行npm publish --access public推送版本号变更到远程仓库拆到这个粒度AI 才能一步步执行而且每一步都有明确的成功/失败判断标准。如果某一步失败了也能精确定位问题出在哪。4.3 用检查点代替假设写 skill 的时候有一个思维陷阱默认 AI 会自己检查前置条件。实际上不会。如果你不明确写确认 X 存在AI 很可能会跳过检查直接往下走然后在某个地方报错。所以我的做法是在关键节点插入显式的检查点。检查点的写法很简单就是一句确认……如果……则……。比如确认package.json中的version字段与 git tag 一致如果不一致则先修正确认目标目录为空如果不为空则询问用户是否清空确认环境变量NODE_ENV已设置如果未设置则默认为production这些检查点看起来啰嗦但它们能避免 90% 的AI 跑偏问题。我自己的经验是一个 skill 里检查点的数量和它的可靠性成正比。4.4 给 skill 加上反例这一点很少有人提到但我觉得特别重要。在 skill 里明确写出不要做什么比只写要做什么更有效。原因是AI 在缺乏明确指令时会倾向于自由发挥而自由发挥的方向往往是它训练数据里最常见的做法不一定是你项目里的做法。如果你只写使用函数式组件AI 可能会用箭头函数也可能用function声明。但如果你写使用箭头函数禁止使用function声明AI 就不会犹豫了。反例的写法通常是这样的## 禁止事项 - 禁止在组件内部直接调用 API所有数据请求必须通过 src/services/ 下的服务函数 - 禁止使用 any 类型如果确实无法确定类型使用 unknown 并添加类型守卫 - 禁止在路由文件中写业务逻辑路由文件只负责路径映射这些禁止条款本质上是在给 AI 划定边界。边界越清晰输出越可控。5. 实战中踩过的坑skill 不生效、冲突、失效的排查思路5.1 skill 完全不触发从 description 开始查最常见的问题就是明明写了 skillAI 却像没看见一样。排查顺序是这样的第一步检查文件位置和命名。SKILL.md的文件名必须完全一致大小写敏感。有些工具要求文件夹名和 skill 的name字段一致不一致就不会加载。第二步检查 frontmatter 格式。YAML 对格式极其严格。常见的错误包括---前后有多余空格、缩进用了 tab 而不是空格、字符串里包含特殊字符没有加引号。我建议用在线 YAML 校验工具过一遍。第三步检查 description 的触发匹配度。这是最容易被忽略的。如果你的 description 写的是用于处理数据而用户的请求是帮我写个查询接口AI 很可能匹配不上。解决办法是把 description 写得更贴近实际请求的表达方式。第四步检查是否有多个 skill 竞争。如果两个 skill 的 description 都匹配当前请求AI 可能会选择其中一个或者两个都不选。这时候需要调整 description让每个 skill 的适用范围更明确。5.2 skill 加载了但行为不对指令冲突的识别与解决有时候 skill 确实被加载了但 AI 的行为和预期不符。这通常是指令冲突导致的。冲突的来源有两种一种是 skill 内部自相矛盾比如前面写使用分号后面写遵循 Standard 风格不用分号。另一种是多个 skill 之间的冲突比如项目级 skill 说用 4 空格缩进用户级 skill 说用 2 空格缩进。排查方法很简单把当前生效的所有 skill 列出来逐条对比指令。如果发现冲突优先级规则通常是项目级 用户级 全局级。但为了保险最好在 skill 里显式写明优先级比如本 skill 的指令优先于用户级通用规范。5.3 skill 突然失效环境变化导致的隐性依赖还有一种情况是 skill 之前用得好好的某天突然不生效了。这种突然失效往往和环境变化有关目录结构变了skill 里引用的路径不存在了导致前置检查失败。依赖的工具升级了比如 skill 里写的命令在新版本里改了参数。AI 助手本身更新了加载机制或者 frontmatter 的字段定义发生了变化。我的建议是给每个 skill 标注一个最后验证日期定期回顾。特别是那些依赖外部工具或特定目录结构的 skill环境一变就要重新验证。问题现象最可能的原因排查动作完全不触发description 不匹配用实际请求语句测试匹配度触发但行为不符指令冲突列出所有生效 skill 对比指令之前正常突然失效环境变化检查路径、命令、工具版本时好时坏多个 skill 竞争精简 description明确边界6. 让 skill 真正好用的几个进阶思路6.1 分层组织把大流程拆成多个小 skill一个 skill 不要试图覆盖太多内容。我见过有人写了一个全栈开发规范的 skill里面从数据库设计到前端样式全都有结果 AI 加载之后反而不知道该关注哪部分。更好的做法是按职责拆分。比如新增功能这个大流程可以拆成数据库迁移API 接口前端组件测试用例四个独立的 skill。每个 skill 只关注自己那一块description 也写得更精准。AI 在处理具体任务时只会加载相关的那一个。分层还有一个好处复用性更高。API 接口这个 skill 在多个项目里都能用而全栈开发规范这种大而全的 skill 换个项目就废了。6.2 版本管理skill 也需要迭代skill 不是写完就完事了。项目在变规范在变skill 也要跟着变。我建议把 skill 纳入版本管理和代码一起提交。每次修改 skill 的时候在 frontmatter 里更新version字段并在文件末尾加一个简单的变更记录。## 变更记录 - 1.2.0: 新增对 TypeScript 5.0 装饰器的支持 - 1.1.0: 调整错误码格式与后端新规范对齐 - 1.0.0: 初始版本这样做的好处是当 AI 行为出现异常时你可以快速定位是不是最近改了 skill 导致的。6.3 用真实任务验证 skill 的有效性写完一个 skill怎么知道它好不好用唯一的办法是拿真实任务去跑。而且不能只跑一次要跑不同类型的任务观察 AI 在不同情况下的表现。我的验证清单是这样的标准场景完全符合 skill 描述的任务看 AI 是否按步骤执行边界场景部分符合的任务看 AI 是否会误触发异常场景前置条件不满足的任务看 AI 是否正确处理冲突场景同时有其他 skill 生效的任务看 AI 是否优先执行本 skill跑完这四类场景基本就能判断一个 skill 的成熟度了。如果边界场景和冲突场景表现不好说明 description 还需要打磨。6.4 从社区 skill 中学习写法最后说一个快速提升 skill 写作水平的方法去读别人写的高质量 skill。GitHub 上有很多开源的 skill 仓库覆盖数学建模、前端开发、数据处理等各种场景。读的时候不要只看内容要关注它的结构——元信息头怎么写的、步骤怎么拆的、检查点放在哪里、反例怎么列的。我自己的很多写法都是从别人的 skill 里学来的。比如用检查点代替假设这个思路就是看到一个数学建模的 skill 里每一步之前都有确认数据格式正确的检查才意识到这个做法的重要性。提示参考别人的 skill 时注意区分通用写法和特定项目约定。通用写法可以直接借鉴特定约定要根据自己项目的情况调整。7. 关于 skills 的一些个人体会用了这段时间的 skills我最大的感受是它改变的不是 AI 的能力上限而是 AI 的稳定性下限。没有 skill 的时候AI 可能偶尔能做出符合规范的东西但你不确定它下次还能不能做到。有了 skill 之后只要 skill 写得够清楚AI 的输出就变得可预期了。另一个体会是写 skill 的过程其实是在梳理自己的知识。很多规范你平时做的时候是下意识的不会刻意去想。但当你需要把它写成 AI 能读懂的指令时就必须把每个细节都想清楚。这个过程本身就有价值哪怕你最后不用 AI这些整理出来的规范对团队新人也是有用的。还有一个坑我想提醒一下不要过度依赖 skill。skill 是辅助工具不是万能药。有些任务就是需要人的判断硬要写成 skill 反而会限制发挥。我的原则是流程性的工作写成 skill判断性的工作留给人。分清楚这两类skill 才能真正帮到你。最后分享一个小技巧如果你不确定某个流程该不该写成 skill先试着用自然语言把它完整描述一遍。如果描述过程中你发现这里要看情况那里不一定那说明这个流程还不够标准化暂时不适合写成 skill。等流程稳定了再写效果会好很多。
