1. 从“装完就吃灰”说起Skill 到底解决了什么问题我大概是在 Claude Code 刚火起来那阵子开始重度使用的。最开始的两周我的用法和大多数人一样打开终端敲claude然后一句一句地跟它聊需求让它帮我改代码、写脚本、查报错。用着用着就发现一个很尴尬的事——每次开新会话我都得重新交代一遍背景这个项目用什么框架、目录结构长什么样、代码风格有什么约定、提交信息怎么写、测试怎么跑。说一遍两遍还行说到第十遍的时候人是真的会烦。后来我接触到了 Skill 这个概念也就是SKILL.md那一套东西。一开始我没太当回事觉得不就是把提示词存成文件嘛能有多大差别。直到我陆陆续续给自己的环境里塞了差不多四十个 Skill覆盖了前端规范、后端接口约定、文档写作、数据处理、代码审查、提交规范这些场景之后我才真正意识到之前那些用法基本等于白用。因为 Skill 改变的不是“我问什么”而是“它默认知道什么”。这篇文章我想聊的就是这件事。Skill 是什么、SKILL.md里的 frontmatter 怎么写、子 agent 和主 agent 怎么配合、四十个 Skill 我是怎么分类管理的、哪些 Skill 是真有用哪些是凑数的、以及踩过的那些坑。适合已经用过 Claude Code 但还停留在“纯聊天”阶段的人也适合刚开始接触 agent skill、想搞清楚 skill 和 agent 区别的读者。不需要你有多深的编程背景我会尽量用生活化的方式讲清楚。先说结论性的判断Skill 的本质是把重复的上下文固化成可复用的能力单元。它不是插件不是脚本也不是传统意义上的工具函数而是一份“给模型看的说明书”。你写得越清楚它执行得越稳。四十个 Skill 装下来我最大的感受不是“功能变多了”而是“我终于不用每次重新教它做事了”。2. Skill 的核心机制拆解SKILL.md 与 frontmatter 到底怎么运作2.1 一个 Skill 的最小结构长什么样很多人第一次看到 Skill会以为它是个很复杂的东西。其实一个能用的 Skill核心就是一个目录加一个SKILL.md文件。目录名通常就是 Skill 的名字SKILL.md里面分两部分上面是 frontmatter下面是正文说明。frontmatter 是用三条横线包起来的一段元信息写法类似这样--- name: vue-best-practices description: Vue 3 项目开发规范包含组合式 API 写法、目录约定、命名规则 ---这两行看起来简单但它们是整个 Skill 能不能被正确触发的关键。name是标识description是给模型判断“什么时候该用我”的依据。我踩过的第一个坑就在这里一开始我把 description 写得很文艺比如“让代码更优雅”结果模型根本不知道什么时候该调用它。后来改成具体的场景描述命中率立刻上来了。正文部分就是你真正想让它遵守的规则。可以写代码风格、可以写操作步骤、可以写禁止事项。我一般会分成“适用范围”“核心规则”“示例”“反例”四块。反例这块特别重要因为模型对“不要做什么”的敏感度往往比“要做什么”更高。2.2 frontmatter 里那些容易写错的字段除了 name 和 descriptionfrontmatter 还能放一些控制字段。不同版本支持的范围略有差异但常见的几个方向是触发条件、依赖关系、是否允许自动加载。我个人的经验是不要贪多。字段写得越复杂调试成本越高。有个细节值得单独说description 的写法直接决定了 Skill 的“召回率”。我做过一个粗糙的对比测试同一个 Skilldescription 写成“处理数据”和写成“把 CSV 文件清洗成统一格式并输出统计摘要”后者被正确触发的概率明显更高。原因很简单模型是靠语义匹配来判断的你描述得越贴近真实任务它越容易对上号。还有一个常见误区是把 frontmatter 当成配置文件塞一堆参数。它不是。它更像简历上的“求职意向”作用是让系统快速判断“这个 Skill 适不适合当前任务”。真正的能力细节全部放在正文里。2.3 Skill 和 Agent 的区别别再搞混了热词里经常出现“skill 和 agent 的区别”这个问题我被问过很多次。用一句话概括Skill 是知识Agent 是执行者。Skill 告诉模型“这件事应该怎么做”它本身不主动干活。Agent 则是一个能自主规划、调用工具、多轮执行的实体。你可以把 Skill 理解成给 Agent 看的操作手册Agent 是拿着手册干活的人。没有 Skill 的 Agent 也能干活但干出来的活可能不符合你的规范没有 Agent 的 Skill 就是一份躺在那里没人看的文档。在实际使用中这两者是配合关系。主 agent 负责理解你的整体意图、拆解任务、决定调用哪些能力子 agent 负责在具体环节里执行比如专门做代码审查、专门写测试、专门整理文档。而 Skill 就是这些 agent 在执行时参考的标准。理解了这层关系后面配置起来就顺了。3. 四十个 Skill 的分类与管理思路3.1 我为什么按“场景”而不是“技术栈”分类装到二十个左右的时候我发现一个问题找 Skill 变得很费劲。一开始我是按技术栈分的前端一堆、后端一堆、数据库一堆。但实际用的时候我的任务往往是跨栈的比如“给这个接口加个字段并更新前端调用”它同时涉及后端和前端。按技术栈分类反而让我每次都要想“这该归哪类”。后来我改成按使用场景分类情况就好多了。我现在的分类大致是这几组编码规范类命名、目录结构、注释风格、提交信息格式审查质检类代码审查、安全检查、性能检查、边界条件检查文档写作类接口文档、README、变更日志、注释补全数据处理类CSV 清洗、JSON 转换、统计摘要、格式校验流程协作类任务拆解、子 agent 调度、上下文压缩、会话交接这样分的好处是我脑子里想的是“我现在要干什么”而不是“这属于哪个技术”。场景是任务的第一直觉技术栈是第二直觉。按第一直觉组织检索效率高很多。3.2 哪些 Skill 是真高频哪些是凑数的四十个里面真正每天都在用的其实也就十来个。我统计过一段时间的使用频率大致是这样的分布类型数量使用频率是否建议新手优先配置编码规范类8极高是审查质检类6高是文档写作类5中是数据处理类7中视需求流程协作类6高是实验性/尝鲜类8低否那八个实验性的基本是我看到新东西就想试试装上的结果比如某些特定领域的写作 Skill、某些小众语言的规范 Skill。装完之后发现要么触发不了要么触发了但输出质量还不如我自己写提示词。这部分我建议新手直接跳过先把高频的十几个配好比堆数量有用得多。提示Skill 不是越多越好。每多一个 Skill模型在判断“该用哪个”时就多一分干扰。数量上去之后description 之间的语义重叠会变成新的问题。3.3 目录组织与命名约定我的目录结构大概是这样的skills/ coding/ naming-convention/ SKILL.md commit-format/ SKILL.md review/ code-review/ SKILL.md security-check/ SKILL.md docs/ api-doc/ SKILL.md分层目录的好处是我一眼能看出这个 Skill 属于哪个场景组。命名上我坚持用“动作对象”的格式比如code-review、commit-format、csv-clean。避免用helper、utils、misc这种模糊词因为模糊词会让 description 也跟着模糊最后触发不准。有个小技巧我会在每个 Skill 目录里额外放一个examples.md专门存这个 Skill 的典型输入输出。它不参与触发但在我调试 Skill 效果的时候特别有用相当于给自己留了一份回归测试用例。4. 子 Agent 与主 Agent 的配合实操4.1 主 agent 负责什么子 agent 负责什么主 agent 的角色是“项目经理”。它接收你的整体需求判断这个任务有多大、需要拆成几步、每步该用什么能力。子 agent 的角色是“专项执行者”它只关心自己那一小块比如“审查这段代码”“把这个 JSON 转成表格”。我一开始不理解为什么要分子 agent觉得一个 agent 全干了不就行了。后来发现任务一复杂单个 agent 的上下文会被塞爆前面聊的内容到后面就“忘”了。子 agent 的价值在于隔离上下文每个子 agent 只带自己需要的信息干完活把结果交回主 agent主 agent 再汇总。这样既省上下文又提高每步的专注度。举个我实际用过的例子。我要给一个老项目补测试任务链是这样的主 agent 先扫描项目结构识别出哪些模块没有测试然后派子 agent 逐个模块分析依赖和边界条件再派另一个子 agent 按项目规范生成测试代码最后主 agent 汇总并检查一致性。整个过程里每个子 agent 只看到自己那个模块的信息不会被其他模块的细节干扰。4.2 子 agent 的配置要点配置子 agent 的时候有几个点必须交代清楚否则它很容易跑偏职责边界明确告诉它“你只负责 X不要碰 Y”输入格式它需要什么信息以什么形式给它输出格式它应该返回什么结构化还是自然语言参考 Skill它执行时应该遵守哪个 Skill 的规范我踩过的一个坑是没写清楚输出格式结果子 agent 返回了一大段散文主 agent 还得再解析一遍效率反而低了。后来我强制要求子 agent 用固定结构返回比如“结论 依据 建议”三段式主 agent 处理起来就顺畅多了。4.3 上下文压缩与会话交接任务链一长上下文就会膨胀。这时候“上下文压缩”这个 Skill 就派上用场了。它的作用是让主 agent 在阶段之间把已完成的信息压缩成摘要丢掉冗余细节只保留结论和关键决策。这样下一阶段开始时上下文是干净的。会话交接是另一个实用场景。比如我今天干到一半要下班明天接着干。我会让主 agent 生成一份交接摘要当前进度、已做的决策、待办事项、注意事项。第二天新开会话把这份摘要喂进去就能无缝接上。这个习惯养成之后我再也没有出现过“昨天聊到哪了”的尴尬。注意子 agent 不是越多越好。每派一个子 agent 都有调度开销任务太碎反而拖慢整体速度。我的经验是单个子 agent 的任务量控制在“一个明确的小目标”比较合适。5. 从零配置一套可用 Skill 的完整流程5.1 环境准备与安装路径确认不管你是在 Ubuntu 上装 Claude Code还是在 Windows 上通过 VS Code 配置第一步都是确认 Skill 的加载路径。不同安装方式路径不太一样。我建议先跑一次基础命令确认程序能正常启动再去找配置目录。在 Ubuntu 上我一般会先确认命令行工具能正常调用然后找到用户配置目录下的 skills 文件夹。在 Windows 上如果用的是桌面版或者 VS Code 集成路径通常在用户目录下的隐藏配置文件夹里。找不到的时候我会用搜索功能直接搜SKILL.md看系统里已经有哪些 Skill它们的父目录就是加载路径。这一步的常见问题是权限。如果目录没有写权限你放进去的 Skill 不会被加载而且不会有明显报错只是“没生效”。我建议放完文件后手动确认一下文件确实在目标目录里。5.2 手动安装 GitHub 上的 Skill热词里有人问“怎么手动装 GitHub 上的 skills”这个流程其实很简单。核心就是把仓库里的 Skill 目录复制到你的加载路径下。具体步骤找到目标 Skill 的仓库确认里面有SKILL.md把整个 Skill 目录复制到你的 skills 加载路径检查 frontmatter 的 name 和 description 是否完整重启会话让系统重新扫描用一个贴近 description 的任务测试是否触发我踩过的坑是有些仓库的SKILL.md放在子目录里直接复制外层目录会导致加载不到。还有的仓库 frontmatter 字段名写错了比如把description写成desc这种不会报错但也不会生效。所以复制完一定要打开文件看一眼。5.3 写第一个自己的 Skill与其装一堆别人的不如先写一个自己的。我建议从“提交信息格式”这种小而明确的场景开始。步骤是建目录比如commit-format写SKILL.mdfrontmatter 里 name 写commit-formatdescription 写“生成符合约定式提交规范的提交信息”正文里写清楚格式规则、允许的类型前缀、示例、反例保存后重启会话让它帮你写一条提交信息看是否符合规范这个 Skill 我写了不到二十行但每天都在用。它的价值不在于多复杂而在于把一件我每次都要想一下的事变成了默认行为。这就是 Skill 的核心价值。5.4 参数与触发条件的调试方法Skill 不生效八成是触发条件的问题。我的调试方法是“对照实验”准备两个任务一个应该触发一个不应该触发分别跑一遍看结果。如果该触发的没触发就改 description让它更贴近任务描述如果不该触发的触发了就加限定词缩小范围。这个过程有点像调搜索引擎的关键词。你不能指望一次写对得反复试。我一般会改三到五轮直到触发准确率稳定下来。改的时候记得一次只改一个地方不然你不知道是哪个改动起了作用。6. 常见问题与排查技巧实录6.1 Skill 装了但完全不生效这是最高频的问题。排查顺序我一般是这样的现象可能原因排查方法完全没反应路径不对确认文件在加载目录下完全没反应frontmatter 格式错检查三条横线是否完整偶尔触发description 太模糊改成具体场景描述触发但输出不对正文规则不清补充示例和反例和其他 Skill 冲突语义重叠合并或明确边界我遇到最多的是 frontmatter 格式问题。比如横线只有两条、字段名拼错、冒号后面没空格。这些细节看起来小但直接决定加载成败。建议写完先用眼睛逐行核对一遍。6.2 多个 Skill 互相干扰装到三十个以上之后我开始遇到 Skill 之间“抢活”的情况。比如一个任务同时符合两个 Skill 的描述模型可能选错或者两个都用导致输出混乱。解决办法有两个一是合并语义相近的 Skill二是给每个 Skill 加明确的“不适用场景”。我现在的做法是每个 Skill 正文开头都写一句“本 Skill 仅适用于 X不适用于 Y”。这句话看起来多余但实际能挡掉很多误触发。尤其是那些场景相邻的 Skill比如“代码审查”和“安全检查”边界一定要划清楚。6.3 子 agent 返回结果不可用子 agent 返回一堆废话或者格式不对通常是因为你没告诉它要什么。我的经验是给子 agent 的指令要像给外包写需求一样具体输入是什么、要做什么、输出什么格式、参考什么规范、不要做什么。这五点写全返回质量立刻不一样。还有一个隐藏问题是子 agent 的上下文里带了太多无关信息。如果你把整个项目都塞给它它反而抓不住重点。正确做法是只给它完成任务必需的那部分信息其余的让主 agent 保留。6.4 性能与上下文膨胀Skill 多了之后每次会话启动时加载的元信息也变多启动会变慢。我的应对策略是分组加载把不常用的 Skill 放到单独的目录需要时再临时启用。这样日常会话只加载高频的那十几个速度和准确率都更好。上下文膨胀的另一个来源是长任务链。我的习惯是每完成一个阶段就让主 agent 压缩一次把细节丢掉只留结论。这个习惯让我的长任务稳定性提升了很多不再出现“聊到后面它忘了前面”的情况。7. 一些我踩过的坑和真实体会装到四十个 Skill 之后我最大的体会是Skill 的质量远比数量重要。我见过有人一上来就装几十个结果一个都不生效最后得出结论说“这东西没用”。其实问题不在 Skill在于没理解它的运作逻辑。它需要你花时间写清楚、调准确才能发挥作用。第二个体会是Skill 和 Agent 的配合是有学习曲线的。一开始我只用主 agent觉得够用。后来学会派子 agent效率提升明显但也踩了不少坑比如任务拆得太碎、子 agent 之间信息不同步。这些都得靠实际用才能摸出门道。第三个体会是关于维护。Skill 不是写完就不管了。项目规范变了、工具升级了、你自己的习惯变了Skill 都得跟着更新。我现在每个月会花半小时过一遍自己的 Skill把过时的删掉把常用的优化一下。这半小时的投入换来的是接下来一个月每次会话的顺畅。最后分享一个小技巧如果你不确定一个 Skill 该不该留就把它停用一周。一周内你如果完全没想起它那它大概率可以删了。这个方法帮我从四十个精简到了二十多个真正有用的剩下的都是精华。