Claude Code 40个Skill实战：SKILL.md配置与子agent分工指南

1. 从“装完就吃灰”说起：40个Skill到底改变了什么

我大概是在Claude Code刚火起来那阵子开始重度使用的。最开始那两个月，我的用法特别朴素：打开终端，进项目目录，敲一句“帮我看看这个报错”，然后等它回。能用，但也就那样——它像一个记性不错但没什么专长的实习生，你问什么它答什么，你不问它就不动。直到有一次我在一个前端项目里连续让它改了七遍样式，每次都要重新解释“我们用的是Tailwind不是CSS Modules”“组件必须走design system里的Button”，我才意识到问题不在模型，在我自己：我把一个可编程的Agent当成了聊天框在用。

后来我开始系统性地往里面塞Skill。从最开始的三五个，到后面稳定维持在四十个左右，中间踩过的坑、删掉的废Skill、重写的SKILL.md，加起来能写一本小册子。这篇就聊聊这四十个Skill是怎么组织的、SKILL.md的frontmatter到底该怎么写、子agent和主agent怎么分工、以及为什么我现在的结论是：Skill不是插件，是你给Agent写的“岗位说明书”。

如果你现在还在“装了一堆Skill但感觉没啥用”的阶段，或者你压根不知道SKILL.md里的frontmatter是干嘛的，那这篇应该能帮你省下至少两周的试错时间。我会把每个关键决策背后的“为什么”讲清楚，参数怎么算、目录怎么放、什么时候该拆子agent、什么时候纯属过度设计，都会给到可直接抄的配置。

2. Skill的本质：不是插件，是上下文注入器

2.1 为什么“装完没感觉”是常态

很多人第一次接触Skill，脑子里对标的是VSCode插件或者Chrome扩展——装上就该有按钮、有面板、有可见的变化。但Skill的运行机制完全不是这个逻辑。一个Skill被触发时，它做的事情是把一段预先写好的指令文本注入到当前对话的上下文里，让模型在生成回复时“顺便”遵守这些约束。它不新增能力，它改变的是模型的行为倾向。

这就解释了一个特别常见的困惑：为什么我装了某个“代码规范Skill”，但模型还是写出了不符合规范的代码？因为Skill的注入是有条件的——它需要被匹配到。匹配靠的是SKILL.md里frontmatter的description字段和当前对话的相关性。如果你的description写得太泛，比如“帮助编写更好的代码”，那它要么永远不触发，要么到处乱触发，两种情况都等于没用。

我自己的经验是：一个Skill的description写得越具体、越场景化，它的触发准确率越高。比如“当用户要求新增React组件时，强制使用函数式组件+TypeScript+项目内design system的Button”就比“React开发规范”强十倍。前者几乎不会误触发，后者会在你聊任何前端话题时都跳出来刷存在感。

2.2 SKILL.md的frontmatter：三个字段决定生死

SKILL.md的frontmatter看起来简单，但每个字段都有讲究。我见过太多人把frontmatter当摆设，随便填两行就往下写正文，结果Skill要么不触发要么乱触发。下面是我实际在用的字段结构：

--- name: react-component-generator description: 当用户要求创建新的React组件、页面或UI模块时使用。强制使用函数式组件、TypeScript、项目内design system组件，禁止使用内联样式和any类型。 version: 1.2.0 tags: [frontend, react, typescript] ---

name字段看起来最不重要，但其实它决定了你在对话里怎么引用这个Skill。我习惯用“领域-动作”的命名法，比如react-component-generator、api-error-handler、sql-query-optimizer。这样在子agent配置里引用的时候一目了然，不会出现“那个管数据库的Skill叫啥来着”的情况。

description是真正的核心。我的写法是“触发条件+强制约束+禁止事项”三段式。触发条件要写得像if语句一样明确，强制约束要具体到可执行，禁止事项要列出最常见的错误做法。这三段缺一段，Skill的效果就打对折。我实测下来，description控制在80到150个字符之间触发最稳定，太短了匹配不准，太长了模型可能只抓到前半段。

