1. 从“能跑就行”到“体系化作战”我为什么开始折腾 Skill用了大半年 Claude Code我一度觉得自己已经把它榨干了。写代码、改 bug、重构模块、生成测试用例日常开发里能想到的场景基本都覆盖了。直到有一次我让它帮我处理一个跨了五个文件的接口重构任务它改完 A 文件忘了 B 文件的类型定义改完 B 文件又把 C 文件的导入路径搞乱了。来回折腾了七八轮最后我手动收尾的时间比我自己从头改还长。那一刻我才意识到一个问题我一直在把 Claude Code 当成一个“更聪明的代码补全工具”在用而不是一个可以体系化协作的 Agent。后来我开始接触 Agent Skills 这个概念花了两周时间陆续给它装上了 40 个 Skill。说实话前 10 个装完的时候我还没什么感觉觉得无非就是多了一些预设提示词。但装到第 20 个、第 30 个的时候整个使用体验发生了质变——它不再是每次都要我从零解释上下文的“陌生人”而更像一个已经熟悉我项目结构、代码风格、甚至踩坑习惯的老搭档。这篇文章不是教程式的“第一步第二步”而是我这两周折腾下来的完整复盘。我会讲清楚 Skill 到底是什么、和子 Agent 有什么区别、SKILL.md 怎么写才有用、40 个 Skill 里哪些是真正值得装的、哪些是凑数的以及我在这个过程中踩过的那些坑。如果你也在用 Claude Code或者正在观望要不要深入折腾希望这些经验能帮你少走点弯路。2. 先把概念理清楚Skill、Agent、子 Agent 到底差在哪2.1 Skill 的本质给 Agent 的“操作手册”很多人第一次听到 Skill 这个词会下意识觉得它是什么插件或者扩展。其实不是。Skill 的本质是一份结构化的指令文档告诉 Claude Code 在特定场景下应该怎么做。你可以把它理解成给一个新员工写的 SOP。没有 SOP 的时候你每次都要口头交代“这个接口要用我们自己的请求封装不要直接用 fetch”“数据库查询记得加缓存层”“错误处理统一走 ErrorBoundary”。有了 SOP新员工第一次就能按规矩来你只需要说“帮我加个接口”就行。Skill 就是这个 SOP。它通常以SKILL.md文件的形式存在里面写清楚了触发条件、执行步骤、注意事项、输出格式。Claude Code 在遇到匹配的场景时会自动读取对应的 Skill 文件按照里面的指令来执行。这里有个关键点Skill 不是代码是自然语言写的指令。这意味着你不需要会写什么特殊的 DSL只要你能把一件事的流程说清楚你就能写一个 Skill。门槛低到离谱但效果上限很高。2.2 子 Agent 和主 Agent 的分工逻辑热词里有个问题被反复提到“cursor 中如何使用子 agent 和主 agent”。这个问题其实触及了 Agent 架构的核心。主 Agent 是你直接对话的那个 Claude Code 实例。它负责理解你的意图、拆解任务、决定要不要调用子 Agent。子 Agent 是主 Agent 派生出来的“临时工”专门处理某个具体子任务处理完就把结果交回来自己销毁。打个比方主 Agent 是项目经理子 Agent 是它临时拉来的专项外包。项目经理不会自己去写每一行代码而是判断“这个任务需要前端改样式、后端加字段、测试补用例”然后分别派给对应的外包去干。Skill 和子 Agent 的关系是Skill 定义了“怎么做”子 Agent 是“谁来做”。一个子 Agent 在执行任务时可以调用多个 Skill。比如一个“重构子 Agent”在处理任务时会调用“代码风格 Skill”“测试覆盖 Skill”“依赖检查 Skill”。我实测下来子 Agent 最大的价值是隔离上下文。主 Agent 的上下文窗口是有限的如果所有细节都堆在主对话里很快就会爆。子 Agent 在自己的独立上下文里干活只把最终结果返回给主 Agent主 Agent 的上下文就能保持干净。2.3 为什么 40 个 Skill 是分水岭我一开始装 Skill 是零散的看到哪个觉得有用就装哪个。前 10 个装完感觉就是“哦方便了一点”。但装到 20 个以上的时候我发现了一个现象Skill 之间开始产生协同效应。举个例子。我装了一个“API 设计规范 Skill”它规定了接口的命名、参数格式、错误码规范。又装了一个“数据库查询 Skill”它规定了查询必须走 Repository 层、必须加索引提示。还装了一个“测试生成 Skill”它规定了测试用例的命名和覆盖要求。单独看每一个都只是省了我几句话。但当它们同时存在时Claude Code 在做一个完整功能时会自动串联这些 Skill先按 API 规范设计接口再按数据库规范写查询最后按测试规范生成用例。整个过程我只需要说一句“帮我加一个用户积分查询接口”它就能端到端产出符合我所有规范的代码。这就是 40 个 Skill 带来的质变从“单点辅助”变成了“体系化协作”。它不再需要我反复交代各种规范因为这些规范已经内化成了它的“肌肉记忆”。3. SKILL.md 怎么写才真正管用我的踩坑与模板3.1 一个合格 SKILL.md 的四个必备模块我前前后后写了三十多个 SKILL.md废掉的有一半。总结下来一个真正管用的 SKILL.md 必须包含四个模块触发条件When to use写清楚什么场景下应该激活这个 Skill。不要写得太宽泛比如“写代码时”这种等于没写。要具体到“当用户要求新增 REST API 接口时”或者“当检测到文件中有 TODO 注释需要处理时”。执行步骤Steps按顺序列出要做的事情。每一步都要具体到可执行不要写“优化代码结构”这种模糊指令要写“检查函数是否超过 50 行如果超过则拆分为多个子函数”。约束条件Constraints明确什么不能做。比如“不要修改现有测试文件”“不要引入新的第三方依赖”“不要改变公开接口的签名”。这些约束是防止 Claude Code 过度发挥的关键。输出格式Output format规定最终产出长什么样。是返回一个 diff、一个完整文件、还是一个总结报告格式要明确否则每次输出都不一样你没法做后续处理。我踩过最大的坑就是触发条件写得太模糊。有一次我写了一个“代码审查 Skill”触发条件写的是“当用户要求审查代码时”。结果 Claude Code 在几乎每次改完代码后都会自动触发这个 Skill因为它觉得“改完代码应该审查一下”。后来我把触发条件改成“仅当用户明确说出‘审查’或‘review’关键词时”才解决了这个问题。3.2 触发条件的设计精准比宽泛重要十倍触发条件的设计直接决定了 Skill 是帮你还是烦你。我的经验是宁可写窄不要写宽。窄了最多是不触发你手动喊一声就行。宽了会到处乱触发干扰正常流程反而降低效率。具体怎么写我总结了一个公式触发条件 用户意图关键词 场景上下文 排除条件举个例子## When to use - 用户消息中包含“重构”“refactor”“优化结构”等关键词 - 且当前操作的文件是 .ts 或 .tsx 文件 - 且不是新建文件新建文件走“新文件创建 Skill” - 排除如果用户明确说“只改一行”或“快速修复”不触发本 Skill这样写下来触发精度会高很多。我实测下来加了排除条件之后误触发率从大概 30% 降到了 5% 以下。3.3 步骤拆解的颗粒度多细才算够步骤拆解的颗粒度是个需要反复调试的事情。太粗了 Claude Code 会自由发挥太细了又显得啰嗦而且容易在细节上卡住。我的经验法则是每个步骤应该是一个“可验证的动作”。也就是说做完这一步你能明确判断它做对了没有。比如“处理错误”这个步骤就太粗了没法验证。“检查每个异步调用是否有 try-catch 包裹如果没有则添加catch 块中统一调用 logger.error 并返回标准错误格式”就足够具体做完之后你能一眼看出对不对。但也不要细到“在第 3 行和第 7 行之间插入一个空行”这种程度。这种细节 Claude Code 自己会处理你写进去反而限制了它的灵活性。我一般会把一个 Skill 的步骤控制在 5 到 12 步之间。少于 5 步说明这个 Skill 太简单可能不值得单独写。多于 12 步说明这个 Skill 太复杂应该拆成两个。3.4 我常用的 SKILL.md 模板下面是我经过多次迭代后固定下来的模板直接可以抄# Skill: [Skill 名称] ## When to use - [触发条件 1] - [触发条件 2] - 排除[排除条件] ## Steps 1. [步骤 1具体可验证] 2. [步骤 2具体可验证] 3. [步骤 3具体可验证] ## Constraints - 不要 [约束 1] - 不要 [约束 2] - 必须 [强制要求] ## Output format [描述输出格式如 diff、完整文件、总结报告] ## Examples [可选给一两个输入输出示例]这个模板看起来简单但每个模块都有讲究。特别是 Constraints 和 Output format很多人写 Skill 时会忽略这两个结果就是 Claude Code 每次执行的结果都不一样你没法做自动化处理。4. 40 个 Skill 的实战分类哪些真香哪些吃灰4.1 代码质量类装了就回不去的前 5 个这类 Skill 是我装完之后使用频率最高的基本上每天都会触发。第一个是“命名规范 Skill”。它规定了变量用 camelCase、常量用 UPPER_SNAKE_CASE、组件用 PascalCase、文件用 kebab-case。听起来很简单但之前 Claude Code 经常混用一会儿getUserInfo一会儿get_user_info。装了这个 Skill 之后命名一致性直接拉满。第二个是“导入排序 Skill”。它规定了导入语句的分组顺序先 React 相关再第三方库再项目内部模块最后样式文件。每组之间空一行。这个 Skill 装完之后我再也没手动整理过导入。第三个是“错误处理 Skill”。它规定了所有异步操作必须有错误处理错误必须被记录用户可见的错误必须友好。这个 Skill 帮我抓出了好几个之前遗漏的边界情况。第四个是“类型定义 Skill”。它规定了接口类型必须定义在types/目录下类型命名必须加I前缀或Type后缀禁止使用any。这个 Skill 让我的 TypeScript 项目类型覆盖率从 70% 提到了 95% 以上。第五个是“注释规范 Skill”。它规定了公开函数必须有 JSDoc 注释复杂逻辑必须有行内注释注释必须用中文。这个 Skill 让代码可读性提升了一个档次。这五个 Skill 我建议所有人都装不管你是写前端还是后端不管你是用 TypeScript 还是 Python命名、导入、错误、类型、注释这五件事是通用的。4.2 工作流类让 Claude Code 自己管自己这类 Skill 的价值在于自动化流程让 Claude Code 在特定节点自动做某些事情不需要你手动触发。**“提交前检查 Skill”**是我最满意的之一。它规定在每次 git commit 之前自动运行 lint、type check、单元测试。如果任何一项失败就阻止提交并报告问题。装了这个之后我再也没有提交过带 lint 错误的代码。**“PR 描述生成 Skill”**也很实用。它规定在创建 Pull Request 时自动根据 commit 历史生成结构化的 PR 描述包括变更摘要、影响范围、测试计划。之前我每次写 PR 描述都要花十分钟现在基本一键生成。**“变更日志 Skill”**规定在每次发布版本时自动从 commit 历史中提取变更内容按 feat、fix、refactor 分类生成 CHANGELOG。这个 Skill 让我维护变更日志的成本降到了零。**“依赖更新检查 Skill”**规定每周一自动检查 package.json 中的依赖是否有新版本列出可更新的依赖和潜在风险。这个 Skill 帮我及时发现了好几个安全更新。这类 Skill 的特点是触发时机明确不需要你主动调用到了特定节点自动执行。装完之后你会感觉 Claude Code 像一个有自我管理能力的助手而不是一个需要你时刻盯着的工具。4.3 领域专用类数学建模、论文、文献检索的 Skill 实践热词里提到了“数学建模 skill”“论文 skill”“codex 用的检索文献 skill”说明很多人有领域专用的需求。我也装了几个这类 Skill效果出乎意料地好。**“数学建模 Skill”**是我帮一个做算法的朋友写的。它规定了建模流程先明确问题和假设再选择模型类型再推导公式最后验证结果。每一步都有具体的检查清单。朋友反馈说之前 Claude Code 做数学建模经常跳步装了这个 Skill 之后推导过程完整多了。**“论文写作 Skill”**规定了学术写作的规范摘要必须包含背景、方法、结果、结论四要素引言必须包含研究问题和贡献点参考文献必须用指定格式。这个 Skill 让论文初稿的质量提升明显。**“文献检索 Skill”**规定了检索策略先用关键词检索再根据结果调整关键词再筛选高引用文献最后整理成结构化摘要。这个 Skill 帮我节省了大量文献调研时间。领域专用 Skill 的写法和其他 Skill 不太一样它需要你把领域内的隐性知识显性化。比如数学建模里“先明确假设”这件事对老手来说是常识但对 Claude Code 来说需要明确写出来它才会做。4.4 那些我装了又卸掉的 Skill反面教材不是所有 Skill 都值得装。我装了又卸掉的有这么几类过度约束类。有一个“代码风格 Skill”我写得特别细规定了每行最多 80 字符、函数最多 3 个参数、嵌套最多 2 层。结果 Claude Code 为了满足这些约束把很多简单逻辑拆得七零八落可读性反而下降了。后来我把约束放宽到“建议”级别问题才解决。触发太频繁类。有一个“代码审查 Skill”触发条件写得太宽几乎每次改代码都会触发导致 Claude Code 改完一行就审查一遍效率极低。后来我把触发条件改成手动触发才恢复正常。和其他 Skill 冲突类。有两个 Skill 对同一个事情的规定不一致比如一个说“错误必须抛出”另一个说“错误必须捕获并返回默认值”。结果 Claude Code 每次遇到错误处理都犹豫不决输出不稳定。后来我合并了这两个 Skill统一了规定。太抽象类。有一个“代码质量 Skill”我写的是“确保代码高质量”没有任何具体标准。结果 Claude Code 完全不知道该怎么执行每次都是敷衍了事。后来我把它拆成了五个具体的 Skill才有实际效果。这些反面教材给我的教训是Skill 不是越多越好而是越精准越好。一个精准的 Skill 胜过十个模糊的 Skill。5. 从安装到调优我的完整实操流程5.1 安装 Skill 的三种方式与选择建议安装 Skill 主要有三种方式我分别试过各有适用场景。第一种是手动创建。在项目的.claude/skills/目录下新建一个文件夹里面放SKILL.md文件。这种方式最灵活适合你自己写的自定义 Skill。我大部分 Skill 都是这么装的。第二种是从 GitHub 仓库导入。热词里有人问“claude code 怎么手动装 github 上的 skills”其实就是把别人的 Skill 仓库克隆下来把SKILL.md文件复制到你的 skills 目录。这种方式适合用别人写好的通用 Skill比如一些开源的代码规范 Skill。第三种是通过 Skill 管理工具。有些第三方工具可以帮你管理 Skill 的安装、更新、卸载。我试过一两个感觉目前还不够成熟经常出现版本冲突。如果你 Skill 数量不多手动管理就够了。我的建议是核心 Skill 自己写通用 Skill 从社区拿管理工具暂时观望。自己写的 Skill 最贴合你的项目社区 Skill 可以补充一些通用规范管理工具等生态成熟了再用。5.2 让 Skill 生效的关键配置项装完 Skill 之后有几个配置项必须检查否则 Skill 可能不生效。第一是 Skill 目录路径。Claude Code 默认会读取项目根目录下的.claude/skills/目录。如果你把 Skill 放在别的地方需要在配置文件中指定路径。我一开始就是把 Skill 放在了docs/skills/下结果一直不生效找了半天才发现是路径问题。第二是 Skill 的启用状态。有些 Skill 默认是禁用的需要在配置中手动启用。特别是那些触发频繁的 Skill默认禁用可以避免干扰。第三是 Skill 的优先级。当多个 Skill 同时匹配时优先级决定了哪个先执行。我一般把“约束类 Skill”的优先级设高确保约束先生效再执行具体操作。第四是上下文窗口配置。Skill 会占用上下文窗口如果装太多 Skill可能导致主对话的可用上下文变小。我一般会把不常用的 Skill 设为“按需加载”只在触发时才读取。5.3 参数调优触发阈值、上下文窗口、优先级Skill 装好之后调优是个持续的过程。我主要调三个参数触发阈值。有些 Skill 的触发条件可以设置置信度阈值比如“当匹配度超过 80% 时才触发”。调高阈值可以减少误触发但可能漏掉一些该触发的情况。我一般从 70% 开始根据实际效果调整。上下文窗口。每个 Skill 可以设置自己的上下文窗口大小。复杂的 Skill 需要更大的窗口来读取更多项目文件简单的 Skill 可以设小一点节省资源。我一般把代码审查类 Skill 的窗口设大命名规范类 Skill 的窗口设小。优先级。前面说过优先级决定执行顺序。我一般按这个顺序排约束类 规范类 操作类 报告类。约束先生效确保不越界规范其次确保风格一致操作再次执行具体任务报告最后输出结果。调优这件事没有标准答案需要根据你的项目特点和使用习惯来。我建议每装一批新 Skill 后花一两天观察效果根据实际情况调整参数。5.4 实测效果装 Skill 前后的效率对比说几个具体的数据。我记录了自己在装 Skill 前后处理同类任务的时间任务类型装 Skill 前装 Skill 后提升幅度新增一个完整 API 接口约 25 分钟约 8 分钟约 68%重构一个模块约 40 分钟约 15 分钟约 62%修复一个跨文件 bug约 30 分钟约 12 分钟约 60%生成单元测试约 20 分钟约 6 分钟约 70%代码审查约 15 分钟约 5 分钟约 67%这些数据是我自己记录的不一定适用于所有人但趋势是明显的装 Skill 之后处理同类任务的时间普遍减少了 60% 以上。主要节省在“反复交代规范”和“来回修正”这两个环节。当然前期写 Skill 和调优也花了不少时间。我大概花了 20 个小时写和调这 40 个 Skill。但考虑到每天都能节省一两个小时一周就回本了。6. 常见问题与排查技巧实录6.1 Skill 不生效的五个排查方向Skill 不生效是最常见的问题。我遇到过好几次总结下来有五个排查方向第一检查文件路径。确认SKILL.md文件在正确的目录下文件名大小写正确。我遇到过因为文件名写成skill.md而不是SKILL.md导致不生效的情况。第二检查文件格式。确认SKILL.md是合法的 Markdown 格式没有语法错误。特别是 YAML front matter 部分格式错误会导致整个文件无法解析。第三检查触发条件。确认你的输入确实匹配了 Skill 的触发条件。有时候你以为匹配了但实际上差了一个关键词。可以临时把触发条件放宽测试是否能触发。第四检查优先级冲突。确认没有其他 Skill 的优先级更高把你要的 Skill 覆盖了。可以临时禁用其他 Skill单独测试。第五检查配置。确认 Skill 在配置中是启用状态且路径配置正确。有时候配置文件改了但没重启导致不生效。6.2 Skill 之间冲突了怎么办Skill 冲突的表现是Claude Code 在执行时犹豫不决或者输出结果不稳定每次都不一样。解决冲突的方法有三种第一种是合并。如果两个 Skill 对同一件事的规定不一致把它们合并成一个 Skill统一规定。这是最彻底的解决方法。第二种是分层。如果两个 Skill 管的是不同层面的事情可以设置优先级让一个先执行另一个后执行。比如“代码风格 Skill”和“代码审查 Skill”风格先执行审查后执行。第三种是排除。如果两个 Skill 确实无法共存可以在触发条件中互相排除。比如“快速修复 Skill”和“完整重构 Skill”在快速修复的触发条件中排除“重构”关键词。我一般优先用合并其次用分层最后才用排除。排除会导致一些场景下两个 Skill 都不触发需要手动处理。6.3 上下文窗口不够用的优化策略装太多 Skill 之后上下文窗口会变得紧张。我的优化策略有四个第一按需加载。把不常用的 Skill 设为按需加载只在触发时才读取。这样平时不占用上下文。第二精简 Skill 内容。把 Skill 中不必要的内容删掉只保留核心指令。我一般会把 Skill 控制在 500 字以内。第三拆分复杂 Skill。如果一个 Skill 太长把它拆成多个小 Skill按需组合。第四定期清理。每隔一段时间检查一下 Skill 列表把不再使用的 Skill 删掉。我每个月会清理一次一般能删掉 5 到 10 个。6.4 常见问题速查表问题现象可能原因解决方法Skill 完全不触发路径错误或文件格式错误检查路径和 Markdown 格式Skill 触发太频繁触发条件太宽泛收窄触发条件加排除条件Skill 输出不稳定和其他 Skill 冲突合并或分层处理Skill 执行到一半卡住步骤太复杂或上下文不足拆分 Skill 或增大上下文窗口Skill 效果不如预期步骤不够具体细化步骤增加可验证性装了 Skill 后变慢Skill 太多占用资源按需加载定期清理6.5 我的独家避坑心得最后分享几个我在实操中总结的避坑心得心得一先写一个 Skill 试水不要一次性写 40 个。我一开始就是一次性写了 20 个结果大部分都有问题调试起来非常痛苦。后来改成一次写 3 到 5 个用一周时间调优再写下一批效率高多了。心得二每个 Skill 都要有“不做什么”的约束。只写“做什么”的 Skill 容易让 Claude Code 过度发挥。加上“不做什么”的约束输出会稳定很多。心得三定期回顾 Skill 的使用频率。我每个月会统计一次每个 Skill 的触发次数触发次数低于 3 次的就考虑删掉。这样能保持 Skill 列表的精简。心得四把 Skill 当成代码来管理。用 Git 管理 Skill 文件每次修改都提交出问题了可以回滚。我吃过没版本管理的亏改坏了一个 Skill 之后找不回原来的版本。心得五不要迷信别人的 Skill。网上有很多人分享 Skill但别人的 Skill 不一定适合你的项目。我试过几个热门 Skill效果都不如我自己写的。核心原因是我自己的 Skill 最了解我的项目结构和代码风格。心得六Skill 的命名要见名知意。我一开始用skill-01、skill-02这种命名后来完全记不住哪个是哪个。改成naming-convention、error-handling这种描述性命名之后管理起来清晰多了。心得七给 Skill 写测试用例。每个 Skill 写完后我会准备几个测试输入验证它是否按预期触发和执行。这个习惯帮我提前发现了很多问题。心得八Skill 不是一劳永逸的。项目在变代码规范在变Skill 也需要跟着更新。我一般每季度会全面回顾一次所有 Skill该更新的更新该删的删。心得九不要用 Skill 做它不擅长的事。Skill 擅长的是“流程规范”和“重复操作”不擅长的是“创造性设计”和“复杂决策”。把创造性的事情留给主 AgentSkill 只负责规范执行。心得十享受折腾的过程。写 Skill 本身就是一个梳理自己工作流程的过程。我在写 Skill 的过程中发现自己之前很多操作其实是不规范的写 Skill 逼着我把这些规范明确下来对我自己的代码质量也有提升。这 40 个 Skill 折腾下来最大的收获不是效率提升了多少而是我对“怎么和 AI 协作”这件事有了全新的理解。之前我是把 Claude Code 当成一个工具现在更像是把它当成一个需要培训的团队成员。你投入多少精力去“培训”它它就能回报你多少效率。这个投入产出比在我试过的所有效率工具里是最高的。