1. 从“能跑就行”到“四十个Skill全装上”我为什么突然觉得之前白用了最开始用 Claude Code 的时候我跟大多数人一样把它当成一个“能读项目、能改文件、能跑命令”的终端助手。装好、配好 key、进项目目录敲一句需求它就开始干活。能用确实能用但用久了总有一种说不出的别扭每次开新会话它对我这个项目的理解都像第一次见面我反复强调的代码规范、目录约定、提交信息格式它转头就忘同一个“帮我写个组件”的活儿今天给的风格和昨天完全不一样。后来我才意识到问题不在模型本身而在我一直只用了它最表层的能力——对话。Claude Code 真正的扩展性藏在Skill这套机制里。所谓 Skill你可以粗暴理解成“给这个助手预先写好的一本本操作手册”每本手册放在一个独立目录里核心是一个SKILL.md文件文件头部用frontmatter就是被---包起来的那段元数据声明这个技能叫什么、什么时候该被触发、需要哪些工具权限正文则写清楚具体怎么做。我一开始也只装了三五个觉得够用了。直到某天心血来潮把手头攒的、社区里口碑好的、自己写的 Skill 一口气整理到40 个重新跑了一遍日常开发流程那种感觉就像——原来我之前一直在用一台没装驱动的电脑。不是它不行是我没把它的接口接上。这篇东西不打算写成又一篇“Claude Code 入门指南”那种文章已经够多了。我想聊的是当你把 Skill 当成一套真正的工程化配置来管理时哪些认知会被彻底刷新哪些坑是装到第 20 个才会暴露出来的以及那 40 个 Skill 到底该怎么分类、怎么触发、怎么和子 agent 配合。如果你现在还在“一个会话干所有事”的阶段这篇大概率能帮你省下不少重复劳动。2. Skill 到底是什么把 SKILL.md 和 frontmatter 拆开看2.1 一个 Skill 就是一个带元数据的目录很多人第一次接触 Skill会以为它是什么高深的插件系统其实结构朴素得让人意外。一个 Skill 就是一个文件夹里面至少有一个SKILL.md。这个文件分两部分frontmatter夹在两行---之间的 YAML 元数据声明name、description有的实现还支持声明允许使用的工具、是否自动触发等。正文Markdown 写的操作说明告诉模型“遇到这类任务时按这些步骤做”。我自己的一个代码规范 Skillfrontmatter 大概长这样--- name: vue-component-style description: 当需要新建或修改 Vue 单文件组件时使用统一组件结构、命名与样式约定 ---正文里我会写清楚script setup放最前、props 用defineProps加类型、样式一律 scoped、组件文件名用大驼峰等等。关键在于description 的措辞——它不是写给人看的简介而是写给模型看的“触发条件”。写得越具体模型越知道什么时候该翻这本手册。2.2 frontmatter 里的 description 才是真正的开关装到十几个 Skill 之后我才慢慢摸清一个规律Skill 能不能被正确调用八成取决于 description 写得好不好。我踩过最典型的坑是早期写了一个叫code-review的 Skilldescription 只写了“用于代码审查”。结果模型几乎从不主动用它因为“代码审查”这个描述太宽泛和它默认就会做的事重叠了。后来我改成“当用户要求对已完成的改动做系统性检查需要按安全性、可读性、边界条件三个维度逐项过一遍时使用。”触发率立刻上来了。原因很简单description 要描述的是“场景”而不是“功能”。功能是模型本来就会的场景才是它需要被提醒“这里该用专门流程”的信号。提示如果你装了 Skill 却发现模型很少调用先别怀疑机制回去把 description 重写成“当……时使用”的句式把触发场景写具体十有八九能解决。2.3 Skill 和子 agent 的分工一个管“怎么做”一个管“谁来做”热词里经常有人问“skill 和 agent 的区别”这个问题我当初也纠结过。用下来我的理解是维度Skill子 agent本质一套操作流程/知识一个独立的执行角色关注点怎么做这件事谁来独立完成这件事上下文共享主会话上下文拥有独立上下文可隔离典型用途规范、模板、固定流程并行调研、独立验证、长任务拆分举个我实际用的例子我要给一个老项目补测试。我会让子 agent去独立读某个模块、梳理出所有对外函数因为它需要大量阅读、会污染主上下文而“测试文件该怎么命名、断言该怎么写”这类规范则交给Skill来约束。子 agent 负责“跑腿和隔离”Skill 负责“立规矩”。两者配合才是我装到 40 个之后效率真正起飞的原因。3. 四十个 Skill 的分类法别一股脑全塞进去3.1 按“触发时机”分四类比按功能分更有用一开始我按功能分类前端类、后端类、文档类……结果发现不好用因为真正决定体验的是“什么时候被触发”。后来我改成按触发时机分四类管理起来清爽很多常驻规范类几乎每个任务都该遵守比如命名约定、提交信息格式、注释语言。任务触发类只在特定任务出现时用比如“写单元测试”“生成 API 文档”。工具封装类把某条固定命令流程包起来比如“按项目约定跑 lint 并自动修复”。领域知识类某个垂直领域的知识比如数学建模里的建模步骤、论文写作的结构规范。这么分的好处是我能一眼看出哪些 Skill 是“背景音”哪些是“按需响”。常驻类要写得克制否则每个会话都背着几十条规范反而拖慢响应任务触发类则可以写得详细反正平时不占地方。3.2 常驻类 Skill 要“少而精”否则会互相打架我装到第 15 个左右时遇到一个典型问题两个常驻 Skill 对“函数注释”的要求冲突一个要求写 JSDoc一个要求简洁单行注释。模型每次都要在两者之间犹豫输出变得不稳定。解决办法是合并同类项把所有关于“代码风格”的常驻规范收敛到一个 Skill 里内部用分节写清楚不同语言、不同场景的差异。常驻类 Skill 的数量我个人经验是控制在 5 个以内比较舒服超过之后边际收益急剧下降冲突概率却直线上升。3.3 任务触发类才是数量主力可以放心堆真正让我觉得“40 个不嫌多”的是任务触发类。因为它们平时不触发只在对应任务出现时才被翻出来所以堆多少都不太影响日常。我手头这类大概有二十多个覆盖了写测试、写迁移脚本、写 CI 配置生成变更日志、生成 PR 描述数据清洗、格式转换、批量重命名特定框架的脚手架生成这类 Skill 的写法有个共同点开头先写“前置检查”。比如写测试的 Skill第一步永远是“先确认测试框架和现有测试目录结构”而不是上来就写代码。这个习惯帮我避免了很多“生成的测试跑不起来”的尴尬。4. 装到第 20 个才暴露的坑触发、冲突与上下文膨胀4.1 Skill 不触发先查 description再查目录结构这是最高频的问题。我总结的排查链路是这样的看 description 是不是“功能描述”而非“场景描述”——最常见原因。看目录层级对不对——Skill 通常要放在约定的 skills 目录下多套一层文件夹就找不到。看 frontmatter 的 YAML 有没有语法错误——一个中文冒号、一个没对齐的缩进都会让整个 frontmatter 解析失败Skill 直接失效。看名字有没有和内置能力撞车——名字太泛模型会优先用默认行为。我印象最深的一次一个 Skill 死活不触发查了半小时最后发现是 frontmatter 里description那行我用了中文全角冒号。改成半角立刻就好了。这种坑文档里不会写只有自己踩过才记得住。4.2 多个 Skill 同时命中优先级和互斥要提前设计当 Skill 多起来一个任务同时命中三四个 Skill 是常事。比如“帮我重构这个组件”可能同时触发“代码风格”“重构流程”“测试补充”三个。如果它们之间没有约定好先后模型就会乱。我的做法是在常驻规范类 Skill 里写一句总纲“当多个技能同时适用时先执行流程类再执行规范类最后执行验证类。”相当于给模型一个调度顺序。另外对于明确互斥的 Skill比如两套不同的目录结构约定我会在 description 里写明适用条件让它们尽量不重叠。4.3 上下文膨胀Skill 不是越多越好是要“按需加载”装到 30 个之后我明显感觉到会话变“重”了模型开始在一些无关任务里引用不相关的 Skill 内容。原因在于如果所有 Skill 的正文都被塞进上下文那再强的模型也会被淹没。正确的姿势是让 Skill 按需加载平时上下文里只保留各 Skill 的 name 和 description也就是 frontmatter只有当某个 Skill 被判定适用时才把它的正文读进来。这也是为什么 description 要写得精准——它承担的是“索引”的角色。理解这一点之后我把每个 Skill 的正文都做了瘦身只留真正必要的步骤把大段背景知识挪到同目录的附加文件里需要时再引用。5. 我的高频 Skill 清单哪些真的每天都在用5.1 规范类三件套代码风格、提交信息、注释语言这三个是我装的所有 Skill 里使用频率最高的。代码风格 Skill 管命名和结构提交信息 Skill 管 commit message 的格式我用的是“类型: 简述”这种注释语言 Skill 统一规定注释用中文还是英文。它们几乎在每个任务里都会被动触发属于“背景音”级别的存在。写这类 Skill 有个心得别写“应该怎样”要写“必须怎样例外情况是什么”。模型对模糊表述的容忍度比人低你写“尽量使用简洁命名”它可能理解成各种样子你写“组件名必须大驼峰工具函数必须小驼峰例外与后端接口字段对应的变量保持下划线”它就执行得很稳。5.2 流程类测试生成、重构、文档同步流程类 Skill 的价值在于把多步骤任务标准化。以测试生成为例我的 Skill 里固定了这几步先扫描目标文件列出所有导出成员。检查是否已有对应测试文件有则增量补充。按项目现有测试风格生成用例覆盖正常路径和至少一个边界。生成后尝试运行失败则报告而不是硬改。第 4 步特别重要。早期我没写这条模型生成完测试就“交差”了结果一堆跑不过的用例。加上“尝试运行并如实报告”之后它要么生成能跑的要么明确告诉我哪里需要人工确认体验好太多。5.3 领域类数学建模、论文结构、文献检索热词里“数学建模 skill”“论文 skill”“检索文献 skill”出现频率很高说明大家对垂直领域 Skill 需求很旺。我自己写过一个数学建模的 Skill核心是把建模流程拆成“问题重述—假设—符号定义—模型建立—求解—检验”六步每一步都要求先输出再进入下一步。这样模型不会一上来就堆公式而是像真正的建模过程一样推进。论文结构类 Skill 则更像模板摘要怎么写、引言怎么引出问题、方法部分怎么组织。这类 Skill 的关键是给出结构而非内容内容让模型根据实际材料填结构由 Skill 锁死出来的东西就规整很多。6. 从零到四十一套可复制的 Skill 管理流程6.1 建立目录约定让每个 Skill 各就各位我现在所有 Skill 都放在一个统一目录下按类别分子目录skills/ always/ # 常驻规范类 tasks/ # 任务触发类 tools/ # 工具封装类 domain/ # 领域知识类每个子目录下再放各自的 Skill 文件夹。这个约定最大的好处是可迁移换机器、换项目整个目录拷过去就能用。我甚至把它纳入版本管理每次调整 Skill 都有记录改坏了能回滚。6.2 新 Skill 的诞生流程从“重复三次”开始我的原则是同一个操作重复三次以上才值得写成 Skill。只做一次的事直接对话解决就行写 Skill 反而是负担。确定要写之后流程是先手动做一遍把实际步骤记下来。把步骤抽象成“前置检查—执行—验证”三段。写 frontmatterdescription 用“当……时使用”句式。找三个不同场景测试触发是否准确。根据测试结果微调 description 和正文。第 4 步是很多人跳过的但恰恰最重要。一个 Skill 写得再好触发不准就是废的。6.3 定期清理删掉三个月没触发的 Skill装到 40 个之后我养成了每月清理一次的习惯。判断标准很简单过去三个月一次都没被触发过的要么删要么重写 description。因为一个从不触发的 Skill要么是场景太窄要么是描述有问题留着只会增加上下文负担。清理时我还会顺手合并功能重叠的 Skill。比如我一度有三个关于“格式化”的 Skill后来合并成一个内部按文件类型分节清爽多了。7. 和子 agent 配合让 Skill 从“手册”变成“团队”7.1 子 agent 负责隔离Skill 负责统一这是我用下来最有价值的一个组合。子 agent 最大的特点是上下文独立适合干那些“读一大堆东西但只需要一个结论”的活。比如让子 agent 去调研某个库的用法它读一堆文档最后只回我一段结论主会话干干净净。但子 agent 独立之后怎么保证它产出的东西符合我的规范答案就是让子 agent 也加载同一套 Skill。这样无论主 agent 还是子 agent写出来的代码风格、提交格式都是一致的。Skill 在这里扮演的是“团队规范”的角色子 agent 是“团队成员”规范统一了协作才顺。7.2 并行任务里Skill 是保证一致性的锚点我经常同时开几个子 agent 干不同的活一个补测试、一个写文档、一个重构。如果它们各自为政产出会五花八门。但因为它们共享同一套 Skill最终合并回来的东西风格是统一的。这一点在多人协作的项目里尤其重要——Skill 把“个人习惯”变成了“项目约定”。7.3 主 agent 做调度子 agent 做执行Skill 做约束把这三者关系理清之后我的工作流变成了主 agent 负责理解需求、拆解任务、决定派谁去做子 agent 负责具体执行Skill 负责约束执行的质量和风格。三者各司其职我作为使用者更多是在“设计流程”而不是“盯着每一步”。这才是装到 40 个 Skill 之后我真正觉得“之前白用了”的地方——从操作者变成了流程设计者。8. 几个只有踩过才知道的细节8.1 frontmatter 的缩进和符号比你想的敏感前面提过全角冒号的坑这里再补几个YAML 对缩进极其敏感name和description必须同级对齐字符串里如果有冒号最好用引号包起来中文内容没问题但标点符号一定要用半角。我现在的习惯是写完 frontmatter 先用一个最小的 YAML 校验工具过一遍省得后面排查。8.2 description 里别写“等等”“之类”这种模糊词“处理各种代码问题等等”——这种 description 等于没写。模型需要的是明确的边界模糊词会让它要么过度触发要么完全不触发。我现在写 description会刻意避免“等”“之类”“相关”这些词宁可多写几个具体场景。8.3 Skill 正文里步骤要能“独立执行”一个常见误区是把 Skill 正文写成给人看的说明文。但它是给模型执行的所以每一步都要是可执行的动作而不是“理解一下这个背景”。背景可以放在开头一小段但主体必须是“第一步做什么、第二步做什么”。我现在的 Skill 正文基本都能当成一份 checklist 来读。8.4 别在 Skill 里写死具体路径和密钥Skill 是要跨项目复用的写死路径就废了。我的做法是路径用相对描述“项目根目录下的 src”密钥一律不写需要时让模型从环境变量或配置文件读。这样同一个 Skill 换个项目照样能用。9. 关于“装 Skill”这件事我现在的真实体会装到 40 个之后我最大的转变不是效率提升了多少而是对“怎么用 AI 编程助手”这件事的理解变了。以前我把它当成一个更聪明的自动补全现在我把它当成一个需要被“配置”和“管理”的团队成员。Skill 是它的岗位手册子 agent 是它的分身frontmatter 是它的任务分派规则。如果你现在只装了三五个 Skill我的建议不是立刻冲到 40 个而是先把常驻规范类那三五个写扎实让模型先稳定下来。稳定之后再按“重复三次才写”的原则一个个往上加。加的过程中description 的措辞、正文的步骤化、和子 agent 的配合这三件事会反复出现把这三件事处理好数量自然就上去了而且每一个都是真正在用的不是摆设。最后分享一个我最近才养成的小习惯每次新写一个 Skill我会先故意在一个不相关的任务里试一次看它会不会被误触发。如果误触发了说明 description 写得太宽如果该触发时没触发说明写得太窄。这个“正反各试一次”的动作帮我省下了大量后期调试的时间。Skill 这东西写只是开始调才是常态。