version和tags属于锦上添花。version在你迭代Skill的时候有用，tags在Skill数量多了之后方便检索。但如果你只装三五个Skill，这两个字段可以省。

2.3 正文部分：写“怎么做”而不是“是什么”

frontmatter下面的正文，很多人写成了一篇技术文档，大段大段解释React的哲学、TypeScript的好处。这是典型的写错了方向。Skill的正文应该是操作指令，不是知识科普。模型不需要你告诉它什么是函数式组件，它需要你告诉它“在这个项目里，新增组件必须放在src/components/下，文件名用PascalCase，必须导出default，props类型必须显式声明”。

我现在的写法是分三块：执行步骤、代码模板、检查清单。执行步骤用有序列表，每一步都是一个可执行的动作。代码模板直接给一个完整的示例文件，让模型照着改。检查清单是最后一道防线，列出“提交前必须确认”的事项，比如“没有使用any”“没有内联style”“import路径使用@/别名”。

注意：Skill正文里不要写“你应该”“你可以考虑”这种软性表述。模型对“必须”“禁止”“强制”这类词的服从度明显更高。我做过对比测试，同一个约束用“建议使用函数式组件”和“必须使用函数式组件”，后者的遵守率高出将近四成。

3. 四十个Skill的分层架构：别让它们互相打架

3.1 按“触发时机”分四层，而不是按“功能”分

我最初是按功能分类的：前端Skill、后端Skill、数据库Skill、部署Skill。结果很快就乱了，因为一个“新增API接口”的任务会同时触发前端、后端、数据库三个Skill，它们各自往上下文里塞指令，互相覆盖，模型直接懵了。

后来我改成按触发时机分层，问题迎刃而解。四层分别是：

• 全局层：永远生效，不依赖具体任务。比如“代码注释用中文”“提交信息遵循Conventional Commits”“禁止在代码里留console.log”。这层我控制在5个以内，多了会稀释注意力。
• 领域层：按技术栈触发。React、Node、Python、SQL各一个，描述里写清楚“当任务涉及X技术栈时使用”。这层大概15个。
• 任务层：按具体动作触发。比如“新增组件”“写单元测试”“优化查询”“处理错误”。这层大概12个。
• 项目层：只对特定项目生效。比如某个老项目的“禁止使用可选链”“必须兼容IE11”。这层大概8个。

分层的核心逻辑是：同一时刻只让一层到两层的Skill生效。全局层永远在，领域层按技术栈匹配，任务层按动作匹配，项目层按目录匹配。这样上下文里同时活跃的Skill不会超过四个，模型能处理得过来。

3.2 用目录结构做隐式分层

Claude Code读取Skill的方式是扫描特定目录下的SKILL.md文件。我利用这个机制，用目录结构做了隐式分层：

.claude/skills/ ├── global/ │ ├── commit-convention/SKILL.md │ ├── no-console-log/SKILL.md │ └── chinese-comments/SKILL.md ├── domain/ │ ├── react/SKILL.md │ ├── node/SKILL.md │ └── sql/SKILL.md ├── task/ │ ├── new-component/SKILL.md │ ├── unit-test/SKILL.md │ └── error-handler/SKILL.md └── project/ └── legacy-admin/ └── ie11-compat/SKILL.md

这样做的好处是，当我要临时禁用某一层的时候，只需要把对应目录移走或者改个名。比如我在做原型验证的时候，会把project/整个目录临时移走，避免老项目的约束拖慢新项目的开发速度。

3.3 冲突检测：两个Skill说反话怎么办

Skill之间打架是必然会发生的。我遇到过最典型的一次：全局层有个“禁止使用any类型”，任务层有个“快速原型开发”的Skill里写了“允许使用any以加快速度”。两个同时触发的时候，模型的行为变得很不稳定，有时候用any有时候不用。

