1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词被单独拎出来当项目标题我其实愣了一下。这词太泛了泛到像在搜索引擎里敲工具两个字。但结合后面跟着的一串热词——Claude、Agent Skills、SKILL.md、Claude Code——方向就清楚了这里说的 skills指的是围绕 Claude 这类 AI 编程助手构建的可复用能力模块也就是让 AI 从什么都能聊两句变成在某个具体任务上真能干活的那套东西。打个比方。裸的 Claude 像一个刚招进来的聪明应届生逻辑好、反应快、知识面广但你让他直接上手改你们公司的项目他连代码规范、目录结构、部署流程都不知道得你一句一句喂上下文。而 skills 就是给这个应届生配的一本《岗位操作手册》遇到什么任务、按什么步骤走、调用哪些工具、输出什么格式全写清楚了。他照着手册干第一次就能干得像模像样。所以这篇内容我想聊的不是skills 是什么概念这种虚的而是实打实的几件事skills 的目录结构和 SKILL.md 到底怎么写、怎么从 GitHub 上把别人写好的 skills 装到本地、装完之后怎么验证它真的生效了、以及在实际项目里怎么攒出自己的一套技能库。适合两类人看——一类是刚接触 Claude Code、还在纠结命令行怎么敲的新手另一类是已经用了一阵子、觉得每次都要重复交代背景很烦、想把这部分沉淀下来的老用户。我自己的经历是这样的最开始用 Claude Code 的时候每次开新会话都要重新说一遍我们这个项目用 pnpm 不用 npm组件都放 src/components 下面提交信息用中文。说了大概两周烦了才开始认真研究 skills。研究完发现这东西的价值远不止省几句话——它本质上是把你的工程经验变成了 AI 能稳定复现的资产。这个认知转变是我写这篇东西的最大动机。2. SKILL.md 的骨架一个 skill 到底由哪些部分组成2.1 目录结构为什么是一个文件夹 一个入口文件先看最基础的问题一个 skill 在磁盘上长什么样。绝大多数实现遵循的是同一套约定——一个 skill 就是一个独立文件夹文件夹里必须有一个 SKILL.md 作为入口其余文件按需添加。my-skill/ ├── SKILL.md # 必需入口和元信息 ├── scripts/ # 可选放可执行脚本 │ └── build.sh ├── references/ # 可选放参考资料 │ └── api-spec.md └── assets/ # 可选放模板、配置等静态资源 └── template.json为什么设计成文件夹而不是单个文件我琢磨过这个问题答案其实很务实一个真正有用的 skill往往不止一段提示词。它可能需要附带一个脚本让 AI 去执行、需要一份 API 文档让 AI 查阅、需要一个模板文件让 AI 填充。如果全塞进一个 md 文件里会又臭又长AI 读起来也费劲。拆成文件夹之后SKILL.md 只负责说明这是什么、什么时候用、怎么用具体资源按需加载结构清晰维护起来也方便。这里有个容易踩的坑文件夹名字和 SKILL.md 里声明的 name 最好保持一致。我见过有人文件夹叫my-awesome-skill里面 name 写code-helper结果某些工具在索引的时候对不上skill 死活加载不出来。排查了半天才发现是命名不一致。所以我的习惯是建文件夹的时候就把名字定死后面不再改。2.2 SKILL.md 的头部name 和 description 是命门SKILL.md 用的是 Markdown 加 YAML frontmatter 的格式开头那段被---包起来的就是元信息。看起来简单但这两个字段直接决定了 skill 能不能被正确触发。--- name: react-component-generator description: 当用户需要创建新的 React 函数组件时使用。生成符合项目规范的组件文件包含 TypeScript 类型定义、样式文件和单元测试骨架。适用于 src/components 目录下的组件开发。 --- # React 组件生成器 ## 使用场景 ...name的规则很直白小写字母、数字、连字符别用空格和特殊符号。这个没什么好说的照着来就行。真正需要花心思的是description。它不是给你看的是给 AI 看的——AI 在决定要不要调用这个 skill的时候主要就是读这段描述。所以描述写得好不好直接决定 skill 是每次都能精准触发还是该用的时候不用、不该用的时候乱用。我总结了一个写 description 的公式实测下来触发准确率明显提升触发条件 具体动作 适用范围 边界说明拿上面那个例子拆解当用户需要创建新的 React 函数组件时是触发条件生成符合项目规范的组件文件包含 TypeScript 类型定义、样式文件和单元测试骨架是具体动作适用于 src/components 目录下的组件开发是适用范围。如果这个 skill 不该处理类组件那就再加一句不适用于 class 组件作为边界。反面教材我也见过不少比如 description 写成帮助处理 React 相关任务。这种描述太宽泛AI 看到任何跟 React 沾边的问题都可能去调它结果就是该调的时候调了、不该调的时候也调了反而添乱。描述越具体触发越精准这是我在几十个 skill 上反复验证过的结论。2.3 正文部分把怎么做拆成 AI 能执行的步骤frontmatter 下面是正文也就是 skill 的操作手册本体。这部分没有强制格式但写得好不好直接决定 AI 执行的质量。我的经验是正文要遵循一个原则假设 AI 对这个任务一无所知把每一步都写清楚但不要写废话。一个结构比较完整的正文通常包含这几块使用场景什么情况下该用这个 skill给几个具体例子前置条件执行前需要确认什么比如依赖是否安装、文件是否存在执行步骤一步一步的操作每步说清楚输入和输出输出格式最终产物长什么样最好给个示例注意事项容易出错的地方、需要人工确认的环节我拿一个真实在用的 skill 举例。我们团队有个规范所有新页面的路由都要在src/router/index.ts里注册并且要同步更新权限配置。这个规则新人经常忘我就写了个 skill## 执行步骤 1. 在 src/pages 下创建页面组件文件命名遵循 PascalCase 2. 打开 src/router/index.ts在 routes 数组中添加新路由对象 3. 路由对象的 meta 字段必须包含 title 和 permission 两个属性 4. 打开 src/config/permissions.ts在对应角色下添加新路由的权限标识 5. 运行 pnpm lint 检查是否有格式问题 ## 注意事项 - 路由的 path 必须以 / 开头且不能与已有路由重复 - permission 标识的命名规则是 模块名:页面名:动作比如 user:list:view - 如果页面需要登录才能访问meta 里要加 requiresAuth: true你看这种写法 AI 照着做基本不会错。关键在于把隐性知识显性化——那些老员工觉得这不是常识吗的东西恰恰是新人包括 AI最容易漏的。写 skill 的过程其实也是逼自己把团队里那些口口相传的规矩整理成文字的过程一举两得。3. 从 GitHub 装 skills手动安装的完整链路3.1 为什么很多人卡在装不上这一步热词里有一堆关于安装的问题——claude code怎么手动装github上的skills安装claude codeclaude code安装教程。这说明什么说明安装环节是新手最大的拦路虎。我自己第一次装的时候也折腾了快一个小时踩的坑现在想想都好笑。先说清楚一个前提skills 的安装方式取决于你用的是哪种客户端。目前主流的有几类——命令行工具、桌面应用、编辑器插件。不同客户端的 skills 存放路径不一样这是第一个容易搞混的点。下面我按手动安装这条最通用、最不依赖具体客户端的路径来讲因为搞懂了手动安装其他方式都是它的变体。手动安装的本质就一句话把 skill 文件夹放到客户端会去扫描的目录里。所以核心问题是两个——放哪个目录、怎么放进去。3.2 找到正确的 skills 目录不同平台的默认目录不一样我整理了一张表覆盖常见的几种情况平台/客户端默认 skills 目录macOS / Linux 命令行~/.claude/skills/Windows 命令行%USERPROFILE%\.claude\skills\项目级随项目走项目根目录下的.claude/skills/桌面应用设置里通常能看到skills 目录的路径这里有个关键区分用户级目录 vs 项目级目录。用户级的 skill 对你所有项目都生效适合放那些通用的、跟具体项目无关的能力比如生成规范的 Git 提交信息。项目级的 skill 只在这个项目里生效适合放项目特有的规范比如我们这个项目的组件必须怎么写。我一般把通用的放用户级项目相关的放项目级这样换项目的时候不会互相干扰。提示如果你不确定自己的客户端用的是哪个目录最笨但最有效的办法是——先在客户端里创建一个最简单的 skill很多客户端有新建 skill的入口然后去文件系统里搜这个文件名搜到的位置就是正确目录。3.3 从 GitHub 拉取并放置的完整步骤假设你在 GitHub 上看到一个心仪的 skill 仓库想装到本地。完整流程是这样的第一步确认仓库结构。打开仓库看根目录下是不是直接有SKILL.md。有两种常见情况一种是仓库根目录就是 skill 本体SKILL.md在最外层另一种是仓库里有个skills/文件夹里面装着多个 skill。这两种情况的处理方式不同先看清楚再动手。第二步克隆或下载。用 git 克隆最省事git clone https://github.com/xxx/yyy-skill.git如果没装 git或者只是想快速试一下直接在仓库页面点Download ZIP解压也行。我一般推荐 git clone因为后续仓库更新了git pull一下就能同步比重新下载省事。第三步把 skill 文件夹放到目标目录。注意这里有个细节要放的是包含 SKILL.md 的那个文件夹本身而不是它的内容。比如你克隆下来是yyy-skill/里面是SKILL.md和scripts/那你要把整个yyy-skill文件夹复制到 skills 目录下最终形成~/.claude/skills/yyy-skill/SKILL.md这样的结构。我见过有人把SKILL.md直接拷到 skills 目录根下结果加载不出来——因为客户端是按子文件夹来识别 skill 的。# 假设克隆下来的文件夹叫 yyy-skill cp -r yyy-skill ~/.claude/skills/Windows 上用资源管理器复制粘贴也行路径换成%USERPROFILE%\.claude\skills\。第四步重启或刷新客户端。大部分客户端不会实时扫描目录变化需要重启一下或者在设置里手动触发一次重新加载 skills。这一步经常被忽略导致明明放进去了却没生效。3.4 装完之后的验证怎么确认 skill 真的生效了装完不验证等于没装。我的验证流程分三步第一看客户端有没有识别到。大多数客户端在 skills 管理界面会列出已加载的 skill能看到名字和描述。如果列表里没有说明目录放错了或者格式有问题。第二做一次触发测试。构造一个明显应该触发这个 skill 的请求看 AI 会不会去调用它。比如装了个生成 React 组件的 skill就直接说帮我创建一个 UserProfile 组件观察 AI 的反应。如果它开始按 skill 里定义的步骤走说明生效了。第三检查输出是否符合预期。有时候 skill 触发了但输出不对——可能是 SKILL.md 里的步骤写得有歧义或者引用的脚本路径不对。这时候要回去改 SKILL.md而不是怀疑安装有问题。我踩过的一个坑是skill 里引用了一个scripts/build.sh但我复制的时候只复制了SKILL.md脚本没带过去结果 AI 执行到那一步就卡住了。所以复制的时候一定要整个文件夹一起复制别偷懒只拿入口文件。4. 自己动手写一个 skill从需求到落地4.1 先想清楚哪些事值得做成 skill不是所有事都值得写成 skill。我一开始热情高涨恨不得把每个操作都做成 skill结果攒了二十多个真正高频使用的不到五个。后来我总结了一个判断标准这件事是不是重复发生 有固定套路 容易出错。三个条件同时满足才值得做成 skill。举几个我实际做成 skill 的例子生成符合团队规范的 Git 提交信息每天都要提交格式有固定要求类型前缀、中文描述、关联 issue 号新人经常写错。完美符合三个条件。新建页面时的路由和权限注册前面提过步骤固定、容易漏。把设计稿的字段映射成 TypeScript 接口有固定的命名转换规则手写容易出错。反过来那些一次性的、每次都不一样的任务就不适合做成 skill。比如帮我重构这个函数——每次重构的目标和约束都不同写成 skill 反而束手束脚。4.2 写 SKILL.md 的实操一个完整例子我拿生成 Git 提交信息这个 skill 从头写一遍你能看到每个部分是怎么落地的。--- name: git-commit-message description: 当用户需要为当前改动生成 Git 提交信息时使用。读取暂存区的改动内容按照团队规范生成中文提交信息格式为类型(范围): 描述。适用于任何需要提交代码的场景。 --- # Git 提交信息生成器 ## 使用场景 用户说帮我写个提交信息生成 commit message提交一下等类似表达时触发。 ## 执行步骤 1. 运行 git diff --staged 查看暂存区的改动 2. 如果暂存区为空提示用户先执行 git add 3. 分析改动内容判断改动类型 - feat: 新功能 - fix: 修复 bug - refactor: 重构不改变外部行为 - docs: 文档变更 - style: 格式调整不影响逻辑 - chore: 构建、依赖等杂项 4. 生成提交信息格式为 类型(范围): 简短描述 5. 描述用中文不超过 50 个字动词开头 ## 输出格式 feat(user): 新增用户列表分页功能 fix(api): 修复登录接口超时未重试的问题 ## 注意事项 - 范围用改动最集中的模块名不确定时留空 - 一次提交只做一件事如果改动混杂提醒用户拆分 - 不要生成更新代码修改文件这类无信息量的描述写完这个我实际用了一周发现两个问题一是 AI 有时候会自作主张把git add也执行了二是遇到大改动时描述容易超长。于是我在注意事项里补了两条明确禁止自动执行git add以及描述超长时优先保留核心动作。skill 不是一次写完就完事的要在使用中不断打磨这点后面还会展开说。4.3 让 skill 更可靠的几个技巧写了十几个 skill 之后我攒了一些让它们更听话的经验都是踩坑换来的技巧一步骤要可执行不要写理解需求这种虚的。AI 不需要你教它理解它需要的是明确的动作指令。分析改动内容比理解用户意图有用得多。技巧二给判断标准不给模糊描述。比如判断改动类型与其说根据改动性质判断不如把每种类型对应的典型场景列出来。AI 有了对照表判断准确率会高很多。技巧三把容易出错的边界情况写进注意事项。这是 skill 价值最高的部分。那些正常情况下不会错、但偶尔会翻车的场景提前写清楚能省掉大量返工。技巧四能用脚本的别用自然语言。如果某个步骤是确定性的比如格式化、文件重命名写个脚本放scripts/里让 AI 去调用比让它按规则处理可靠得多。自然语言描述总有歧义脚本没有。技巧五控制 skill 的粒度。一个 skill 只干一件事。我见过有人写了个全能前端助手skill里面塞了组件生成、路由配置、样式规范、测试编写一大堆结果 AI 每次触发都要读一大堆无关内容反而容易出错。拆成多个小 skill各管一摊触发更精准。5. 不同场景下的 skills 实践从数学建模到内容创作5.1 数学建模场景把建模流程沉淀成 skill热词里出现了数学建模skills推荐华为杯建模比赛好用的codex skills说明这个场景需求很实在。数学建模比赛的特点是时间紧、任务重、流程相对固定——读题、选模型、写代码、跑结果、写论文。这套流程完全可以沉淀成 skill。我帮参加建模的朋友整理过一套核心是把常见模型的代码模板和论文写作规范做成 skill。比如一个灰色预测模型的 skill里面写清楚什么数据特征适合用这个模型、代码怎么调、结果怎么解读、论文里这段该怎么写。比赛的时候直接触发省掉大量查资料和试错的时间。这里的关键是把选型判断也写进去。光给代码没用得告诉 AI和用 AI 的人什么情况下该用这个模型。比如数据量少于 10 个、呈递增趋势、无明显周期性波动时优先考虑灰色预测。这种判断规则才是 skill 里最值钱的部分。5.2 内容创作场景AI 漫剧和文案的 skill 化ai漫剧常用skills这个热词让我挺意外的但细想很合理。漫剧这类内容创作有很强的套路性——分镜怎么切、台词什么节奏、画面描述写到什么颗粒度都是有规律的。把这些规律写成 skillAI 生成的内容就能保持风格一致。我试过给一个做短视频脚本的朋友写 skill核心是把爆款开头的几种模式固化下来悬念式、冲突式、反常识式每种给几个模板和适用场景。AI 拿到 skill 之后生成的开头质量明显比裸用好。内容创作类 skill 的秘诀是给范例——与其描述要写得吸引人不如直接给三个吸引人的例子让 AI 照着感觉走。5.3 前端开发场景规范类 skill 是刚需前端开发skills这个热词指向很明确。前端项目的规范特别多——命名、目录结构、组件写法、状态管理、样式方案每一条都能写成一个 skill。而且前端项目迭代快规范经常变skill 的好处是改一处、全局生效比口头传达或者写文档靠谱多了。我的做法是建一个项目规范skill 集合每个规范一个文件。新人入职把 skills 目录一同步AI 就自动按团队规范干活了。这比让新人读几十页文档高效得多——文档没人看但 AI 会老老实实按 skill 执行。6. 维护与迭代skill 库不是建完就完事6.1 定期清理删掉那些僵尸 skillskill 库跟代码库一样会随着时间积累垃圾。我每隔一两个月会做一次清理标准很简单过去一个月没被触发过的考虑删掉或合并。有些 skill 是当时为了解决某个临时问题写的问题解决了skill 就成了负担——它会占用 AI 的注意力增加误触发的概率。清理的时候我会问自己三个问题这个 skill 最近用过吗它的功能能不能被别的 skill 覆盖它的规则还符合当前的项目现状吗三个问题有一个答否就动手处理。热词里有个tibo关于清理skills的方法推荐说明清理这件事确实是个普遍痛点大家都攒了一堆用不上的。6.2 版本管理把 skill 当代码管skill 是要改的改了就要有记录。我的做法是把用户级的 skills 目录整个用 git 管起来每次修改都提交写清楚改了什么、为什么改。这样万一改坏了能快速回滚多个设备之间也能同步。项目级的 skill 直接跟着项目仓库走放在.claude/skills/下面跟代码一起提交。好处是团队共享——一个人写好了其他人拉下来就能用规范自然统一。6.3 从能用到好用持续打磨的心态最后说点心态上的东西。我见过很多人装了一堆 skill用两次觉得也就那样就放弃了。问题往往不在 skill 本身而在于没有根据自己的实际使用情况去调整。别人的 skill 是别人的经验搬到你这儿未必完全适用。我的习惯是每次 skill 触发后如果结果不理想就顺手记一笔是触发时机不对还是步骤有歧义还是输出格式不满意。攒几条之后统一改一次 SKILL.md。改完再用再看效果。这么迭代几轮skill 才会真正变成你的skill而不是从网上抄来的一个文件。说到底skills 这套机制的价值不在于它能让 AI 多干多少活而在于它逼着你把脑子里那些只可意会的经验整理成可以言传的规则。这个过程本身就是对你自己工作方法的一次梳理。我写完第一批 skill 之后最大的感受是原来我平时做事的很多步骤自己都没意识到是有套路的。把它们写下来不光 AI 受益我自己也更清楚了。