1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、技术群或者视频平台上频繁刷到“skills”这个词大概率不是指传统意义上的“技能”泛称而是特指围绕 Claude 生态衍生出来的一套能力扩展机制——Agent Skills。简单说它是一套让 AI 助手从“只会聊天”变成“能按你的规矩干活”的配置方案。核心载体通常是一个叫SKILL.md的文件配合若干辅助脚本、模板或资源文件放在指定目录下AI 在需要时自动读取并执行。我第一次接触这个概念是在一个前端项目里。当时想让 Claude Code 帮我按团队规范生成组件代码但每次都要重复粘贴一堆约束条件烦得很。后来有人丢给我一个SKILL.md说“把这个放到对应目录以后它自己会看”。试了一下确实省事——AI 在生成代码前会先读这个文件然后按里面写的规则来。这就是 skills 最朴素的价值把重复的指令沉淀成可复用的能力包。它解决的问题很具体。以前用 AI 辅助开发你得在每次对话里反复交代“用 TypeScript 严格模式”“组件必须带 PropTypes”“样式用 CSS Modules 不要用内联”说多了自己都嫌烦。skills 机制相当于给 AI 装了一本“工作手册”它自己会翻。适合谁来学前端开发者、全栈工程师、数据科学工作者、数学建模参赛者以及任何需要让 AI 按固定流程输出结果的人。哪怕你只是用 Claude Desktop 做文档整理也能通过 skills 把常用格式模板固化下来。目前社区里讨论最多的几个方向包括前端开发 skills、数学建模 skills、AI 漫剧常用 skills、superpower skills 等。不同方向的SKILL.md写法差异不小但底层逻辑相通。接下来我会从设计思路、核心细节、实操过程、常见问题四个维度把这一套东西拆开讲清楚。2. 内容整体设计与思路拆解2.1 为什么是SKILL.md而不是别的格式社区里几乎所有的 skills 方案都围绕SKILL.md展开这不是偶然。Markdown 本身是纯文本任何编辑器都能打开Git 友好diff 清晰AI 读取时也不容易因为格式解析问题丢信息。相比之下如果用 JSON 或 YAML 来写技能描述嵌套一深就容易出错而且写注释不方便。SKILL.md允许你用自然语言描述规则同时用代码块嵌入示例AI 理解起来更顺。另一个原因是渐进式加载。Claude Code 这类工具不会一次性把所有 skills 都塞进上下文而是先扫描目录看到SKILL.md的元信息比如名称、描述、触发条件等任务匹配时才加载完整内容。这样既节省 token又避免无关技能干扰当前任务。如果你把所有规则写成一个巨大的配置文件每次对话都全量加载成本高且效果差。提示SKILL.md的文件名大小写敏感社区约定全大写但部分工具也接受skill.md。建议统一用大写避免跨平台同步时出问题。2.2 技能包的目录结构怎么设计才合理一个典型的 skill 目录长这样my-skill/ ├── SKILL.md ├── templates/ │ └── component.tsx.hbs ├── scripts/ │ └── validate.sh └── references/ └── style-guide.mdSKILL.md是入口里面会引用其他文件。templates放代码模板或文档骨架scripts放可执行脚本比如校验、格式化references放参考文档。这样拆分的好处是AI 在需要生成代码时读模板需要校验时调脚本需要查规范时看参考文档各取所需不会互相干扰。我见过有人把所有内容都塞进一个SKILL.md结果文件超过两千行AI 读取时反而抓不住重点。拆分的粒度建议控制在主文件不超过 300 行每个辅助文件不超过 500 行。超过这个量级考虑再拆一层目录。2.3 触发机制AI 怎么知道该用哪个 skill这是很多人困惑的地方。Claude Code 在启动时会扫描 skills 目录读取每个SKILL.md头部的元信息。常见的元信息字段包括字段作用是否必填name技能名称用于展示和调用是description一句话描述AI 据此判断是否匹配当前任务是triggers触发关键词或场景辅助匹配否version版本号便于管理否author作者信息否当你的提问里出现“生成 React 组件”“按团队规范写代码”这类表述时AI 会扫描已注册的 skills找到 description 或 triggers 匹配的那个然后加载完整内容。如果多个 skill 同时匹配优先级通常由目录顺序或显式声明的 priority 决定。注意description 写得越具体匹配越准。不要写“帮助写代码”要写“按 Airbnb 风格指南生成 React 函数组件使用 TypeScript 严格模式”。2.4 方案选型自己写还是用现成的社区里已经有不少开源的 skills 集合比如 typesafe ai skills、superpower skills 等。自己写还是直接用现成的取决于你的需求有多特殊。如果只是通用场景比如“生成符合 ESLint 标准的 JavaScript 代码”现成的 skill 改改就能用。但如果涉及公司内部规范、特定业务逻辑、私有工具链那就必须自己写。我的建议是先抄再改。找一个结构清晰的现成 skill把SKILL.md读一遍理解它的组织方式然后替换成自己的规则。这样比从零开始快得多也不容易漏掉关键字段。数学建模场景下有人把常用模型线性规划、灰色预测、时间序列的代码模板和参数说明做成 skills比赛时直接调用省去大量重复劳动。3. 核心细节解析与实操要点3.1SKILL.md的写法从结构到语气一个可用的SKILL.md通常包含以下几个部分--- name: react-component-generator description: 按团队规范生成 React 函数组件使用 TypeScript 严格模式和 CSS Modules triggers: - 生成组件 - React 组件 - 写一个组件 version: 1.0.0 --- # React 组件生成规范 ## 基本要求 - 必须使用函数组件禁止 class 组件 - 必须使用 TypeScript禁止 any 类型 - 样式使用 CSS Modules文件名格式为 ComponentName.module.css ## 文件结构 每个组件包含三个文件 1. index.tsx - 组件主体 2. index.module.css - 样式 3. types.ts - 类型定义 ## 代码模板 参考 templates/component.tsx.hbs ## 校验步骤 生成后运行 scripts/validate.sh 检查注意几个细节。第一frontmatter 里的 description 要包含关键词方便 AI 匹配。第二正文用祈使句直接说“必须”“禁止”不要用“建议”“可以考虑”AI 对确定性指令的执行更稳定。第三引用外部文件时写相对路径不要写绝对路径否则换台机器就失效。3.2 模板文件怎么写才能让 AI 正确填充模板文件不是简单的占位符替换。AI 需要理解哪些部分该改、哪些部分该保留。以 Handlebars 模板为例import React from react; import styles from ./{{componentName}}.module.css; import { {{componentName}}Props } from ./types; export const {{componentName}}: React.FC{{componentName}}Props ({ {{props}} }) { return ( div className{styles.container} {{content}} /div ); };AI 看到{{componentName}}就知道要替换成实际组件名看到{{content}}就知道要填充具体 JSX。关键是在SKILL.md里说明每个占位符的含义和示例否则 AI 可能猜错。比如{{componentName}}使用 PascalCase例如UserProfile、OrderList。3.3 脚本集成让 skill 具备“动手能力”纯文本的 skill 只能指导 AI 生成内容但如果配合脚本就能让 AI 执行校验、格式化、甚至调用外部 API。比如一个数学建模 skill 可以包含#!/bin/bash # scripts/validate-model.sh # 检查模型文件是否包含必要的注释和参数说明 MODEL_FILE$1 if ! grep -q ## 参数说明 $MODEL_FILE; then echo 错误缺少参数说明章节 exit 1 fi if ! grep -q ## 结果解读 $MODEL_FILE; then echo 错误缺少结果解读章节 exit 1 fi echo 校验通过在SKILL.md里写生成模型代码后运行bash scripts/validate-model.sh 文件名进行校验。如果校验失败根据提示补充缺失章节。这样 AI 就会在生成后主动调用脚本并根据输出决定是否修正。脚本的退出码很重要0 表示成功非 0 表示失败AI 据此判断下一步动作。3.4 多技能协作与优先级管理一个项目里往往需要多个 skills 配合。比如前端项目可能同时有“组件生成”“API 请求封装”“单元测试生成”三个 skill。当你说“写一个用户列表组件带请求和测试”时AI 需要依次调用三个 skill。管理优先级的方式有两种。一种是在SKILL.md里声明priority字段数值越大越优先。另一种是依靠目录命名比如01-component、02-api、03-testAI 按顺序加载。我更推荐第一种因为目录改名容易乱而 priority 字段显式且稳定。实操心得如果两个 skill 的触发词重叠严重AI 可能反复横跳。解决办法是在 description 里写清楚边界比如“仅用于生成组件文件不涉及 API 调用”。4. 实操过程与核心环节实现4.1 环境准备从零搭建 skills 目录假设你用的是 Claude Code默认 skills 目录通常在~/.claude/skills/下具体路径以官方文档为准。如果没有这个目录手动创建mkdir -p ~/.claude/skills cd ~/.claude/skills然后为每个 skill 建一个子目录mkdir react-component-generator cd react-component-generator touch SKILL.md mkdir templates scripts references目录建好后先写SKILL.md的 frontmatter再填充正文。不要一开始就写完整内容先写最小可用版本测试 AI 能否正确识别和调用再逐步补充细节。4.2 编写第一个 skill以“生成 API 请求函数”为例假设团队规范是所有 API 请求必须用 axios必须带错误处理和 loading 状态必须用 TypeScript 泛型定义返回类型。SKILL.md可以这样写--- name: api-request-generator description: 生成符合团队规范的 axios API 请求函数包含错误处理、loading 状态和 TypeScript 泛型 triggers: - API 请求 - 接口封装 - axios 函数 version: 1.0.0 --- # API 请求函数生成规范 ## 必须遵守 - 使用 axios 实例不要直接 import axios - 必须定义请求参数类型和返回数据类型 - 必须包含 try-catch 错误处理 - 必须管理 loading 状态通过回调或状态管理库 ## 文件命名 api/{{moduleName}}.ts例如 api/user.ts ## 代码模板 参考 templates/api-function.ts.hbs ## 示例 输入用户登录接口POST /api/login参数 username 和 password 输出api/auth.ts 中的 login 函数 ## 校验 生成后检查是否包含 try、catch、loading 关键字模板文件templates/api-function.ts.hbsimport { axiosInstance } from /utils/request; import type { {{returnType}} } from /types/{{moduleName}}; export interface {{functionName}}Params { {{paramFields}} } export async function {{functionName}}( params: {{functionName}}Params, setLoading?: (loading: boolean) void ): Promise{{returnType}} { setLoading?.(true); try { const { data } await axiosInstance.{{method}}{{returnType}}({{url}}, params); return data; } catch (error) { console.error({{functionName}} failed:, error); throw error; } finally { setLoading?.(false); } }写完后在 Claude Code 里输入“帮我写一个用户登录的 API 请求函数”观察它是否自动读取这个 skill 并按模板生成。如果没反应检查 description 里的关键词是否匹配或者手动在对话里提一句“用 api-request-generator 这个 skill”。4.3 调试与迭代怎么知道 skill 生效了最直接的验证方式是看 AI 的输出是否符合SKILL.md里的约束。比如你写了“必须用 CSS Modules”但 AI 生成了内联样式说明 skill 没被加载或者约束没写清楚。调试步骤检查SKILL.md的 frontmatter 格式是否正确---不能少。检查 description 是否包含用户可能说的关键词。在对话里显式点名“请使用 react-component-generator skill”。如果还是不行把SKILL.md内容直接粘贴到对话里看 AI 是否能理解。如果能理解说明是加载机制问题如果不能说明写法有问题。踩过的坑有一次我把triggers写成了trigger少了一个 s结果 AI 一直不匹配。这种拼写错误很隐蔽建议写完对照社区示例检查一遍。4.4 数学建模场景下的 skills 实战数学建模比赛时间紧、任务重skills 能帮上大忙。我见过一个队伍把常用模型封装成 skills包括线性规划 skill包含 scipy.optimize.linprog 的调用模板和结果解读规范灰色预测 skill包含 GM(1,1) 的 Python 实现和精度检验步骤时间序列 skill包含 ARIMA 参数选择流程和残差检验每个 skill 的SKILL.md里写清楚适用场景、输入数据格式、输出结果格式、注意事项。比赛时队员只需要说“用灰色预测处理这组数据”AI 就会按预设流程生成代码和解读。关键是提前测试比赛现场再调试就来不及了。5. 常见问题与排查技巧实录5.1 问题速查表问题现象可能原因解决方法AI 完全不读 skill目录路径不对确认 skills 目录位置检查是否在正确路径下AI 读了但没按规则执行约束写得太模糊改用祈使句增加具体示例多个 skill 冲突触发词重叠修改 description 明确边界或调整 priority模板占位符没替换占位符说明不清在 SKILL.md 里逐个说明占位符含义和示例脚本执行失败权限或路径问题检查脚本可执行权限用绝对路径或相对路径测试换机器后 skill 失效用了绝对路径全部改为相对路径或使用环境变量5.2 独家避坑技巧技巧一用“反例”强化约束。在SKILL.md里不仅写“必须怎样”还写“禁止怎样”。比如“禁止使用 any 类型如果无法确定类型使用 unknown 并添加类型守卫”。AI 对禁止性指令的执行往往更严格。技巧二版本化你的 skills。每次修改SKILL.md都更新 version 字段并在文件末尾加一个变更记录。这样出问题时能快速回滚也方便团队协作。技巧三定期清理不用的 skills。社区里有人推荐用 tibo 清理 skills 的方法核心思路是超过一个月没被触发的 skill要么删掉要么合并到其他 skill 里。太多 skill 会拖慢加载速度也增加 AI 匹配的负担。技巧四测试时用“最小输入”。不要用复杂任务测试新 skill先用一句话看 AI 是否触发。比如测试 API skill就说“写一个登录接口”看它是否按模板生成。触发没问题了再测试复杂场景。5.3 关于“claude code 怎么手动装 github 上的 skills”社区里经常有人问这个问题。基本流程是从 GitHub 仓库下载 skill 目录放到本地 skills 路径下然后重启 Claude Code 或重新加载配置。注意检查仓库的 README有些 skill 需要额外依赖比如 Python 包或 Node 模块需要提前安装。如果 skill 里包含脚本还要确认脚本的执行权限。注意从网络下载的 skill 要审查内容确保没有恶意脚本或不当指令。尤其是包含scripts/目录的 skill打开脚本看一眼再运行。5.4 Windows 环境下的特殊处理Windows 用户可能会遇到路径分隔符问题。SKILL.md里引用文件时用正斜杠/不要用反斜杠\因为正斜杠在 Windows 和 Unix 下都能识别。如果脚本是 bash 脚本Windows 下需要 Git Bash 或 WSL 才能运行。纯 Windows 环境建议用 PowerShell 脚本并在SKILL.md里注明“仅限 Windows PowerShell”。另外Windows 下 Claude Code 的安装路径可能不同skills 目录通常在%USERPROFILE%\.claude\skills\。如果找不到在 Claude Code 里输入/skills或查看帮助文档确认。6. 技能库的扩展与长期维护6.1 从个人使用到团队共享个人用的 skill 可以随意些但团队共享就需要考虑可维护性。建议做法把 skills 目录纳入 Git 版本控制每个 skill 有独立的 README说明用途、依赖、示例定期 review合并重复的 skill删除过时的新成员加入时clone 仓库到本地 skills 路径即可团队共享最大的问题是规范漂移。今天张三改了SKILL.md明天李四又改回去AI 的行为就不稳定。解决办法是修改SKILL.md必须走 PR至少一人 review 后才能合并。6.2 技能库的版本管理与回滚给每个 skill 打 tag比如react-component-generator1.0.0。当新版本导致 AI 输出异常时可以快速切回旧版本。Git 的 tag 功能足够用不需要额外工具。如果 skill 依赖外部模板或脚本这些文件也要一起版本化。不要只版本化SKILL.md否则回滚后模板对不上照样出问题。6.3 后续扩展方向skills 机制目前还在快速演进。我观察到几个方向值得关注一是技能组合多个 skill 可以串联成工作流比如“生成组件 → 生成测试 → 运行校验”一键完成二是动态技能根据项目类型自动加载不同的 skill 集合三是技能市场社区共享经过验证的 skill减少重复造轮子。如果你现在开始积累自己的 skills建议从最常用的场景入手先解决自己的痛点再考虑分享。我自己的技能库从三个 skill 起步现在扩展到十几个覆盖了日常开发的大部分重复劳动。每次看到 AI 按我写的规则自动干活都觉得前期投入的时间值了。最后分享一个小技巧在SKILL.md末尾加一个“更新日志”章节记录每次修改的原因和效果。过几个月回头看你会感谢自己当初写了这些备注。