我的解决方法是加一个优先级声明。在frontmatter里加一个priority字段，数值越大优先级越高。全局层默认100，领域层默认80，任务层默认60，项目层默认40。当两个Skill的指令冲突时，模型会倾向于遵守高优先级的那个。但这个机制不是硬性的，所以我还会在低优先级的Skill里显式写“当与全局规范冲突时，以全局规范为准”。

提示：与其事后检测冲突，不如在写Skill的时候就约定好“全局层永远最高优先级”。这样你只需要保证全局层的Skill足够精简和正确，剩下的层就算有冲突也不会出大问题。

4. 子agent与主agent：分工的边界在哪里

4.1 主agent做决策，子agent做执行

主agent和子agent的关系，我理解成“项目经理和外包团队”。主agent负责理解需求、拆解任务、决定调用哪个子agent、汇总结果。子agent负责在特定领域内深度执行，它不需要知道全局，只需要把手头的活干好。

这个分工的关键在于：子agent的上下文是独立的。主agent把任务描述和必要的上下文传给子agent，子agent在自己的上下文里执行，执行完把结果返回给主agent。这意味着子agent不会被主agent上下文里的其他信息干扰，专注度更高。

我实际用下来，最适合拆子agent的场景有三类：需要大量搜索的任务（比如“在整个代码库里找出所有用了废弃API的地方”）、需要独立验证的任务（比如“写完之后让另一个agent检查一遍”）、需要并行处理的任务（比如“同时给五个文件加测试”）。

4.2 子agent的配置：三个参数决定成败

子agent的配置我一般只关注三个参数：

--- name: code-reviewer description: 当需要审查代码质量、检查潜在bug、验证规范遵守情况时使用。 model: claude-sonnet skills: [global/no-console-log, domain/react, task/unit-test] ---

model参数决定用哪个模型。我的经验是：执行类任务用快模型，审查类任务用强模型。因为审查需要更强的推理能力来发现隐蔽问题，而执行类任务更多是照着模板改，快模型足够。

skills参数决定子agent加载哪些Skill。这里有个容易踩的坑：不要给子agent加载全局层的Skill。全局层的约束应该由主agent在传递任务时以文字形式带过去，而不是让子agent自己去读。因为子agent的上下文窗口有限，加载太多Skill会挤占执行任务的空间。

description参数决定主agent什么时候调用这个子agent。写法和Skill的description一样：触发条件要具体，不要写“用于代码审查”这种泛泛的描述，要写“当主agent完成代码生成后，需要独立验证时使用”。

4.3 一个实际的任务拆解案例

我拿一个真实任务来演示：给一个React项目新增一个“用户列表”页面，包含搜索、分页、排序功能。

主agent的思考过程是这样的：首先识别出这是一个前端任务，触发domain/react和task/new-component两个Skill。然后它把任务拆成四步：生成组件骨架、实现搜索逻辑、实现分页逻辑、实现排序逻辑。接着它决定调用一个子agent来生成组件骨架，因为这一步需要严格遵循design system的规范，独立执行更不容易出错。搜索、分页、排序三步由主agent自己完成，因为这三步之间有依赖关系，放在同一个上下文里更容易保持一致。

子agent收到任务后，加载task/new-component和domain/react两个Skill，生成骨架代码，返回给主agent。主agent拿到骨架后，在上面继续实现三个功能，最后调用code-reviewer子agent做一遍检查。

这个流程我跑了大概二十次，每次都能稳定产出符合规范的代码。关键就在于：子agent只做一件事，主agent负责串联。

5. 从零搭建：四十个Skill的落地步骤

5.1 第一步：先写五个全局Skill，别贪多

新手最容易犯的错是一上来就写二十个Skill，结果互相打架，体验比不装还差。我的建议是：第一周只写五个全局Skill，而且这五个必须是“不依赖任何技术栈”的通用约束。

