如果你最近在折腾 Claude Code、自建 Agent 工作流或者研究 Anthropic 官方那套 SKILL 机制应该已经发现一个现象SKILL 这个东西官方文档看着很简单就是一个SKILL.md加上几个示例但真正放到自己的项目里它要么不触发要么触发了以后干活的质量飘忽不定。我自己前前后后调了十几个 SKILL踩了不少坑才把能用变成好用。这篇文章就围绕 Anthropic 官方的最佳实践拆出三个我实测下来最值钱的技巧怎么写描述才能让 Claude 在正确时机自动加载技能、怎么控制 SKILL 的体积避免上下文被塞爆、以及怎么用评估样本驱动 SKILL 持续迭代。文章会带着具体案例和排查思路走适合正在用 Claude Code、或者在自研工作流里接入 SKILL 的开发者参考。你不需要一开始就懂所有细节跟着章节走一遍至少能避开我踩过的那些大坑。1. SKILL到底是什么能力封装而不是又一种提示词模板1.1 从提示词堆积到按需加载的场景转变以前做 Agent 工作流最常见的做法是把所有指令都堆在系统提示词里你希望 Agent 会写文档、会写代码、会做数据分析就把这些角色的要求全部写进去。结果很直观——上下文很快被撑爆模型在无关指令上浪费注意力而且指令之间互相打架。SKILL 的思路完全不同它把一组技能封装成独立目录平时不占上下文只有当 Claude 判断当前任务需要这个技能时才会按需加载。你可以把它理解成给 Agent 装了一个工具房需要扳手的时候伸手拿扳手而不是把整个工具房背在身上。官方对 SKILL 的定义也印证了这一点它是一组指令、工具和资源的集合用于让 Claude 完成特定任务核心价值在于三点——模块化、按需触发、可复用。就拿官方给的例子来说PDF 处理、PNG 图像分析、演示文稿转换这些任务都可以做成独立 SKILL谁用谁加载。1.2 一个 SKILL 的目录结构长什么样一个标准 SKILL 的基本结构如下skill-name/ ├── SKILL.md # 技能说明书包含名称、描述、指令 ├── scripts/ # 辅助脚本可选 ├── assets/ # 静态资源可选 └── reference/ # 参考资料可选最核心的文件是SKILL.md它决定了技能是否会被正确触发。这个文件顶部有 YAML frontmatter包含name和description字段正文才是具体的指令内容。我用一个实际例子解释。假设做一个会议纪要整理技能--- name: meeting-notes description: 将原始会议录音转写文本或杂乱笔记整理为结构化会议纪要支持按参会者、决策项、待办事项三维度输出。 --- # 会议纪要整理 当输入包含会议记录、转写文本或杂乱笔记时按以下步骤处理 1. 提取参会者与发言轮次 2. 标记决策项 D1、D2... 3. 生成带负责人和截止日期的待办列表看起来很简单但注意一个关键点description写得好不好直接决定 SKILL 能不能被有效触发。下一步我要详细说这个。1.3 为什么说 SKILL 是给 Claude 装上的工具箱系统提示词像是给 Claude 设定世界观SKILL 则是具体的肌肉记忆。它们的分工不一样。工作流场景里我用一个类比你把系统提示词比作公司的规章制度——它定义了员工该遵循的基本准则SKILL 则是岗位操作手册——遇到某类任务时拿出来逐条执行。两者缺一不可但不能相互替代。也有不少人问SKILL 和插件、子代理有什么区别我的理解是插件偏向外部工具接入SKILL 偏向能力路径封装子代理是分身SKILL 是工具。实际项目里它们经常组合使用SKILL 可以调用插件工具也可以把子代理作为执行环节。但核心竞争力始终在那份SKILL.md里这也是官方一直在强调的设计技能时把注意力放在指令质量和示例质量上。2. 技巧一把 description 写成触发说明书别写成功能简介2.1 description 是唯一被自动检索的窗口官方文档里明确提到当你在 Claude Code 中请求某项任务时模型会自动扫描所有已安装 SKILL 的name和description来判断哪个技能匹配。这意味着一个残酷的事实如果 description 写得不精确Claude 根本不会加载你的 SKILL正文写得再漂亮也白搭。这个问题在我刚上手时特别严重。我最初写过一个代码审查技能description 是用于代码质量检查和问题发现。听着没毛病但实际使用中Claude 经常在帮我看看这个函数有没有问题时不触发它反而在给我讲解一下这段代码时触发了。原因在于描述没有点出触发边界模型无法区分审查和解释。2.2 正确写法场景 输入 输出 边界经过多次调试我把 description 的写法总结成一个公式触发场景 输入形态 输出要求 不适用情况。四要素缺一不可但描述篇幅有限需要精炼。用官方文档里的例子做参考——官方一个图片处理技能的 descriptiondescription: 用于图像处理任务包括裁剪、缩放、格式转换和基本滤镜效果。 当用户提供图片文件路径或图片 URL 时使用。 不要用于图像生成或高级图像分析任务。注意最后那半句不要用于……这就是边界意识。因为描述里一旦没有排除项模型建模相似度时常常会把相邻任务错误关联。另一个常见问题是描述太短导致召回失败。官方推荐描述要具体、包含示例、表明使用场景这一点怎么强调都不过分。之前在调整一个简历筛选工作流的 SKILL 时我只写筛选简历召回率极低改成当用户提供简历 PDF、DOCX 或文本内容且需要按岗位 JD 评估候选人匹配度时使用。输出包含技能匹配、经验年限、薪资区间三部分之后十次测试有九次能正确触发。2.3 一个从召回失败到稳定命中的改造案例这里放一个真实改造过程。需求是做一个狗头军师式的决策建议技能输入一个问题或选项输出多角度分析和建议。第一版 description 是提供聪明且略带幽默的建议帮助用户做出决策。测试结果十次请求只触发了三次。第二版改成description: 当用户描述一个两难选择、人生决策、职场困惑或需要权衡利弊的问题时使用。 输入可以是一个具体问题或多个选项输出应包含利弊分析、决策建议和一句幽默总结。 如果不涉及决策、建议或权衡不要使用。改造后召回率提升到 9/10。核心变化在于明确了触发时机两难选择、职场困惑、输入形态具体问题或多个选项、输出形态利弊分析 建议 总结、排除情况不涉及决策时禁用。这个结构可以直接抄走用在自己项目里。这里有个额外心得description 里不要放模型的具体版本号、公司内部代号这类噪音信息。模型在检索时是通过语义相似度匹配的噪音越少匹配越准。你写- 内部代号为 X-1 的技能模型很可能会把这个代号当成语义特征反而干扰匹配。3. 技巧二让 SKILL 保持轻量把重资源放到外部引用里3.1 一个常见的上下文超长困扰热搜词里一直有人在搜dify工作流 上下文超长comfyui工作流这其实是个普遍痛点SKILL 或工作流加载的内容越多上下文越长模型速度越慢费用越高甚至直接超出窗口限制。我在做代码审查 SKILL时也翻过车——把完整的编码规范、工具说明、示例代码全部写进SKILL.md结果每次加载光这个文件就有三千多 token再加上输入内容很快接近上下文上限。官方推荐的思路是保持技能轻量把详细信息放在外部文件里。也就是说SKILL.md更像一个索引和操作纲要重资源通过相对路径引用让 Claude 在需要时再去读取具体文件。比如 PDF 处理 SKILL正文只写 workflow 和脚本调用方式具体的 PDF 解析脚本放在scripts/目录参考文档放在reference/目录。3.2 SKILL.md 瘦身 外部资源引用的目录设计一个瘦身后的典型结构长这样code-reviewer/ ├── SKILL.md # 只有核心工作流引导 Claude 访问下面三个文件 ├── rules/ │ ├── security_rules.md # 安全检查清单 │ ├── performance_rules.md# 性能问题清单 │ └── style_rules.md # 风格规范清单 ├── scripts/ │ └── parse_diff.py # 解析 git diff 的辅助脚本 └── examples/ ├── good_review.md # 正向示例 └── bad_review.md # 反向示例在SKILL.md里正文部分可以这样引导# 代码审查 1. 如果输入包含 git diff 或 PR 变更先运行 scripts/parse_diff.py 解析变更内容 2. 依次阅读 rules/security_rules.md、rules/performance_rules.md、rules/style_rules.md 3. 按安全、性能、可读性三个维度输出审查意见 4. 涉及具体模式时参考 examples/ 下的示例这样的好处非常明显Claude 不是一次性把所有规则塞进上下文而是按步骤按需读取整体 token 消耗大幅下降。实测同一个审查任务瘦身前单次加载约 4.2k token瘦身后约 1.5k token执行效果反而更稳定——因为模型不会被一堆冗余信息干扰。这里要补充一个注意点外部文件的超链接路径要写清楚最好是相对路径。Claude 在沙箱环境里通常可以访问 SKILL 目录但如果你用绝对路径或者写错文件名它会按自己的理解猜测猜错了就报SKILL 加载失败。我第一次写引用时用了默认路径/Users/xxx/skills/...换一台机器就废了改成相对路径reference/xxx.md后通用性立刻提升。3.3 用 CLAUDE.md 做全局路由让 SKILL 各司其职除了给单个 SKILL 瘦身还要注意 SKILL 和工作流全局配置的关系。Claude Code 里有CLAUDE.md作为项目级全局记忆文件它是所有会话默认加载的。滥用CLAUDE.md和滥用 SKILL 是一样的问题。我的经验是CLAUDE.md里只写项目结构、命令规范、团队约定这类全局信息不要写具体技能步骤SKILL 负责具体技能。这样 claude 在加载技能时不会遇到两个来源的指令冲突比如 CLAUDE.md 说代码风格走 eslintskill 里说忽略代码风格模型就会犹豫到底执行哪个。实际操作中我还会在CLAUDE.md里放一段技能路由说明## Skills 使用约定 - 所有代码审查类任务code-reviewer - 所有文档生成类任务doc-writer - 所有数据分析类任务data-analyzer - 其他情况优先从已安装 skill 中按描述匹配这种写法相当于给别人一个明确入口也让 Claude 在自动触发失败时可以人工指定路径。很多团队在协作时发现我写的 skill 别人就是不触发多半是因为没有把这种路由约定写在显眼位置。4. 技巧三用评估样本驱动迭代别靠手感调词4.1 SKILL 也是代码需要回归测试我知道多数人做 SKILL 的流程是写一版跑一次发现不理想改两句措辞再跑一次。这本质上是在手感调词能短期有效但长期不可维护——因为你没法回答一个问题这次改动会不会让之前能通过的场景变差官方一直在强调评估的重要性。SKILL 设计的测试闭环应该是为每个 SKILL 准备一组输入样本和期望输出每次迭代后跑一遍样本对比输出质量和触发正确率。这样改动才有依据。具体做法上我为每个 SKILL 建立一个tests/目录放两类东西一是测试用例文档二是评估跑分脚本通常用 Claude API 批量跑样本然后人工或规则评分。测试用例文档长这样# 测试样本清单 ## 正样本应该触发 - 帮我看看这个 PR 的代码有什么安全问题 - 分析一下这段代码的性能瓶颈 ## 负样本不应该触发) - 给我解释一下什么是区块链 - 帮我把这篇文章翻译成英文 ## 边界样本触发与否均可但行为要明确 - 这个函数能不能优化一下 # 偏向触发 - 这个项目用的什么架构 # 偏向不触发4.2 构造正样本、反样本、边界样本的方法很多人在这一步犯难不知道样本哪里来。我的方法有三个来源第一历史会话和用户提问记录。把你在真实使用中遇到的应该触发但没触发、不该触发却触发了的情况全部记录下来这些是最有价值的样本。我做简历筛选 SKILL 时就是从三周的会话日志里捞出了 40 多条真实提问作为正负样本基础。第二同义改写和对抗扰动。把一条正样本用不同表达方式重写比如帮我筛简历改写成看看这两个候选人哪个更合适这个人的经历匹配这个岗位吗确认这些变体都能触发。负样本则要写一些描述上很像、实际不匹配的场景对抗模型的误召回比如帮我生成一份简历模板就不该触发简历筛选技能。第三边界样本。这是最容易被忽略但最有用的部分。边界样本专门用来测试 description 的排除项是否生效。比如处理讲一下这个决策的利弊这类请求触发决策建议 SKILL 可以但不该把只是陈述事实的请求也拉进来。边界样本能逼着你去精化 description 里的否定条件。评估脚本不用太复杂一个 Bash 或 Python 脚本就能跑。Python 的思路大致是读取所有样本逐个发给 Claude加上如果上述任务适合用某个 SKILL 处理请回复该 SKILL 的 name否则回复 NO_SKILL的指令最后对比结果。批量跑完之后人工看一眼错例按误触发哪些样本、漏触发哪些样本来定位问题再回到 description 和正文里做修改。4.3 在 Claude Code 里跑评估把结果沉淀成 CHANGELOG更贴合实际的做法是在 Claude Code 里直接跑评估。可以先按官方方式安装 SKILL 到.claude/skills/下然后用一个简单的测试子代理或脚本过样本。跑完一轮评估后我会把结果沉淀成变化日志放在 SKILL 目录下的CHANGELOG.md里。别嫌这一步多余它会在两周后救你一命——当你改完描述却发现效果倒退时可以快速 diff 出上次哪个版本触发了这个样本这次为什么没触发。# Changelog ## v0.3.0 (2025-11-02) - 修改 description增加当用户提供简历 PDF、DOCX 或文本内容的输入形态说明 - 负样本回归新增 5 条生成简历模板类样本全部正确排除 - 正样本通过率38/4192.7% ## v0.2.1 (2025-10-28) - 修正 scripts/parse_diff.py 的失败回退逻辑 - 修复当 diff 为空时不再输出空审查报告这里我特别要强调回退逻辑这个点。SKILL 执行时经常会遇到文件缺失、脚本报错、格式不匹配等情况。如果你的技能指令里没有写脚本失败时怎么办Claude 会自行发挥导致同一技能不同次表现差异巨大。官方的建议是提供清晰的执行路径和失败处理方式实测下来给技能加如果解析失败读取输入的前 500 字并尝试基于文本模式输出这类兜底指令稳定性提升非常明显。5. 踩坑实录从能跑到稳定好用的四个常见问题5.1 技能没被加载先查路径再查描述我明明装了 SKILLClaude 就是不调用是社区里最常见的问题。排查顺序我建议固定为先确认目录位置对不对——Claude Code 默认读取.claude/skills/skill-name/SKILL.md注意是放在项目根目录的全局配置里还是用户级目录不同环境的路径有差异确认文件名严格是SKILL.md大小写写错会直接失效最后再检查 description 是否达到前面说的四要素标准。多数情况下漏触发都是 description 的问题而不是代码问题。遇到技能加载后行为不符合预期也先别急着改描述。用--print或者模型输出确认它真的加载了正确的 SKILL 文件有时候它会同时在多个技能中选择一个相似度最高的错误技能。你可以通过更新排除项让两个技能的 description 拉开距离。5.2 上下文被塞满控住自动加载而不是控输出上下文超长多半不是 SKILL 本身太大而是自动加载了太多 SKILL。官方设计里Claude 会在必要时自动加载相关技能但如果你装了二十个 SKILL 且描述写得含糊它可能会同时加载五六个加起来 token 就爆了。解决思路有两个一是精简已安装技能数量只留高频使用的二是在每个技能描述里加强排除项降低被并发加载的概率。对于特别重的资源坚持用外部引用别让SKILL.md成为看不见的上下文杀手。我见过有人为了省 token把SKILL.md压缩到只剩一句话结果技能质量全面崩盘。这个方向是错的正确的做法是让SKILL.md全文保持精炼但它引用的外部文件可以丰富。核心指令控制在上下文是两三百 token参考资料按需读取这样才能兼顾质量和效率。5.3 多个技能互相干扰给每个技能画清楚势力范围当你同时有简历筛选面试问题生成候选人对比评估三个 SKILL 时很容易出现用户问这两个候选人怎么比较模型同时加载了两个技能输出出现两套格式。我的解法是在团队协作项目里直接建立技能边界表写明哪些任务归属哪个技能并在每个技能 description 里显式写上候选人对比由 candidate-comparison 技能处理本技能不处理对比类请求。听起来有点啰嗦但实际效果立竿见影。另一方面如果你发现两个技能的功能高度重叠不要靠描述微调硬撑而是合并成一个。官方也强调技能设计要模块化但避免冗余。拆得太碎描述互斥工作量大合并太大又变成早期的巨型提示词。这个度怎么把握我的判断标准是如果一个技能的指令超过两千字并且包含多个不相关子任务就考虑拆分如果两个技能的核心步骤七成相同就坚决合并。5.4 不要试图用 SKILL 替代系统提示词最后一个容易跑偏的点有些开发者把 SKILL 当成万能钥匙什么都要做成 SKILL甚至把整套产品的行为规范塞进去。这违背了设计初衷。SKILL 解决的是特定任务的高质量执行不是全局人格设定。全局约束应该留在CLAUDE.md或系统提示词里SKILL 应该保持任务聚焦、边界清晰、按需加载的特点。我在多个工作流里测试过一旦把全局规范误放进 SKILL最直观的副作用是其他任务再也拿不到这些规范因为技能没被加载时规范就不存在。跨项目复用时还会带着旧项目的全局信息造成行为污染。所以我的经验是SKILL 的正文只写完成该任务所需的步骤、判断标准、输入输出格式其他一律不写。如果你发现正文里开始出现你是一个……这种人格设定句停一下那句话很可能应该放在别处。写完这些我自己最大的体会就是SKILL 的难点从来不在写而在设计——设计触发、设计边界、设计评估。你要先接受它是会被模型检索、会占上下文、会在真实输入下出各种意外的系统而不只是一篇漂亮的说明文。每次改动都跑一轮样本每次上线都写一行 changelog你的工作流会在这种笨功夫里一点点变稳。毕竟我们折腾这些不是为了让别人觉得好厉害而是让自己的 Agent 真正少犯错、多干活。