1. 从“能跑就行”到“跑得漂亮”我为什么开始折腾 Skill刚上手 Claude Code 那阵子我跟大多数人一样觉得这东西能读懂代码、能改文件、能跑命令已经够神了。日常写个脚本、调个接口、重构个小模块直接对话就能搞定心里还挺得意。直到有一次我让它帮我处理一个跨了七八个文件的 Vue 组件重构结果它改到一半开始“自由发挥”——该保留的 props 给我删了该抽的 composable 又原地内联最后我花了比手写还长的时间去擦屁股。那次之后我才意识到一个问题Claude Code 的默认能力是“通用智能”不是“领域专家”。它知道 Vue 怎么写但它不知道你这个项目的 Vue 该怎么写它能写测试但它不知道你们团队的测试规范长什么样。每次对话都像在跟一个刚入职的聪明新人解释一遍规矩解释完这轮下轮又忘了。后来我接触到Skill这个概念准确说是SKILL.md这套机制才明白之前真的是“白用了”。Skill 的本质是把你的领域知识、项目规范、操作流程固化成一个 Claude Code 能自动识别、按需加载的能力包。装上 40 个 Skill 之后我的体感是它从一个“什么都会一点的通才”变成了一个“懂我项目、守我规矩、按我流程干活的老手”。这篇内容我想聊的不是“Skill 是什么”这种概念科普而是我踩过一圈坑之后真正跑通的那套方法论Skill 到底怎么组织、SKILL.md的 frontmatter 怎么写才不翻车、子 agent 和主 agent 怎么配合、40 个 Skill 怎么管理才不乱。如果你也在用 Claude Code或者正在纠结要不要上 Skill这篇应该能帮你少走不少弯路。2. Skill 到底解决了什么问题一次真实的翻车复盘2.1 没有 Skill 时Claude Code 的“失忆症”有多严重我先还原一下那次 Vue 重构的翻车现场因为这个问题特别典型。项目是一个中型的后台管理系统组件目录结构是views/下面按业务模块分每个模块里有components/、composables/、api/三层。团队约定所有接口调用必须走api/层封装组件里不允许直接fetch所有可复用的状态逻辑必须抽成composable不允许在组件里堆ref和watch。我当时的 prompt 大概是“帮我把 UserList 这个组件重构一下逻辑太乱了。”Claude Code 干得挺快但它干了什么它把接口调用直接内联到了组件里理由是“减少一层抽象更直观”它把原本已经抽好的useUserFiltercomposable 又拆回了组件内部理由是“这个逻辑只在这个组件用”。从纯技术角度它没错甚至有点道理。但它完全不知道我们团队的约定也不知道这个 composable 未来还要被另外三个页面复用。这就是没有 Skill 时的核心痛点每次对话都是“冷启动”。你得在 prompt 里把所有背景、规范、约束重新讲一遍讲少了它自由发挥讲多了 token 爆炸而且下一轮对话它又忘了。2.2 Skill 的本质把“口头交代”变成“可加载的能力模块”Skill 的机制其实很朴素它就是一个目录里面放一个SKILL.md文件加上可选的脚本、模板、参考资料。Claude Code 在启动或者执行任务时会根据SKILL.md里的元信息判断“这个任务要不要加载这个 Skill”需要就加载不需要就跳过。你可以把它理解成给 Claude Code 装了一套“插件系统”但比传统插件轻得多——它不需要编译不需要注册就是一个 Markdown 文件加几个附属资源。真正让它“活”起来的是SKILL.md顶部的frontmatter也就是那一段用---包起来的 YAML 元数据。我举个最直观的对比。没有 Skill 的时候我每次都要写“注意我们这个项目用 Vue 3 Composition API接口统一走 api 层状态逻辑抽 composable命名用 camelCase组件文件用 PascalCase……”有了 Skill 之后我只需要在SKILL.md里写一次--- name: vue-project-conventions description: 本项目 Vue 3 开发规范涉及组件重构、接口调用、状态管理时加载 ---然后正文里把规范写清楚。之后每次我提到“重构 Vue 组件”Claude Code 会自动把这个 Skill 拉进来规范就生效了。这就是从“每次口头交代”到“一次固化、按需加载”的质变。2.3 为什么是 40 个而不是 4 个或 400 个有人可能会问装这么多 Skill 不会乱吗我的经验是Skill 的数量不是问题粒度和触发条件是问题。我一开始只装了 4 个 Skill结果每个都写得特别大而全一个“前端开发规范”里塞了 Vue、React、CSS、测试、构建所有东西。问题是当我只是想让 Claude Code 帮我改个 CSS 变量时它把整个前端规范都加载进来了token 浪费不说还容易触发不相关的约束。后来我拆成了 40 个每个 Skill 只干一件事vue-component-refactor、api-layer-convention、composable-extraction、unit-test-style、commit-message-format……每个的description都写得非常具体明确“什么时候该加载我”。这样 Claude Code 的匹配精度反而高了因为它能根据任务精准命中。所以 40 个不是拍脑袋的数字而是按“任务场景”而不是“技术栈”来切分的结果。一个 Skill 对应一类高频任务这才是合理的粒度。3. SKILL.md 的 frontmatter90% 的坑都藏在这几行里3.1 name 和 description 的写法直接决定 Skill 会不会被触发frontmatter 里最关键的字段就两个name和description。很多人 Skill 写了半天不生效问题基本都出在这。name的规则很简单小写字母、数字、连字符别用空格和大写。我见过有人写name: Vue Best Practices结果加载直接失败。正确写法是name: vue-best-practices。description才是真正的重头戏。它的作用是让 Claude Code 判断“当前任务要不要加载这个 Skill”。所以 description 不是写给人看的简介而是写给模型看的触发条件。我踩过的坑是description 写得太抽象比如“Vue 开发相关规范”。结果 Claude Code 在改一个.vue文件时不确定要不要加载有时候加载有时候不加载行为很不稳定。后来我改成“当任务涉及 Vue 3 组件的新建、重构、props 设计、composable 抽取时加载。不涉及纯 CSS 调整或构建配置。”——明确说清楚“什么时候用”和“什么时候不用”触发就稳定多了。这里有个经验description 里最好包含具体的动作词和文件类型比如“重构组件”“新建 composable”“修改 api 层”而不是“前端开发”这种大词。模型是靠语义匹配的越具体越准。3.2 正文结构别写成散文要写成“可执行的指令”frontmatter 下面是正文也就是 Skill 的实际内容。我一开始把它当博客写洋洋洒洒讲了一堆“为什么要有规范”结果 Claude Code 加载后抓不住重点。正确的写法是指令式、清单式。比如## 组件重构规则 1. 接口调用必须走 src/api/ 下的封装函数禁止在组件内直接使用 fetch/axios 2. 可复用的状态逻辑必须抽成 composables/useXxx.ts命名以 use 开头 3. 组件文件命名用 PascalCasecomposable 文件命名用 camelCase 4. 重构后必须检查是否有其他页面引用了被改动的 composable ## 反例 - 不要在组件里写 const res await fetch(/api/users) - 不要把已经在 composables 里的逻辑内联回组件用“必须”“禁止”“不要”这种强指令词比“建议”“最好”有效得多。模型对祈使句的遵循度明显更高。3.3 一个容易忽略的细节Skill 的加载是有优先级的当多个 Skill 的 description 都匹配当前任务时Claude Code 会加载多个。这时候如果两个 Skill 的规则冲突就会出问题。我遇到过一个 Skill 说“组件逻辑尽量内联减少抽象”另一个说“可复用逻辑必须抽 composable”。结果 Claude Code 在两个规则之间反复横跳改出来的代码四不像。解决办法是在 Skill 里显式声明优先级和边界。比如在vue-component-refactor里写一句“本 Skill 的规则优先于通用代码风格 Skill。”或者在 description 里就划清界限避免两个 Skill 覆盖同一场景。提示Skill 不是越多越好而是“每个场景只有一个权威 Skill”。同一类任务如果有两个 Skill 都能管一定要合并或者明确主从关系。4. 子 agent 与主 agentSkill 真正发挥威力的地方4.1 主 agent 负责“调度”子 agent 负责“专精”聊到 Skill就绕不开 agent 的协作机制。Claude Code 里主 agent 是那个跟你对话、理解整体任务的“大脑”子 agent 是被主 agent 派出去执行具体子任务的“专家”。我一开始没搞懂这个区别把所有 Skill 都挂给主 agent结果主 agent 的上下文被塞得满满的处理复杂任务时反而变笨了。后来才明白Skill 应该按“谁需要”来分配。举个例子我有个任务是“给现有项目补一套单元测试”。主 agent 负责理解需求、规划要测哪些模块、决定测试顺序。然后它派一个子 agent 去专门写测试这个子 agent 加载unit-test-style这个 Skill专注按团队规范写测试用例。主 agent 不需要知道测试规范的所有细节它只需要知道“有个子 agent 能干这事”。这样分工的好处是主 agent 的上下文保持干净子 agent 的上下文高度聚焦。子 agent 加载的 Skill 越专一它干得越漂亮。4.2 子 agent 的 Skill 配置怎么让“专家”真的专子 agent 的 Skill 配置核心是收窄。一个子 agent 不应该加载超过 3 个 Skill否则它就不“专”了。我的做法是给每个子 agent 定义一个明确的职责然后只挂跟这个职责强相关的 Skill。比如子 agent 职责加载的 Skill不加载的 Skill写单元测试unit-test-style, mock-conventionvue-component-refactor, api-layer-convention重构 Vue 组件vue-component-refactor, composable-extractionunit-test-style, commit-message-format生成提交信息commit-message-format其他全部这样每个子 agent 的“知识边界”非常清晰不会互相干扰。4.3 主 agent 怎么知道该派哪个子 agent这是很多人卡住的地方主 agent 怎么知道有哪些子 agent 可用、各自能干什么答案是在子 agent 的配置里写清楚 description跟 Skill 的 description 一个道理。主 agent 会根据任务描述去匹配子 agent 的能力描述。所以子 agent 的 description 也要写得具体比如“用于按团队规范编写和补充单元测试输入是待测模块路径输出是测试文件”。我实测下来子 agent 的 description 写得越像“任务说明书”主 agent 的调度就越准。如果只写“测试相关”主 agent 经常不知道该不该派它。5. 40 个 Skill 的实战分类我是怎么组织这套体系的5.1 按“任务阶段”分四层而不是按技术栈分40 个 Skill 如果乱放找都找不到。我的组织方式是按任务阶段分四层规范层定义“应该怎么做”比如vue-project-conventions、api-layer-convention、naming-convention操作层定义“具体怎么执行”比如vue-component-refactor、composable-extraction、unit-test-style检查层定义“做完怎么验”比如lint-check、type-check、test-coverage-check流程层定义“协作怎么走”比如commit-message-format、pr-description-template、code-review-checklist这样分层的好处是当我要新增一个 Skill 时很清楚它该放哪一层不会重复也不会遗漏。5.2 高频 Skill 的实战写法以 vue-component-refactor 为例我拿一个真实在用的 Skill 举例展示一下完整结构--- name: vue-component-refactor description: 当任务涉及 Vue 3 组件的重构、拆分、props 重新设计时加载。纯样式调整或新建组件不加载。 --- ## 重构前置检查 1. 先读取目标组件及其引用的 composables、api 文件 2. 搜索项目内是否有其他文件 import 了该组件或相关 composable 3. 确认重构不会破坏外部引用 ## 重构规则 1. 接口调用统一走 src/api/ 封装禁止内联 fetch/axios 2. 可复用状态逻辑抽成 composables/useXxx.ts 3. props 设计遵循必填在前、可选在后类型必须显式声明 4. 事件命名用 kebab-case如 update-value ## 重构后自检 - [ ] 所有外部引用是否仍然有效 - [ ] 是否有逻辑被意外内联 - [ ] props 和 emits 是否都有类型声明这个 Skill 我用了几个月触发稳定规则清晰基本没再出现过“自由发挥”的情况。5.3 那些“看起来有用但实际鸡肋”的 Skill我也写过一些废 Skill分享出来帮大家避坑。第一个是general-coding-style想定义“通用代码风格”。问题是它太泛了几乎每个任务都会触发加载后又说了一堆“变量命名要清晰”这种废话纯占 token。后来我把它拆成了naming-convention和comment-style两个具体 Skill只在特定场景加载。第二个是project-overview想给 Claude Code 讲清楚整个项目架构。结果它每次对话都加载把上下文塞满反而让模型抓不住当前任务重点。项目背景应该放在 CLAUDE.md 里而不是 Skill 里。Skill 是“按需加载的能力”不是“常驻的背景知识”。6. 安装、配置与跨工具使用几个实操层面的坑6.1 Skill 放哪里Claude Code 才能找到Skill 的存放位置有讲究。我实测下来放在项目根目录的.claude/skills/下最稳每个 Skill 一个子目录目录名跟name保持一致.claude/ skills/ vue-component-refactor/ SKILL.md unit-test-style/ SKILL.md commit-message-format/ SKILL.md这样 Claude Code 启动时会自动扫描这个目录。如果你想让某个 Skill 全局可用跨项目可以放到用户目录下的对应位置但我的建议是项目相关的放项目里通用能力才放全局避免不同项目的规范互相污染。6.2 在 VS Code 里用 Skill 的注意事项我平时在 VS Code 里用 Claude Code有几个细节值得说。第一Skill 文件改动后最好重启一下 Claude Code 会话让它重新扫描。我遇到过改了SKILL.md但没生效的情况重启后就好了。第二VS Code 的工作区如果开了多根目录Skill 的扫描范围可能跟你预期不一致。我的做法是每个项目单独开一个窗口避免 Skill 串味。第三如果你同时用其他 AI 编程工具Skill 这套机制不一定通用。SKILL.md的格式是 Claude Code 的约定换到别的工具可能需要转换。所以我在写 Skill 时会尽量把“规范内容”和“工具特定格式”分开方便迁移。6.3 从“能用”到“好用”Skill 的迭代节奏Skill 不是写完就完事的它需要迭代。我的节奏是每踩一次坑就回头改一次 Skill。比如有一次 Claude Code 重构组件时把defineProps的默认值写错了我就在vue-component-refactor里加了一条“props 默认值必须用withDefaults显式声明”。下次它就不会再犯。这种“踩坑—补规则—验证”的循环跑上几轮之后Skill 就越来越贴合你的实际需求。40 个 Skill 不是一次写成的是几十次踩坑攒出来的。7. 我踩过的三个大坑以及最后的经验第一个坑是Skill 写太细细到失去通用性。我曾经写过一个 Skill 专门规定“某个特定组件的 props 命名”结果换个组件就废了。Skill 的粒度应该是“一类任务”不是“一个文件”。第二个坑是子 agent 加载了太多 Skill。我一开始给写测试的子 agent 挂了五六个 Skill结果它写测试时还在纠结组件命名规范效率反而低。后来砍到两个专注度立刻上来了。第三个坑是指望 Skill 解决所有问题。Skill 能固化规范、约束行为但它不能替代你对任务的理解。复杂任务还是得你自己拆解清楚Skill 只是让执行更稳不是让思考外包。最后分享一个我现在的习惯每装一个新 Skill先拿一个真实的小任务验证它会不会被正确触发、规则会不会被正确执行。验证通过再纳入日常使用。这样能避免“装了一堆但不知道哪个在起作用”的混乱。这套东西跑顺之后我最大的感受是Claude Code 的上限其实取决于你给它喂了多少“你自己的经验”。Skill 就是那个把经验沉淀下来的容器。40 个不是终点随着项目演进这个数字还会变但“按任务场景切分、按需加载、持续迭代”这个思路我觉得是能长期用下去的。