我最初的五个全局Skill是：

1. commit-convention：提交信息必须用Conventional Commits格式，type用feat/fix/refactor/docs/test/chore。
2. chinese-comments：代码注释和文档用中文，变量名和函数名用英文。
3. no-console-log：禁止在提交的代码里留console.log，调试用logger。
4. error-handling：所有异步操作必须有try-catch或.catch，错误必须被处理或向上抛。
5. file-naming：组件文件用PascalCase，工具函数用camelCase，常量用UPPER_SNAKE_CASE。

这五个Skill我用了两周，确认它们不会误触发、不会互相冲突之后，才开始加领域层。

5.2 第二步：领域层按技术栈写，一个技术栈一个

领域层的Skill我建议一个技术栈只写一个，把所有该技术栈的规范都塞进去。比如React的Skill里同时包含“用函数式组件”“用hooks不用class”“样式用Tailwind”“状态管理用zustand”这些约束。不要拆成四个Skill，拆了之后触发时机很难对齐。

写领域层Skill的时候，description要写清楚“当任务涉及X技术栈时使用”。比如React的description我写的是：“当任务涉及React组件开发、hooks使用、状态管理、样式处理时使用。强制使用函数式组件和TypeScript，禁止class组件和any类型。”

这里有个细节：领域层的Skill不要写得太长。我实测下来，单个SKILL.md的正文控制在500到800字之间效果最好。太短了约束不够，太长了模型可能只记住前半段。如果某个技术栈的规范确实很多，宁可拆成两个Skill，也不要写一个两千字的巨型Skill。

5.3 第三步：任务层按动作写，一个动作一个

任务层的Skill是最容易写多的。我一开始写了三十多个，后来砍到十二个。砍的标准是：这个动作是否足够高频，且是否有明确的执行步骤。低频动作不值得单独写Skill，写在领域层里带一句就行。

我保留的十二个任务层Skill包括：新增组件、新增API接口、写单元测试、写集成测试、优化SQL查询、处理错误、重构函数、写文档、生成类型定义、处理表单、处理路由、处理权限。

每个任务层Skill的正文结构都一样：前置检查（做之前要确认什么）、执行步骤（有序列表）、代码模板（一个完整示例）、后置检查（做完之后要验证什么）。这个结构我用了大半年，稳定可靠。

5.4 第四步：项目层按目录写，一个项目一个

项目层的Skill只对特定目录生效。实现方式是在description里写清楚目录路径，比如“当操作legacy-admin/目录下的文件时使用”。但更可靠的方式是用Claude Code的目录级配置，在项目根目录放一个.claude/skills/，里面的Skill只对该项目生效。

项目层Skill我一般只写两类：兼容性约束（比如“必须兼容IE11，禁止使用可选链和空值合并”）和业务约束（比如“金额字段必须用Decimal类型，禁止用float”）。这两类约束在通用Skill里写不合适，因为只对特定项目有效。

5.5 第五步：迭代，而不是一次写完

四十个Skill不是一天写完的。我的节奏是：第一周五个全局，第二周加三个领域，第三周加五个任务，第四周加两个项目。之后每个月回顾一次，删掉三个月没触发过的Skill，合并功能重叠的Skill，重写触发不准的Skill。

实操心得：我有个习惯是在SKILL.md的frontmatter里加一个last_triggered字段，手动记录最后一次触发的时间。虽然麻烦，但能帮我识别哪些Skill是“僵尸Skill”。三个月没触发的，要么是description写得太窄，要么是这个场景根本不需要Skill。

6. 常见问题与排查技巧实录

6.1 Skill不触发：先查description，再查目录

Skill不触发是最常见的问题。排查顺序我固定为三步：第一步查description是否太泛或太窄，太泛会导致匹配不准，太窄会导致永远匹配不上。第二步查目录结构是否正确，Claude Code只扫描特定目录，放错位置等于没放。第三步查是否有同名Skill冲突，两个Skill的name字段一样会导致其中一个被覆盖。

