1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词作为项目标题大部分人的反应是懵的——这词太泛了。技能技巧能力放在技术语境里它其实指向一个非常具体的东西Agent Skills也就是围绕 Claude 这类 AI 编程助手构建的、以SKILL.md为核心载体的可复用能力模块。我接触这套东西的起点很偶然。当时在做一个前端项目反复让 AI 帮我处理同一类组件重构任务每次都要重新描述规范、重新贴上下文烦得不行。后来发现社区里已经有人在用SKILL.md把这类重复性指令固化下来一次写好后续直接调用。这就是 skills 最朴素的价值——把你每次都要跟 AI 说的话变成AI 自己知道该怎么做的事。所以这篇内容适合谁看三类人一是刚接触 Claude Code、还在手动重复粘贴 prompt 的新手二是想把自己团队的工作流沉淀成可复用资产的开发者三是好奇AI skills 到底怎么写、想动手做一个自己 skill 的实践派。我不打算把它写成一份官方文档的复述而是把我自己从零摸索、踩坑、跑通、再到规模化使用的完整路径摊开讲。需要先明确一个认知skills 不是插件不是 API也不是某种神秘的黑科技。它本质上是一份结构化的指令文档放在约定好的目录里AI 在合适的时机读取它、理解它、执行它。理解这一点后面所有的操作都会变得顺理成章。2. SKILL.md 的解剖一份 skill 到底由什么构成2.1 文件结构的最小可用集一个能跑起来的 skill核心就是一个SKILL.md文件。但能跑和好用之间差着十万八千里。我先给你一个最小骨架再逐层加东西。--- name: frontend-component-refactor description: 当用户要求重构 React 组件时使用统一代码风格与目录结构 --- # 前端组件重构 ## 何时使用 当任务涉及 React 函数组件的拆分、命名规范调整、props 类型补全时触发。 ## 执行步骤 1. 读取目标组件文件识别当前结构问题 2. 按团队规范重命名变量与文件 3. 补全 TypeScript 类型定义 4. 输出改动清单上面这段里---包裹的部分叫frontmatter是元数据区。name是 skill 的唯一标识description是触发条件的自然语言描述——这一行极其关键AI 判断要不要用这个 skill几乎全靠它。很多人 skill 写了半天不生效问题就出在 description 写得太含糊。2.2 description 为什么是成败关键我踩过的第一个大坑就在这里。最初我写的 description 是用于前端开发结果 AI 几乎从不主动调用它因为前端开发这个范围太宽AI 无法判断当前任务是否匹配。后来改成当用户要求重构 React 函数组件、调整组件目录结构或补全 props 类型时使用命中率立刻上来了。这里的逻辑其实和搜索引擎的关键词匹配类似description 是给 AI 看的索引它需要包含具体的触发场景词。你可以这样自查——把你希望触发 skill 的几种典型用户请求写下来看看 description 里有没有覆盖这些请求里的核心动词和名词。如果没有补上。提示description 建议控制在 1-2 句话既要具体又不能太窄。太窄会导致该触发时不触发太宽会导致不该触发时乱触发。2.3 正文部分该写什么、不该写什么正文是 skill 的操作手册。我的经验是遵循一个原则写判断逻辑和决策依据而不是写死步骤。因为 AI 的执行环境千变万化你把步骤写死遇到边界情况它就卡住了。举个例子。写第 3 步把变量名改成驼峰式是死步骤写命名遵循团队 ESLint 配置若配置缺失则默认使用驼峰式常量全大写就是判断逻辑。后者在遇到不同项目时都能自适应。正文里我通常会包含这几块触发场景的细化说明、执行时需要读取哪些上下文文件、关键决策点的判断规则、输出格式要求、以及常见边界情况的处理方式。最后这块最容易被忽略但恰恰是区分玩具 skill和生产 skill的分水岭。2.4 一个真实可用的完整示例把上面的要素拼起来给你看一个我实际在用的、处理数学建模类任务的 skill 骨架数学建模是 skills 社区里非常活跃的应用方向--- name: modeling-paper-structure description: 当用户需要撰写或检查数学建模竞赛论文结构时使用 --- # 数学建模论文结构规范 ## 触发条件 用户提到建模论文竞赛论文结构摘要怎么写等。 ## 上下文读取 - 优先读取项目根目录下的 problem.md题目描述 - 读取已有的 results/ 目录了解已完成的分析 ## 结构规范 1. 摘要问题重述 方法概述 关键结果 结论控制在 500 字内 2. 问题分析明确每个子问题的输入输出 3. 模型假设逐条列出每条附合理性说明 4. 模型建立与求解公式 算法 结果 5. 灵敏度分析至少对 2 个关键参数做扰动 ## 边界处理 - 若题目含多个子问题每个子问题独立成章 - 若缺少数据明确标注假设来源而非编造这份 skill 的价值在于它把一篇合格建模论文该有什么这个隐性知识显性化了。团队里新人拿到它产出质量的下限立刻被拉高。3. 安装与目录skill 放在哪里才会被认出来3.1 目录约定的两种模式skill 能不能被识别位置比内容还重要。目前主流的约定有两种全局目录和项目目录。全局目录通常放在用户主目录下的配置文件夹里比如~/.claude/skills/这类路径放进去的 skill 对所有项目生效。项目目录则是放在项目根目录下的特定文件夹只对当前项目生效。我的建议是通用型 skill 放全局项目专属 skill 放项目内。比如代码注释规范这种放全局本项目的 API 命名约定就放项目里。这里有个容易踩的坑不同工具、不同版本对目录名的要求可能不一样。有的认skills有的认.skills有的要求放在特定子目录下。最稳妥的做法是先查你当前所用工具的官方说明确认目录名再往里放文件。我见过太多人把文件放错位置然后抱怨skill 不生效排查半天发现是路径问题。3.2 手动安装 GitHub 上的 skill社区里已经积累了大量开源 skill从 GitHub 上拿现成的用是最快的入门方式。手动安装的流程大致是这样找到目标 skill 仓库确认它的目录结构通常根目录或某个子目录下会有SKILL.md把整个 skill 文件夹复制到你本地的 skills 目录下确认文件夹名和SKILL.md里的name字段一致不一致有时会导致识别异常重启或重新加载你的 AI 工具让它重新扫描 skills 目录第 3 步是我强烈建议做的检查。有些仓库的文件夹名和内部 name 对不上虽然多数工具能容错但统一之后能省掉很多莫名其妙的调试时间。3.3 验证 skill 是否被正确加载装完之后别急着用先验证。验证方法因工具而异但核心思路一致让 AI 列出它当前可用的 skills。如果它能报出你刚装的 skill 名字说明加载成功如果报不出来就是路径或格式问题。我常用的排查顺序是这样的现象可能原因排查动作skill 完全不被识别目录路径错误确认 skills 目录的准确位置识别了但不触发description 太模糊重写 description加入具体场景词触发但执行不对正文逻辑有歧义检查步骤描述是否过于死板时好时坏多个 skill 冲突检查是否有 description 重叠的 skill这张表基本覆盖了我遇到过的 90% 的问题。尤其是最后一行时好时坏很多人以为是玄学其实是两个 skill 的触发条件重叠了AI 在两者之间摇摆。4. 写一个自己的 skill从需求到落地的完整链路4.1 先想清楚这个 skill 解决什么重复劳动写 skill 之前我建议你先做一件事回顾过去一周你让 AI 重复做过哪些事。凡是出现三次以上的同类请求就值得沉淀成 skill。这个判断标准很实用因为重复三次意味着它足够高频同时你已经对好的输出长什么样有了清晰认知。反过来说一次性任务、探索性任务、需要大量人工判断的任务都不适合做成 skill。skill 的甜区是流程相对固定、但每次都要重新交代背景的工作。比如按团队规范生成 commit message把设计稿描述转成组件代码骨架检查论文格式这类。4.2 把隐性知识显性化的技巧写 skill 最难的部分是把你自己下意识就会做的事情拆解成明确规则。这里有个技巧假装你在教一个完全不懂这个领域的人。你会怎么跟他解释先做什么、看到什么情况怎么判断、遇到异常怎么办我写第一个 skill 时卡在怎么描述判断逻辑上。后来我换了个方法先录一段自己实际操作的屏幕然后回放把每一步的决策点记下来。比如看到变量名是缩写就展开看到函数超过 50 行就拆分——这些就是判断规则。把它们写进 skillAI 就有了可执行的依据。4.3 迭代第一版永远不够好别指望一次写完美。我的每个 skill 都至少迭代过三版。第一版通常太啰嗦把很多 AI 本来就知道的常识也写进去了第二版精简掉冗余但可能删过头导致边界情况处理不了第三版才找到平衡。迭代的信号很明确如果 AI 执行时经常需要你补充说明说明 skill 写少了如果 AI 执行时经常做出你不需要的动作说明 skill 写多了或写偏了。根据这两个信号调整比盲目改有效得多。4.4 版本管理skill 也是代码这一点很多人忽略。skill 文件应该纳入版本管理和你的代码一起提交。原因很简单skill 会随团队规范变化而变化你需要知道什么时候改了什么、为什么改。我见过团队因为 skill 没有版本管理某次改动导致所有人的输出格式突然变了排查了半天才发现是有人改了共享 skill。建议给 skill 目录单独建一个仓库或者至少放在主仓库里用清晰的 commit message 管理。改动 skill 时commit message 写清楚改了什么规则、为什么改未来回看时能省大量时间。5. 实战场景skills 在不同领域的落地方式5.1 前端开发组件规范与代码审查前端是 skills 应用最成熟的领域之一。原因很直接前端有大量约定俗成的规范命名、目录结构、状态管理方式这些规范天然适合写成 skill。我自己的前端 skill 组合里最常用的是两个一个是组件重构一个是代码审查。组件重构那个负责把散乱的组件按规范整理代码审查那个负责在提交前扫一遍常见问题未使用的 import、缺失的 key、硬编码的颜色值等。两个 skill 配合使用基本覆盖了日常开发的大部分重复性检查工作。这里有个经验前端 skill 一定要和你的 ESLint、Prettier 配置联动。skill 里不要重复定义规则而是写遵循项目根目录的 ESLint 配置这样配置变了 skill 不用改。5.2 数学建模从选题到论文的全流程辅助数学建模是 skills 社区里热度很高的方向因为它流程长、环节多、每个环节都有明确的产出要求。我帮几个参赛队伍搭过 skill 组合效果比较明显。典型的组合包括选题分析 skill读取题目列出可能的建模方向、数据处理 skill统一数据清洗和特征工程流程、论文结构 skill前面展示过、以及图表规范 skill统一图表风格和标注方式。这套组合下来队伍能把精力集中在真正的建模思路上而不是反复纠结格式和流程。注意建模类 skill 要特别强调不编造数据和标注假设来源。我在 skill 里会明确写若数据缺失输出假设并标注禁止虚构数值这条规则救过好几次场。5.3 内容创作AI 漫剧与脚本生成AI 漫剧是最近兴起的方向skills 在这里的作用是统一叙事节奏和角色设定。一个漫剧项目往往有几十上百个分镜如果每个分镜都重新描述角色性格和画风效率极低。我的做法是写一个角色设定skill把主要角色的外貌、性格、说话方式固化下来再写一个分镜脚本skill规定每个分镜的时长、镜头语言、对白格式。生成时两个 skill 一起用产出的脚本一致性明显提升。5.4 跨领域通用把 skill 当团队规范容器跳出具体领域skills 还有一个被低估的用法作为团队规范的统一入口。新成员入职时不用读一堆文档直接看 skills 目录就知道这个团队怎么做事的。每个 skill 就是一条被显性化的团队约定。这个用法对远程协作团队尤其有价值。规范写在文档里没人看但写进 skill 里AI 每次执行都会遵守相当于强制落地。6. 那些没人告诉你但一定会踩的坑6.1 skill 冲突两个 skill 抢同一个任务这是最常见的坑。当你装了多个功能相近的 skillAI 在触发时会犹豫表现就是有时用 A 有时用 B结果不稳定。解决办法是定期审查 skills 目录合并或删除功能重叠的 skill。我现在保持 skills 数量在 10 个以内每个都有清晰的边界冲突基本消失。6.2 过度依赖skill 不是万能药我见过有人试图把整个开发流程塞进一个 skill结果这个 skill 又长又难维护AI 执行时还经常跑偏。记住skill 应该小而专。一个 skill 解决一类问题多个 skill 组合解决复杂问题。贪大求全只会让 skill 变成没人敢改的祖传代码。6.3 环境差异换台机器就失效skill 依赖目录路径而不同机器的路径可能不同。如果你在多台设备上工作建议把 skills 目录纳入同步方案或者用软链接指向统一位置。我自己的做法是把 skills 放在一个同步文件夹里各台机器通过软链接接入改一处处处生效。6.4 更新滞后规范变了 skill 没变团队规范更新了但 skill 没跟着改AI 就会按旧规范执行产出和团队要求脱节。这个坑的解法是把 skill 更新纳入规范变更流程——每次改规范时同步检查有没有相关 skill 需要更新。听起来麻烦但比事后返工划算得多。6.5 描述语言中英文混用的隐患description 用中文还是英文我的经验是跟随你日常和 AI 交流的语言。如果你平时用中文提需求description 就用中文如果混用那 description 最好中英关键词都覆盖。因为触发匹配是基于语义的语言不一致会降低命中率。7. 让 skills 真正提升效率的几个进阶思路7.1 组合调用skill 链式使用单个 skill 能力有限但多个 skill 可以形成流水线。比如读取需求 → 生成代码骨架 → 代码审查 → 生成 commit message这是四个 skill 串起来的工作流。关键是要让每个 skill 的输出格式和下一个 skill 的输入格式对齐这样链条才能顺畅。7.2 参数化让一个 skill 适配多种场景skill 正文里可以用占位符或条件分支来适配不同场景。比如一个生成测试的 skill可以写成若目标语言是 Python 用 pytest若是 JavaScript 用 Jest。这样不用为每种语言写一个 skill维护成本大幅降低。7.3 反馈闭环从使用中反哺 skill每次 skill 执行不理想时别只是手动纠正而是把纠正的内容回写到 skill 里。这样 skill 会越用越准。我有个习惯每周花十分钟回顾这周 skill 的翻车时刻把共性问题补进 skill。坚持几个月后我的 skill 命中率和准确率都有明显提升。7.4 分享与复用别重复造轮子社区里已经有大量优质 skill从 GitHub 上找现成的改比从零写快得多。我通常的做法是先搜有没有现成的有就拿来改没有才自己写。改的时候注意保留原作者的说明同时把自己的定制部分单独标注方便未来同步上游更新。8. 我个人的一点使用体会摸索 skills 这套东西大半年最大的感受是它的门槛不在技术而在想清楚。写 skill 的过程本质上是在逼你把模糊的经验变成清晰的规则。这个过程本身就很有价值——很多时候我写着写着才发现自己原来做事的方式里有那么多没意识到的假设。另一个体会是别追求一步到位。我最早的几个 skill 现在回看简直惨不忍睹但正是那些粗糙的版本让我理解了 skill 该怎么写。所以如果你刚开始别纠结写得好不好先写出来用起来在用的过程中迭代。skill 这东西用起来才有价值放在文件夹里吃灰的 skill 写得再漂亮也没意义。最后分享一个小技巧给你的每个 skill 在文件顶部加一行注释写清楚最后更新日期和本次改动原因。这个习惯在 skill 多起来之后能救命尤其是当你几个月后回头看某个 skill想不起来当初为什么那么写的时候。