1. 从“skills”这个热词说起：它到底是什么，为什么突然火了
如果你最近在技术社区、AI 工具群或者前端圈子里频繁看到“skills”这个词，不用怀疑，它确实正在成为 Claude 生态里一个绕不开的话题。我第一次接触这个概念的时候也愣了一下——skills？技能？听起来像是一个很泛的词，但当你真正把它和 Claude Code、SKILL.md、Agent Skills 这些关键词放在一起看的时候，就会发现它其实指向一个非常具体的东西：一套让 AI 助手按照你预设的方式去执行特定任务的模块化能力包。
说白了，skills 就是给 Claude 这类 AI 编程助手“开小灶”的方式。默认情况下，Claude Code 已经能帮你写代码、改 bug、跑命令，但每个团队、每个人的工作流都不一样。有人希望 AI 在提交代码前自动跑一遍 lint，有人希望它按照公司内部的组件规范生成前端代码，有人希望它在做数学建模时自动调用特定的求解器模板。这些“个性化需求”如果每次都靠手动写 prompt 来解决，效率极低且容易遗漏。skills 的出现，就是把这些重复性的、有固定套路的任务封装成可复用的技能模块，让 AI 在需要的时候自动加载并执行。
我实测下来的感受是：skills 本质上是一种“上下文注入 + 行为约束”的机制。它通过一个叫 SKILL.md 的 Markdown 文件来定义技能的名称、触发条件、执行步骤和注意事项，然后 Claude Code 在运行过程中会根据当前任务自动匹配并加载对应的 skill。这个设计思路非常聪明，因为它把“怎么让 AI 更懂我的项目”这件事从“写更长的 prompt”变成了“维护一套结构化的技能库”。
适合谁来用？我的判断是三类人：第一类是每天用 Claude Code 写代码的开发者，尤其是前端开发和全栈开发，因为前端开发 skills 是目前社区里最活跃的方向之一；第二类是做数学建模、数据分析的研究者，数学建模 skills 和 codex nature skills 这类需求在比赛场景下特别实用；第三类是对 AI 工作流自动化感兴趣的技术爱好者，哪怕你只是想让 Claude 帮你自动整理笔记、生成周报，skills 也能派上用场。
2. skills 的核心机制拆解：SKILL.md 到底怎么写才有效
2.1 SKILL.md 的文件结构与字段含义
SKILL.md 是整个 skills 机制的核心载体。你可以把它理解成一份“技能说明书”，Claude Code 在启动时会扫描指定目录下的所有 SKILL.md 文件，建立索引，然后在对话过程中根据用户输入和当前上下文来判断是否需要激活某个技能。我翻了不少社区里的开源 skills 仓库，也自己写了十几个 skill 测试，总结下来一个可用的 SKILL.md 通常包含以下几个关键部分。
首先是元信息区，一般用 YAML front matter 的形式写在文件顶部，包括name（技能名称）、description（一句话描述）、trigger（触发条件，可以是关键词、文件类型、命令模式等）。这部分决定了 Claude 能不能“认出”这个技能该在什么时候用。我踩过的一个坑是：description 写得太模糊，比如只写“帮助处理前端代码”，结果 Claude 在几乎所有涉及 JavaScript 的场景下都想加载这个 skill，反而干扰了正常对话。后来我把 description 改成“当用户要求生成 React 函数组件且项目使用 TypeScript 时激活”，匹配精度立刻上来了。
其次是执行指令区，这是 SKILL.md 的主体内容，用自然语言描述这个技能被激活后 Claude 应该做什么。这里有个经验：指令要写得像给一个聪明但完全不了解你项目的实习生看。比如你要写一个“自动生成 API 请求层代码”的 skill，不能只写“生成 API 代码”，而要写清楚：使用项目里已有的 request 封装、按照src/api/目录下的文件命名规范、每个接口导出为一个函数、错误处理统一用 try-catch 并上报到 logger。这些细节越具体，Claude 执行出来的结果就越接近你的预期。
最后是示例区，可选但强烈建议加上。给一两个输入输出的例子，Claude 对示例的理解能力远强于纯文字描述。我通常会在示例区放一个“用户输入”和“期望输出”的对照，这样即使指令区有歧义，Claude 也能通过示例来校准行为。
2.2 触发机制与加载优先级
Claude Code 加载 skills 的逻辑并不是“全部加载然后逐个尝试”，而是有一套优先级和匹配策略。根据我的实测和社区反馈，大致遵循以下规则：显式调用优先于自动匹配，项目级 skills 优先于全局 skills，具体匹配优先于模糊匹配。
显式调用就是你直接在对话里说“用 xxx skill 来做这件事”，Claude 会直接加载对应的技能，跳过匹配环节。自动匹配则是 Claude 根据当前任务描述和 SKILL.md 里的 trigger 字段来判断。项目级 skills 放在项目根目录的.claude/skills/下，只对当前项目生效；全局 skills 放在用户目录的~/.claude/skills/下，对所有项目生效。这个设计很合理，因为不同项目的技术栈和规范差异很大，项目级 skills 能保证针对性，全局 skills 则适合放一些通用的、跨项目复用的技能。
注意：如果你同时装了多个 skill 且它们的 trigger 有重叠，Claude 可能会加载多个技能导致行为混乱。我的做法是定期用
claude skills list查看已安装的技能，把不用的或者功能重叠的清理掉。社区里有人推荐用 tibo 关于清理 skills 的方法，核心思路就是“一个任务只保留一个主 skill，辅助 skill 用显式调用”。
2.3 为什么是 Markdown 而不是 JSON 或 YAML
这个问题我被问过好几次。用 Markdown 写 SKILL.md 而不是用结构化配置文件，核心原因在于skills 的本质是“给 AI 看的指令”，而不是“给程序解析的配置”。JSON 和 YAML 适合机器解析，但 Claude 理解自然语言的能力远强于理解结构化字段。用 Markdown 写指令，你可以自由地加解释、加示例、加注意事项，Claude 能从中提取出比结构化字段丰富得多的信息。
举个例子，如果你用 YAML 写一个 skill，可能只能写action: generate_component、framework: react、style: typescript。但用 Markdown，你可以写“生成一个 React 函数组件，使用 TypeScript，样式用 CSS Modules，组件名用 PascalCase，props 接口单独导出，默认导出组件本身”。后者给 Claude 的信息量和可执行性完全不是一个级别。这也是为什么社区里流行的 skills 几乎全是 Markdown 格式，包括 superpower skills 和 typesafe ai skills 这些比较知名的技能库。
3. 从零开始写一个可用的 skill：完整实操流程
3.1 环境准备与目录结构
在开始写 skill 之前，你需要确保 Claude Code 已经正确安装并能正常运行。Windows 用户可能会遇到“claude 无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这个报错，这通常是环境变量没配好或者安装路径没加到 PATH 里。我的建议是直接用官方推荐的安装方式，安装完成后在终端里跑claude --version确认能输出版本号。如果用的是 VS Code，可以装 Claude Code 的扩展，在 VS Code 配置里把 Claude Code 的路径指对，这样在编辑器里就能直接调用。
目录结构方面，我推荐这样组织：
项目根目录/ ├── .claude/ │ └── skills/ │ ├── frontend-component/ │ │ └── SKILL.md │ ├── api-generator/ │ │ └── SKILL.md │ └── math-modeling/ │ └── SKILL.md ├── src/ └── ...每个 skill 一个独立文件夹，文件夹名就是 skill 的标识名，里面放一个 SKILL.md。这种结构清晰、易于管理，也方便后续用 Git 做版本控制。全局 skills 则放在~/.claude/skills/下，结构一样。
3.2 编写第一个 skill：以“前端组件生成”为例
假设我们要写一个前端开发 skill，目标是让 Claude 按照团队规范生成 React 组件。下面是我实际在用的一个 SKILL.md 模板，你可以直接抄作业再按需修改。
--- name: frontend-component description: 当用户要求生成 React 函数组件且项目使用 TypeScript 时激活 trigger: - "生成组件" - "create component" - "新建 React 组件" --- # 前端组件生成技能 ## 执行步骤 1. 确认组件名称，使用 PascalCase 命名，文件名与组件名一致 2. 在 `src/components/` 下创建组件文件夹 3. 生成以下文件： - `index.tsx`：组件主体 - `index.module.css`：样式文件 - `types.ts`：类型定义（如果 props 超过 3 个） 4. 组件使用函数式写法，默认导出组件本身 5. props 接口以 `I` 开头命名，如 `IButtonProps` 6. 样式使用 CSS Modules，类名用 camelCase ## 注意事项 - 不要使用 class 组件 - 不要引入未在 package.json 中声明的依赖 - 如果组件需要状态管理，优先使用项目已有的状态管理方案 - 生成后自动运行 `npx tsc --noEmit` 检查类型错误 ## 示例 用户输入：帮我生成一个用户头像组件，接收 url 和 size 两个 props 期望输出： - 创建 `src/components/UserAvatar/` 目录 - 生成 `index.tsx`、`index.module.css`、`types.ts` - 组件接收 `IUserAvatarProps { url: string; size?: number }` - 默认导出 `UserAvatar` 组件这个 skill 写完之后，我在 Claude Code 里测试了十几次，生成结果的规范一致性明显提升。以前每次都要在 prompt 里重复“用 TypeScript、用 CSS Modules、默认导出”，现在只需要说“生成一个 xxx 组件”，Claude 就会自动加载这个 skill 并按规范执行。
3.3 参数计算与条件判断的写法
有些 skill 需要根据输入参数做不同的处理，这时候在 SKILL.md 里写清楚判断逻辑就很重要。比如一个“数学建模 skills”，可能需要根据题目类型选择不同的求解策略。我写过一个简化版的数学建模 skill，核心逻辑是这样的：
--- name: math-modeling description: 当用户描述数学建模问题并需要求解方案时激活 trigger: - "数学建模" - "优化问题" - "求解模型" --- # 数学建模求解技能 ## 问题分类判断 根据用户描述，按以下规则分类： 1. 如果涉及“最大/最小/最优”→ 优化问题 - 连续变量 → 线性/非线性规划 - 离散变量 → 整数规划或启发式算法 2. 如果涉及“预测/趋势”→ 预测问题 - 数据量小于 100 → 灰色预测或回归 - 数据量大于 100 → 时间序列或神经网络 3. 如果涉及“评价/排序”→ 评价问题 - 指标少 → TOPSIS 或 AHP - 指标多 → 熵权法或主成分分析 ## 求解步骤 1. 明确决策变量和目标函数 2. 列出约束条件 3. 选择合适的求解器（优先用 Python 的 scipy 或 pulp） 4. 写出完整可运行的代码 5. 对结果做敏感性分析 ## 注意事项 - 不要直接给最终答案，要展示建模过程 - 代码要能直接运行，包含数据输入示例 - 如果问题规模大，提醒用户考虑计算复杂度这个 skill 在华为杯建模比赛期间帮了我大忙，基本上描述完问题之后 Claude 就能给出一个结构清晰的建模方案，我只需要在它的基础上做调整和验证。
4. 常见问题与排查技巧实录
4.1 skill 不生效的几种典型情况
我遇到过好几次“明明写了 SKILL.md 但 Claude 就是不用”的情况，排查下来主要有以下几个原因。
第一，文件位置放错了。Claude Code 只会扫描特定目录下的 SKILL.md，如果你把文件放在项目根目录而不是.claude/skills/下，它是不会被加载的。我建议每次新建 skill 后先用claude skills list确认一下是否被识别到。
第二，trigger 写得太窄或太宽。太窄的话 Claude 匹配不到，太宽的话又会干扰其他任务。我的经验是 trigger 里至少放 2-3 个不同表述的关键词，覆盖用户可能的不同说法。比如“生成组件”和“create component”都放进去，中英文都覆盖。
第三，SKILL.md 格式有误。YAML front matter 对缩进和符号很敏感，一个中文字符的全角冒号就可能导致解析失败。我建议用 VS Code 的 YAML 插件做语法检查，或者直接参考社区里验证过的模板来改。
第四，多个 skill 冲突。如果两个 skill 的 trigger 高度重叠，Claude 可能会随机选一个或者都加载导致行为混乱。这时候需要手动调整 trigger 的优先级，或者在 description 里写清楚适用场景的差异。
4.2 性能与上下文占用的平衡
skills 虽然好用，但也不是越多越好。每个被加载的 skill 都会占用 Claude 的上下文窗口，如果一次加载了五六个 skill，留给实际任务处理的 token 就少了，响应质量会下降。我的做法是：项目级 skills 控制在 5 个以内，全局 skills 控制在 3 个以内，且定期清理不用的。
另外，SKILL.md 本身也不要写得太长。我见过有人写了一个 2000 多行的 skill 文件，结果每次加载都吃掉大量上下文。其实核心指令控制在 100-200 行就足够了，太长的内容可以拆成多个 skill，或者放到单独的参考文档里让 Claude 按需读取。
4.3 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| Claude 完全不使用 skill | 文件位置错误或格式解析失败 | 检查.claude/skills/目录，用claude skills list确认 |
| skill 被频繁误触发 | trigger 过于宽泛 | 收窄 trigger 关键词，增加具体条件 |
| 多个 skill 同时加载导致混乱 | trigger 重叠 | 调整 trigger 或改用显式调用 |
| 生成结果不符合预期 | 指令描述不够具体 | 增加示例区，细化执行步骤 |
| 响应变慢或质量下降 | 加载了过多 skill | 清理不用的 skill，控制数量 |
| Windows 下命令找不到 | 环境变量未配置 | 检查 PATH，用完整路径或重装 |
提示：如果你在 Windows 上遇到“claude 无法将‘claude’项识别为 cmdlet”这个报错，大概率是安装后没有把 Claude Code 的安装目录加到系统 PATH 里。可以手动在“系统属性-环境变量”里添加，或者直接用安装程序提供的“添加到 PATH”选项重装一次。
4.4 几个我踩过的坑和对应技巧
坑一：skill 里写了“自动运行测试”，结果 Claude 真的去跑了全量测试，等了五分钟。后来我改成“只运行与当前修改文件相关的测试”，并在 skill 里写清楚用--findRelatedTests参数，效率立刻上来了。
坑二：skill 的示例区放了一个过于复杂的例子，Claude 每次都试图复现那个例子的所有细节。示例要简单、典型，不要放边缘 case。边缘 case 放在注意事项里用文字描述就好。
坑三：不同项目的 skill 混在一起，导致 A 项目的规范被应用到 B 项目。一定要用项目级 skills 来管理项目特有的规范，全局 skills 只放真正通用的东西，比如“代码注释用中文”、“提交信息用约定式提交格式”这种。
坑四：skill 更新后没有重启 Claude Code，导致旧版本还在生效。修改 SKILL.md 后记得重启会话或者用claude skills reload重新加载。
5. skills 的进阶玩法与生态现状
5.1 组合技能与技能链
单个 skill 能解决的问题有限，真正强大的是把多个 skill 组合起来形成“技能链”。比如我现在的开发工作流是这样的：先用frontend-component生成组件骨架，然后用api-generator生成对应的请求层代码，最后用test-writer生成单元测试。这三个 skill 各自独立，但在实际使用中会按顺序被触发，形成一条完整的流水线。
实现技能链的关键是在 skill 的注意事项里写清楚“完成后建议激活的下一个技能”。比如在frontend-component的末尾加一句“组件生成后，如果涉及 API 调用，建议激活api-generator技能”。Claude 读到这句话后，会在合适的时机自动加载下一个技能。这种写法比硬编码调用关系更灵活，因为 Claude 会根据实际情况判断是否真的需要下一个技能。
5.2 社区热门 skills 推荐与选择建议
目前社区里比较活跃的 skills 方向有几个：前端开发 skills 是最成熟的，superpower skills 提供了一套比较完整的前端工作流技能；typesafe ai skills 专注于 TypeScript 类型安全相关的技能；数学建模 skills 和 codex nature skills 则在学术和竞赛场景下很受欢迎。
我的选择建议是：不要一上来就装一堆社区 skills，先自己写两三个最简单的，理解机制之后再按需引入。社区 skills 的质量参差不齐，有些写得很粗糙，直接装上去反而会干扰你的正常工作流。我通常会把社区 skills 下载下来先读一遍 SKILL.md，确认它的触发条件和执行逻辑符合我的习惯之后再放到项目里用。
另外，skills 的生态还在快速变化中。今天好用的 skill 明天可能就被更好的替代了，所以保持关注但不要过度依赖。核心还是理解 SKILL.md 的编写逻辑，这样无论生态怎么变，你都能快速写出适合自己的技能。
5.3 从 skills 看 AI 辅助开发的未来形态
我用 Claude Code 配合 skills 工作了几个月，最大的体会是：AI 辅助开发正在从“对话式”向“配置式”演进。以前我们跟 AI 的交互主要是写 prompt，每次都要重新描述需求；现在通过 skills，我们可以把重复性的需求固化成配置，AI 在需要的时候自动加载。这本质上是一种“把 prompt 工程沉淀为工程资产”的思路。
这个思路的延伸空间很大。比如团队可以把代码规范、架构决策、部署流程都写成 skills，新成员入职时只要装好 skills，Claude 就能按照团队标准来辅助开发，大大降低了上手成本。再比如个人可以把常用的工作流都 skill 化，形成一套属于自己的“AI 工作操作系统”。
我目前还在探索的一个方向是动态 skills——根据当前项目的技术栈和依赖自动生成或调整 skill 内容。比如检测到项目用了 Next.js，就自动激活对应的 Next.js 开发规范 skill。这个方向目前还需要一些脚本配合，但思路是可行的，社区里也有人在做类似的尝试。
最后分享一个我个人的小技巧：每次写完一个新 skill，先别急着用，花五分钟读一遍，想象自己是一个完全不了解这个项目的人，看能不能仅凭这个 SKILL.md 就正确执行任务。如果读下来觉得有歧义或者遗漏，那就说明还需要补充细节。这个自检习惯帮我避免了很多“skill 写了但不好用”的情况。