我遇到过最隐蔽的一次是：Skill的description里用了中文标点，而模型的匹配逻辑对中文标点的处理有问题，导致触发率极低。改成英文标点后恢复正常。这个坑我踩过一次之后就养成了“description里只用英文标点”的习惯。

6.2 Skill乱触发：加否定条件

乱触发比不触发更烦人。我遇到过一个“代码优化”Skill，在我聊任何代码话题时都跳出来，导致模型总是想重构我的代码，哪怕我只是在问一个语法问题。解决方法是在description里加否定条件：“当用户明确要求优化代码时使用，不要在用户只是询问语法或调试时触发。”

否定条件的写法有讲究。不要写“不要在不相关的时候触发”，要写具体的排除场景。比如“不要在用户询问API用法、语法细节、错误信息时触发”。越具体，排除效果越好。

6.3 子agent返回结果不符合预期：检查上下文传递

子agent返回的结果不符合预期，九成是因为主agent传递的上下文不够。子agent的上下文是独立的，它不知道主agent之前聊了什么。如果主agent只传了一句“帮我写个组件”，子agent只能靠猜。

我的做法是：主agent在调用子agent时，必须传递三样东西：任务描述（要做什么）、约束条件（必须遵守什么）、参考示例（照着哪个文件写）。这三样缺一样，子agent的产出质量就下降一截。

6.4 性能问题：Skill太多导致响应变慢

Skill数量超过三十个之后，我明显感觉到响应变慢了。排查后发现是每次对话都要扫描所有Skill的frontmatter做匹配，Skill越多扫描越慢。解决方法是用目录分层，把不常用的Skill放到单独的目录里，需要的时候再临时启用。

另一个优化点是合并低频Skill。我把五个“写文档”相关的Skill合并成了一个，触发率没降，但扫描负担小了很多。合并的原则是：如果两个Skill的触发场景有超过一半的重叠，就合并。

6.5 一个我踩过的大坑：Skill里的代码模板太旧

有一次我写了一个“新增API接口”的Skill，里面附了一个代码模板。那个模板是我半年前写的，用的还是旧版的框架API。结果模型照着模板生成代码，跑不起来。我排查了半天才发现是Skill里的模板过期了。

从那以后我养成了一个习惯：Skill里的代码模板必须和项目里的实际代码保持同步。每次框架升级或者规范调整，第一件事就是更新相关Skill里的模板。我甚至在CI里加了一个检查，如果Skill里的模板文件和项目里的示例文件差异过大，就报警。

7. 四十个Skill之后，我的真实体会

装到四十个Skill之后，最大的变化不是我多了四十个功能，而是我不再需要反复解释同一件事了。以前每开一个新对话，我都要重新说一遍“用函数式组件”“注释写中文”“提交信息用Conventional Commits”。现在这些约束被固化在Skill里，模型自动遵守。我的对话从“解释+要求+纠正”变成了“要求+确认”，效率提升是实打实的。

但我也要泼一盆冷水：Skill不是越多越好。我删掉的Skill至少有十五个，有些是因为场景太低频，有些是因为和其他Skill功能重叠，有些是因为写得太复杂反而导致模型困惑。四十个是我目前找到的平衡点，但你的平衡点可能不一样。关键是定期回顾，把不用的删掉，把不好用的重写。

最后分享一个我最近在用的技巧：给每个Skill写一个“反例”。在SKILL.md的末尾加一段“常见错误做法”，列出三到五个模型容易犯的错。比如React组件的Skill里写“不要用index作为key”“不要在useEffect里直接改state”“不要用useMemo包一个简单计算”。这些反例比正面约束更能纠正模型的行为，因为模型对“不要做什么”的记忆比“要做什么”更深刻。

这个技巧我用了两个月，Skill的遵守率从大概七成提升到了九成以上。如果你也在用Skill，强烈建议试试。