当初我刚开始接触 Claude Code 时最让我困惑的并不是它的对话能力而是“如何让它稳定地按我想要的流程办事”。每次临时在提示词里塞一堆规则当时有效换个场景又得重新说一遍后来把规则写进系统提示词倒是统一了但全局生效又让无关任务被拖慢。直到我把技能Skills加载这一套吃透才算真正把 Claude Code 从“聊天助手”用成了“团队实习生”。这篇第五课我就把自己在项目里反复打磨技能加载的经验完整拆出来从加载机制、目录规范到实际编写、踩坑排查一条龙讲清楚。1. 定位与设计思路Skills 到底解决了什么问题1.1 技能是什么——把散落的提示词沉淀为可复用能力很多刚上手 Claude Code 的同学会把技能理解成“高级一点的提示词文件”。这个说法对了一半。技能确实以 Markdown 文件为主要载体但它和普通提示词最大的区别在于技能是一套完整的、可被按需加载的“能力包”。它不只是告诉模型“你要做什么”还规定了“按什么顺序做、调用什么工具、参考什么资料、输出什么格式”。换句话说普通提示词是你在现场口述需求技能则是提前写好的一份岗位说明书模型在接到对应任务时自己会去翻这份说明书并按章执行。我在某个跨平台系统项目里需要频繁对多个服务的日志做异常分析。最初的做法是把分析规则复制粘贴到每次对话里后来规则从 5 条涨到 20 多条粘贴一次要占大量上下文窗口还经常贴错版本。把规则沉淀成“日志分析技能”之后我只需要在对话里说一句“用日志分析技能看下今天的报错”Claude Code 就会自动加载对应的 SKILL.md按里面的步骤让我提供日志路径、指定分析维度、调用脚本提取特征最后按固定模板输出结论。整个过程不再依赖我每次记住规则细节技能本身就是唯一的事实来源。这套机制特别适合三类人一是像我这样需要频繁做同类任务的开发者二是团队里想统一编码规范、评审流程的技术负责人三是想把个人经验固化下来、避免“人走经验流失”的长期项目维护者。技能加载解决的核心痛点很明确让模型的行为可预期、可复用、可维护。1.2 技能与 MCP、插件的边界怎么划说到可扩展性很多同学会立刻联想到 MCP模型上下文协议或者 IDE 插件。我最初也以为技能会被 MCP 取代实际用下来发现两者是互补关系职责完全不同。MCP 解决的是“模型能触达哪些外部世界”比如连数据库、查工单、读对象存储本质是给模型开了一组新的 API 通道。插件解决的是“编辑器/终端环境里怎么更方便地操作”比如一键侧边栏、快捷键绑定。而技能解决的是“模型面对特定任务时该怎么思考和行动”它既可以把 MCP 工具串联进流程也可以单独使用内置的 Shell、文件读写等工具去完成一个逻辑完整的任务。我用一个项目里的真实配置说明。当时我做一个“代码变更影响面分析”技能里面用到了 Git 命令来获取 diff用文件搜索工具定位引用关系最后还调用了内部的知识库 MCP 工具来补充背景信息。这个技能的 SKILL.md 里并没有发明任何新工具它只是把已有能力组合成了一个固定的分析流程。如果只用 MCP我依然需要每次手动告诉模型“先查 diff 再搜引用最后查知识库”但如果只靠技能而没有 MCP 通道知识库信息就拿不到。所以我的建议是技能是“流程编排层”MCP/插件是“能力供给层”。先想清楚你要固化什么流程再看流程里缺哪些外部能力缺的用 MCP 补流程本身用技能管。这三层叠在一起才是完整的一套可扩展架构。2. 加载机制拆解技能包从哪里读取、如何被触发2.1 技能目录规范项目级与用户级的两种放置方式技能加载的第一步是让 Claude Code 知道技能包存在。默认情况下它会在两个位置扫描技能目录项目级目录和工作区根目录下的.claude/skills/以及用户级目录~/.claude/skills/。项目级技能对当前仓库生效适合存放与业务强相关的流程用户级技能对你所有的项目生效适合存放通用的编码规范、通用检查清单。技能包本身是一个文件夹文件夹名一般建议用短横线分隔的英文比如code-review、log-analysis。文件夹内至少要有一个SKILL.md文件这是技能的入口和说明书还可以附带脚本、模板、参考文档等辅助文件。加载器只认SKILL.md技能包里的其他文件不会被当作独立技能加载它们只是执行过程中可以被读取或调用的资源。下面是一个最小可用的技能包结构.claude/skills/ └── log-analysis/ ├── SKILL.md ├── scripts/ │ └── extract_errors.py └── templates/ └── report_template.md这里有个容易踩的坑技能目录名称里最好不要有空格和中文。虽然某些版本可能兼容但空格会导致加载器在解析路径时出现意外的匹配失败。我最早把技能文件夹命名为“日志分析 v2”结果死活加载不出来改成log-analysis-v2后一切正常。如果你在别人的项目里看到既有中文目录名也能用的案例多半是因为文件系统的编码转换恰好掩盖了问题不要拿自己的稳定性去赌这种兼容性。2.2 SKILL.md 的书写要点给模型看的“操作手册”SKILL.md 是技能加载的核心它由两部分组成开头的 YAML 元信息和正文指令。元信息里最重要的字段是name和description这两个字段直接决定了技能会不会被模型“想起来”。加载器会在会话初始化时扫描技能目录把每个技能的name和description汇总成一份清单之后模型会根据用户当前请求和这份清单做匹配匹配到才加载对应 SKILL.md 正文。我写 description 的经验是不要写形容词要写“场景 触发条件 效果”。比如“适用于代码审查场景当用户要求检查代码质量、评审合并请求、分析改动风险时使用。执行后输出结构化评审报告。”这种描述既包含了触发词也说明了技能能产出的结果匹配成功率明显高于干巴巴的一句“代码审查技能”。描述长度控制在 100 到 200 字比较好太短信息不足太长会稀释关键词权重影响匹配精度。正文部分则要像给新同事写操作手册一样分步骤、说清楚输入输出、给出判断标准。模型会按正文指令逐步执行所以正文里每一步都要具体。比如“第一步运行 git diff 获取当前分支的改动第二步仅筛选 .py、.ts 文件的变更第三步针对每个变更文件按附录中的检查清单逐项评估”。如果你只在正文里写“请检查代码质量”那等于没写因为模型不知道你的“质量”标准是什么。2.3 完整加载链路五个阶段逐一说明技能从“存在磁盘上”到“真正影响模型行为”需要经过五个阶段理解这条链路对排查问题非常重要。第一阶段是启动扫描。Claude Code 在项目目录启动或会话初始化时会扫描上述两个技能目录识别出所有包含合法SKILL.md的技能包并解析 YAML 元信息。第二阶段是清单注入。加载器会把所有技能的name和description整理成一份技能清单注入到模型上下文中。第三阶段是触发匹配。模型在理解用户当前请求后对照这份技能清单做判断决定是否需要加载某个技能。第四阶段是按需加载。一旦匹配成功加载器把对应的SKILL.md全文以及技能包内的关键文件路径注入上下文模型开始按正文指令规划执行。第五阶段是执行与反馈。模型执行完技能流程后会返回结果一些实现里还会把执行记录写回日志便于复盘。从这个链路能看出一个关键点技能正文并不会常驻上下文只有匹配成功后才加载。这样设计是为了节省上下文窗口但也意味着如果你的 description 写得不到位技能就永远不会被唤醒。我见过有人辛辛苦苦写了 500 行 SKILL.md结果因为 description 里描述过于泛化模型始终没匹配上技能形同虚设。所以调技能第一步不是调正文而是调 description。3. 实操复现5 步做出并加载一个代码评审技能3.1 目标拆解与技能包骨架纸上谈兵没意思我拿实际项目里的“代码评审技能”作为例子完整走一遍从创建到加载的流程。这个技能的目标很明确当用户要求评审代码或检查合并请求时自动提取 Git 改动、按团队规范逐项检查、输出带风险等级的评审结论。先拆解任务步骤第一步获取改动范围包括分支对比、暂存区状态第二步筛选需要评审的文件类型第三步按检查清单逐项扫描代码包括错误处理、性能隐患、安全漏洞、命名规范、重复代码第四步对每个问题标注严重级别第五步输出评审报告包含总体结论、问题列表、修改建议。根据这个设计技能包骨架如下.claude/skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ ├── get_diff.sh │ └── check_todo.py └── docs/ └── review_checklist.md脚本是可选的但强烈建议放。因为模型在终端环境里执行 Shell 命令时复杂的管道命令容易出错把逻辑封装成脚本能让技能更稳定。我在get_diff.sh里封装了分支差异获取逻辑避免模型每次现场拼命令。3.2 编写 SKILL.md把评审标准转译成模型指令SKILL.md 的 YAML 部分我是这样写的--- name: code-review description: 适用于代码评审场景。当用户要求审查代码质量、评估合并请求风险、检查某个提交或分支的改动或要求执行团队代码规范检查时使用。技能会提取 Git 差异、按检查清单逐项评估并输出带风险等级的结构化评审报告。 ---正文部分按操作手册的风格组织开头先交代技能目标和前置条件然后分步骤列出执行流程。关键步骤我会写得非常细比如“筛选文件”这一步我会明确列出包含哪些扩展名、排除哪些目录# 代码评审技能 ## 目标 对当前分支或指定提交的代码变更执行一次结构化评审输出风险等级明确、可直接执行的改进建议。 ## 前置条件 - 确认当前处于 Git 仓库内 - 明确评审范围默认评审当前分支与主分支的差异 ## 执行步骤 1. 确定评审范围 - 若用户指定了提交 ID则以该提交的变更集为准 - 否则运行 scripts/get_diff.sh 获取当前分支与主分支的差异 2. 筛选变更文件 - 仅评审以下类型.py、.ts、.js、.tsx、.jsx、.go、.java - 排除 lock 文件、生成目录dist、build、node_modules、配置文件.json、.yaml 3. 逐项检查对照 docs/review_checklist.md - 错误处理是否有裸异常、关键路径是否缺 try-catch、失败时是否有降级方案 - 安全风险是否出现硬编码密钥、未过滤的用户输入拼接、危险反序列化 - 性能隐患是否存在 N1 查询、循环内发起 IO、未限制的集合拷贝 - 可维护性命名是否体现意图、函数是否过长、是否存在重复逻辑 4. 输出格式 - 总体结论通过 / 有条件通过 / 不通过 - 问题列表按严重级别排序每项标注文件、行号、问题描述、修改建议我在正文里尽量使用“若…则…”的条件句式这样模型在遇到边界情况时有明确的决策依据不会自己发挥。实际测试中没有给足判断标准的正文模型的评审结论经常出现“看情况”这种模糊表述加上标准之后输出明显更果断。3.3 添加辅助脚本让技能拥有真实执行能力脚本不是锦上添花是技能稳定性的保障。我写get_diff.sh时最朴素的想法是与其让模型记一串复杂的 git 命令不如让它只记得“运行这个脚本”。这样即使模型对 Git 命令的某些参数记忆模糊技能依然能用。#!/usr/bin/env bash # 获取当前分支与主分支的差异输出按文件分组的变更摘要 set -euo pipefail base_branch${1:-origin/main} target_branch${2:-HEAD} echo 评审范围 echo 基础分支: ${base_branch} echo 目标分支: ${target_branch} echo echo 变更文件列表 git diff --name-only ${base_branch}...${target_branch} echo echo 差异摘要 git diff --stat ${base_branch}...${target_branch} echo echo 关键代码差异 git diff --unified5 ${base_branch}...${target_branch} -- *.py *.ts *.tsx *.js *.ts :!**/dist/** :!**/node_modules/**脚本里用set -euo pipefail是我和模型一起踩过坑之后才加上的。如果没有这个某条 git 命令在非 Git 目录执行失败时脚本不会立即退出后续逻辑照样往下跑最后输出一份残缺的差异报告。另外我特意用origin/main作为默认基础分支这个默认值根据团队习惯来定有些团队用origin/master有些用origin/develop一定要在技能里跟用户确认或者允许用户传入否则会拿错基线。3.4 加载验证从初次调用到跑通全流程技能写好之后验证加载是否成功是必不可少的一步。我在项目目录下启动 Claude Code然后输入一句并不完全匹配的请求测试描述里的触发词能不能生效我输入“帮我看下当前分支的代码有没有问题。”这句话里没有出现“评审”“审查”这些词但包含了“代码有没有问题”这个意图。模型通过技能清单里的描述匹配到了code-review技能于是加载 SKILL.md提示我确认评审范围接着调用get_diff.sh获取差异按清单逐项检查最后输出了评审报告。从输出结果看报告里包含了变更文件列表、三个问题项以及各自的风险等级说明整个技能链路是通的。这时候我要特别强调一个验证技巧不要一上来就测试精确指令先测模糊指令。因为精确指令比如“执行 code-review 技能”会让模型直接去找名为 code-review 的技能这相当于开卷考试而模糊指令才是日常使用的真实场景能检验 description 的匹配质量。如果模糊指令没能触发技能优先改 description 里的触发场景描述而不是去改正文内容。4. 调优三板斧触发召回、执行权限、多技能协作4.1 控制技能召回率description 怎么写更“招之即来”技能加载的体验很大程度上取决于召回的准确率。召回率太高稍微沾点边的请求就会加载技能浪费上下文还拖慢响应召回率太低用户明确表达了需求模型却当成普通对话处理。我在调优阶段总结出 description 书写的几个关键点。第一要写“技能不适用什么”的情形。很多人以为 description 只写适用场景就行实际上把排除场景写进去同样重要。比如我有个“部署发布技能”它只在用户要求发布上线时触发但如果用户只是问“当前环境配了哪些变量”就绝不该加载部署流程。我在 description 里加了“仅当需要执行发布相关操作时使用若用户仅询问配置信息不应匹配本技能”这之后误触发的次数明显下降。第二把同义词和口语化表达写进去。模型理解能力很强但它需要线索。如果你想覆盖“审查代码”这个场景除了“代码审查”“代码评审”还可以写上“帮我看看这段改得怎么样”“检查一下这次提交”。这些来自真实用户习惯的表达比正式的术语更容易触发匹配。第三控制描述长度。我试过把 description 写到 300 字结果不仅匹配不精准还占用了不少上下文额度。后来压到 120 字左右只保留场景、触发条件、输出效果三个要素效果反而更好。这就好比给人发工作简介写得太长反而抓不住重点。4.2 执行边界与权限让技能只做该做的事技能一旦被加载模型就拥有了执行整个流程的“指令依据”但并不是所有技能都应该拥有全部工具权限。我在实践里踩过一次深刻的坑某个技能脚本里包含清理临时文件的操作结果一次误触发把项目构建目录给删了。从那以后我做任何技能都会先明确“这个技能不应该做什么”。在 SKILL.md 正文里我会显式列出禁止事项。比如代码评审技能里我写了“禁止修改任何源码文件禁止运行构建命令禁止推送分支”。这些禁止指令虽然不能做到系统级的强制约束但在模型执行技能时的优先级很高能有效阻止常见的越权操作。如果你的运行环境支持更细粒度的工具权限配置我强烈建议把技能需要用的工具范围圈定出来只给最小权限集合。还有一类边界是数据边界。有些技能会读取敏感信息比如日志分析技能可能要读取包含业务数据的日志文件。我在技能正文里要求模型在读取前先确认文件路径并且在输出报告中移除可能的敏感字段比如手机号、token、密钥。技能不是法外之地数据安全约束写得越早后面收拾烂摊子的成本越低。4.3 多技能协作与冲突处理当技能数量超过五个之后一个新的问题浮现出来多个技能的 description 可能会有重叠导致同一个请求命中两三个技能模型不知道该优先执行哪个。我遇到过“代码评审技能”和“重构建议技能”同时被触发的情况两个技能给出的建议方向完全不同模型纠结了很长时间最后输出了一份混搭的结论。解决重叠问题我用的方法是给技能设置明确的分级与边界。在各自的 description 里声明优先级如果用户请求包含重构诉求应优先使用“重构建议技能”如果仅要求对现有代码做质量评估则使用“代码评审技能”。另外一种方案是干脆把两个技能合并成一个在正文里按分支流程处理不同诉求。这里没有标准答案取决于你希望技能粒度细还是粗。我个人的经验是技能粒度宁粗勿细一个技能如果能覆盖一类完整任务闭环就别拆成多个半截技能。还有一个容易忽略的点技能之间的引用。一个技能可以显式调用另一个技能吗在实际使用中是可以的你只需要在正文里写明“若用户需要了解日志格式请加载 log-format-reference 技能”。模型会像查资料一样在需要的时候按名字搜索并加载对应技能。这种层级化设计适合更复杂的任务体系比如一个项目级总控技能下面挂多个子技能。但层级不要超过三层否则加载链路会变得难以追踪排查问题时你会怀疑人生。5. 踩坑实录技能“不加载”“乱执行”“多冲突”的排查方法5.1 技能未被识别三个高频原因我整理了实战里最常见的三个导致技能“失效”的原因每一个都是我或者同事真实遇到过的。第一个原因是技能目录名称不规范。前面提到过目录名里的空格、特殊字符、中文都可能导致加载器解析异常。有个同事的项目里技能目录叫analysis-tool-final-2看起来没问题吧但他在 YAML 里的 name 写的是Analysis Tool Final空格在元信息里倒是合法可是模型通过 name 去匹配技能时带了空格的名字和用户请求的关键词之间匹配效果很差造成技能时常不被触发。后来我把 name 统一改成小写短横线风格问题就消失了。第二个原因是 SKILL.md 的 YAML 元信息解析失败。最常见的是 description 里有特殊字符没有转义比如引号冒号或者 YAML 里的冒号后面没有空格。这些错误会导致整份 SKILL.md 被跳过而且不会有明确报错。我的排查办法是先手动解析把 SKILL.md 里的 YAML 复制到在线解析工具里看能否解析成功。只要 YAML 合法加载器基本不会跳过。第三个原因是技能目录位置放错。我一直以为技能放在项目根目录下的skills/就行后来才发现 Claude Code 只认.claude/skills/这个约定目录。仔细看文档复盘时发现不同版本甚至不同部署模式的默认扫描目录会有差异有的会额外扫描.claude/skills之外的其他路径但不能默认依赖这些差异。最稳妥的方式是启动后先问一下模型“现在可用哪些技能”让它列出来看看你的技能在不在清单里这一步是排查一切加载问题的起点。5.2 执行途中报错脚本、路径与上下文问题技能加载成功不等于执行成功真正的问题往往在执行阶段。我在测试日志分析技能时遇到过一个典型的报错模型按照 SKILL.md 指令去运行脚本但脚本里用了相对路径而模型的工作目录和技能包目录并不是同一个位置导致找不到文件。解决方案是在脚本开头显式切换到技能包所在的绝对路径或者在技能正文里明确规定所有资源文件必须基于技能包目录进行定位。另一个常发生在执行阶段的问题是模型对长步骤的记忆偏差。当技能正文包含 8 个以上步骤时模型可能在执行到第 5 步时忘记了第 2 步的约束条件比如我在前面限制了“仅评审 .py 和 .ts 文件”但模型到后面又去评审了 .json 文件。这种问题我到现在也没有完美解法最有效的缓解措施是让脚本承担更多过滤逻辑把判断交给代码而不是只靠模型记忆。比如我在get_diff.sh里已经用-- *.py *.ts限制了 diff 输出范围模型即使想跑偏拿到的数据范围也是被过滤过的。还有一类问题是上下文长度。技能包的辅助文件如果很大比如参考文档有几十万字符模型加载时会把全文塞进上下文不仅拖慢响应还可能导致后续对话直接挤爆上下文窗口。解决方案是把大文档拆成小模块SKILL.md 里只写关键的摘要和索引需要细节时再让模型按需读取对应的文档片段。5.3 常见异常速查表我把调试技能过程中碰到的常见异常整理成一张速查表方便大家对照排查。现象可能原因排查动作技能从未被触发description 缺少触发场景描述用模糊口语指令测试重写 description技能偶尔被触发描述与用户请求匹配率低补充同义词和排除场景精简描述长度启动时报错但无法定位技能SKILL.md YAML 解析失败单独解析 frontmatter检查特殊字符技能不出现可用清单里目录位置不对或名称不合规确认.claude/skills/路径检查目录名脚本执行报“文件不存在”相对路径问题在脚本内使用绝对路径或基于技能包目录定位模型执行步骤遗漏正文步骤太多模型记忆偏差减少步骤数把逻辑放进脚本技能间互相干扰description 重叠导致多匹配增加优先级声明合并同类技能加载后响应太慢辅助文档过大占用上下文拆分文档正文只留索引和摘要这张表我建议直接贴在项目文档里遇到问题先查表能省下大量对着日志发呆的时间。最后再分享一个我个人坚持的实践习惯每次新写一个技能我都会先建一个一个测试用的临时项目在里面放一个最小样本文件然后用至少三句不同风格的话去触发同一个技能看它是否都能稳定加载、稳定执行。这个习惯帮我提前发现了很多“凑巧能用”的隐患。技能加载这件事难的不是把文件写出来而是让模型在正确的时机、用正确的方式、只执行正确的那部分流程。把这一课吃透之后你再回头用 Claude Code 做重复性任务会明显感觉到它真正开始懂你的流程习惯了。