Claude的Agent Skills大家习惯直接叫SKILL是我最近几个月用得最多的功能没有之一。Anthropic官方发布过一套推荐做法我反复读了几遍又拿真实项目试了好几轮发现真正让SKILL好用起来的关键其实就藏在三个地方。这篇文章不打算复述文档直接把提炼出的三个技巧、背后的逻辑以及我踩过的坑一次性讲清楚。不管你是刚接触SKILL的新手还是已经在用它搭复杂工作流的老手这篇都值得花十分钟看完。先给没接触过的人一句话解释SKILL就是把一套完整的领域知识、操作规范、参考文件和审查要点打包成一个文件夹让Claude在需要时自动加载按照你定义的方式输出结果。它和普通提示词最大的区别在于可复用、可分发、可版本管理——你写好一次之后任何对话里都能反复调用也能丢给团队其他人直接用。我把它理解成给Claude装上一个岗位说明书AI每次上岗前先读一遍规则再开始干活。这三个技巧分别是用描述事实代替下达命令、用渐进式披露组织SKILL目录、像调试代码一样迭代SKILL。下面一个个拆开讲每个部分都附上了可以直接抄走的写法和真实案例。1. 先搞清楚SKILL的底层逻辑1.1 SKILL到底是什么它和Workflow有什么区别很多朋友一上来就把SKILL和coze、dify里搭的工作流等同起来这是个很普遍的误解。工作流是把操作步骤画成节点图每个节点做什么、下一步跳到哪全部写死本质上是一套自动执行流水线。SKILL完全不是这个思路——它不是一条固定路径而是一份领域说明手册。Claude拿到你的SKILL后会理解其中的规则和目标然后自己决定怎么调用这些知识去完成任务。举个例子简历筛选工作流里每个节点可能固定是提取信息→匹配关键词→输出评分而简历筛选SKILL只需要说清楚技术岗简历重点看哪些能力、哪些信号值得警惕、评分标准是什么Claude自己会规划怎么读简历、怎么判断甚至你给一份缺胳膊少腿的简历它也知道想办法处理。这个区别决定了设计思路完全不同。做工作流你关心的是节点之间的连接对不对做SKILL你关心的是描述是否足够清晰、信息是否足够完整。刚开始写SKILL的人最容易犯的错就是把SKILL当成一组if-else命令来写结果Claude执行得很僵硬换个场景就失灵。1.2 官方推荐思路的底层三个原则我看了Anthropic对SKILL设计的推荐做法拆解下来核心是三个原则第一个是单一职责。一个SKILL只做一件事把这件事做透。比如简历筛选是一个职责面试问题生成是另一个职责不要揉在一起。这和我们写代码的高内聚低耦合是一个道理SKILL保持单一职责Claude加载时指令意图才不会被稀释。第二个是渐进式披露。SKILL.md这个入口文件只放精简的索引和说明把冗长的规则、模板、评分细则拆到子文件里Claude真正需要时才读取。这个技巧能显著减少每轮对话占用的上下文窗口让模型不把理解规则的算力浪费在无关细节上。第三个是迭代演进。官方推荐先做一个能跑通的最小版本然后根据真实使用中的失败案例逐步补充。一次做到完美是不可能的最好的做法是让它先够用再慢慢好用。这三条原则贯穿全程后面三个技巧其实就是它们的落地手法。2. 技巧一用描述事实代替下达命令2.1 为什么命令式指令会失败我见过大量刚上手的人这么写SKILL当用户提供简历时你需要第一步提取姓名第二步提取工作年限第三步根据年限打分第四步输出结果。这种写法看上去逻辑清晰实则在跟Claude说你按我的代码执行。问题在于真实场景往往比你的预想复杂——简历格式五花八门有人写5年Java经验有人写Java开发2019年至今。如果你把步骤锁死Claude遇到规则没覆盖到的形式就抓瞎不知道怎么写年份、怎么折算年限只能硬套导致错误输出。用描述的思路改写一遍技术岗位简历的筛选重点是候选人的编程语言经验、项目复杂度、以及技术栈匹配度。工作年限的表达方式多样可能为区间、起止年份或月数需要统一折算为满X年口径。产出意见时需同时给出与岗位描述的匹配程度说明和推荐建议。区别很明显第一种告诉Claude怎么做第二种告诉Claude这个领域是什么样的、重点关注什么、标准是什么。Claude本身是推理模型你给它完整的领域图景它自己会生成比固定步骤灵活得多的执行路径。2.2 描述式指令的三种写法模板我总结了三种经过实测有效的描述式写法也是官方推荐里隐含的套路第一种是建立领域全貌。不要急着写流程先写清楚你的领域是什么、核心目标是什么、常见的边界条件有哪些。比如做项目复盘SKILL就要写清楚复盘关注的维度、团队角色视角、对事的评价不对人的评价等等。第二种是定义好与坏的边界。直接告诉Claude什么样的产出是合格的、什么样的信号要警惕。比如简历筛选SKILL里写清工作经历频繁短跳是需要注意的信号比单纯命令它检查跳槽频率效果好得多。第三种是给出优质范例。在SKILL里放一两份完整的示例输出让Claude在看到真实参照物的情况下模仿格式和深度。示范的作用远大于指令我用过几次后发现放一份范例之后输出质量立刻提升一个档次。2.3 写完SKILL后自查三个问题每次写完SKILL.md我在发布前都会强制过一遍三个自查项也推荐你试试第一个全文有没有当...时你需要这类硬编码句式有的话琢磨下能不能改成描述场景和判断标准让Claude自己推导动作。第二个如果换一个表达方式完全不同的输入这个SKILL还能不能正确触发如果它依赖具体措辞才能工作说明描述不够通用。第三个删掉所有步骤性文字后规则表达还剩多少信息量大量细节的丢失意味着你过度依赖流程没把领域知识写透。这个自查过程大概花费五分钟但每次都能抓出几个导致输出僵硬的句式值得养成习惯。3. 技巧二用渐进式披露组织SKILL目录3.1 为什么不能把SKILL写成一本百科全书我在早期踩过一个大坑为了让SKILL功能强大我把所有规则、模板、FAQ全部塞进了SKILL.md写了将近三千字。结果Claude每轮对话处理时都要消耗巨大的上下文去理解这些内容反而导致核心任务上的表现变差。这就像给新员工上岗前丢给他五百页的员工手册等他想找关键操作时早被淹没在细节里了。Anthropic官方推荐的思路正好相反SKILL.md只承载核心索引和触发条件好比前台接待负责判断谁来、什么事、该引导到哪个部门。详细的评分标准、背景知识、处理模板都放在子文件里只有在Claude真正需要时才会去读。这个模式让SKILL的固定上下文开销降到最低也让主指令不被冗长内容拖累。3.2 一套通用的SKILL目录结构我经过多轮实践后稳定使用这样一套目录结构你可以直接抄resume-screener/ ├── SKILL.md # 入口文件功能概括 触发条件 子文件索引 ├── reference/ │ ├── scoring-rubric.md # 详细评分标准 │ └── red-flags.md # 需要注意的异常信号 ├── scripts/ │ └── normalize_experience.py # 可选辅助脚本规范化工作年限 └── examples/ └── sample-review.md # 样例输出让Claude模仿格式SKILL.md内部结构也很有讲究强烈建议在头部用YAML格式做元信息标注让Claude能快速识别并决定是否加载。我的入口文件通常长这样--- name: resume_screener description: 根据岗位描述与技术能力标准筛选简历输出结构化评审意见。适用于技术岗位的初筛场景。 --- # 简历筛选专家 当用户提供简历与目标岗位时你需要结合评分标准给出推荐决定与理由。 ## 评分标准 详细评分维度与权重见 reference/scoring-rubric.md ## 异常信号 需要特别关注的候选特征见 reference/red-flags.md ## 输出样例 一份完整评审输出示例见 examples/sample-review.md注意看入口文件里我只写了结合评分标准和见...文件真正的细节全部丢给子文件。Claude加载SKILL时只需要消耗很小的上下文识别出这是个简历筛选专家规则详情在子文件里等到它真正开始读简历时才会按需打开scoring-rubric.md。整条链路的信息开销被控制到了最低。3.3 子文件之间怎么配合路径引用要注意什么渐进式披露要想玩得顺子文件的职责切分必须清晰。我通常按三个维度拆分标准类文件比如评分细则、知识类文件比如领域背景与行业惯例、参考类文件比如输出模板与示例。分类清晰的好处是Claude在一次任务里不会同时加载所有文件只读取与当前问题相关的那个。路径引用是我发现翻车率最高的地方。SKILL内部引用子文件时建议使用相对路径并且保持引用名与实际文件名一致。比如在SKILL.md里写见 reference/scoring-rubric.md那reference目录下就必须真的存在这个文件名大小写都不能错。另外引用关系不要绕太深入口文件指向二级文件即可三级以上的嵌套会把路径系统搞得极难维护也增大了Claude找错文件的风险。还有个小技巧在SKILL.md的description字段里写清楚什么样的问题这个SKILL不擅长处理。比如简历筛选SKILL可以注明本技能仅针对技术岗位不适用于设计岗或销售岗。这个负向描述能有效避免Claude在无关请求上错误触发SKILL省下不少阿里云token——别笑这个问题我实际遇到了不下五次。4. 技巧三像调试代码一样迭代SKILL4.1 从最小可用版本起步不要一次写完美很多技术出身的朋友写SKILL有个毛病追求一步到位总想把所有场景都覆盖了再上线。这个思路会让SKILL的开发周期拖得非常长而且容易过度设计——你在设计时想象的那些复杂场景实际根本不会出现。正确的做法是第一版只覆盖最简单的场景先把核心流程跑通。拿简历筛选SKILL举例第一版只需要做到根据岗位描述判断候选人整体匹配度并给出一句话结论就足够了。你甚至可以不加子文件把规则浓缩进SKILL.md里总共三百字就拿去用。跑通以后再观察它哪里表现不好针对性补齐那块知识发现年限折算老出错就加一个normalize_experience的参考规则发现输出格式不统一就补一个sample-review.md。每一轮迭代都解决一到两个明确问题两周下来这个SKILL会变得非常强悍。4.2 用真实失败案例驱动SKILL升级我发现最高效的迭代方法不是靠想象而是收集真实的失败输出。具体操作是每次使用SKILL时如果发现结果不对劲立刻把当时的输入错误输出你期望的正确输出三件套保存下来放进一个专门的迭代笔记里每周集中分析一次。这个方法来源于代码调试里的回归测试思维迁移到SKILL上效果出奇地好。举例来说有个做行业调研的SKILL早期经常把二手信息当成统计数据用。我把几次出错案例放一起看发现共性是没区分数据来源的置信度。于是我在SKILL里加了一条规则所有数据必须标注来源与统计口径未经核实的数据需明确标注待验证。之后类似问题再没出现过。用失败驱动还有一个好处你能清楚知道每条规则是什么场景下加的、为什么加而不是凭记忆写一堆泛泛的指导。SKILL的可维护性会好很多团队协作时尤其明显。4.3 加版本号记录每次变更理由SKILL本质上是代码资产又因为是纯文本形式非常容易被随手改乱。我强烈建议在SKILL.md的meta区维护版本信息记录功能演进轨迹。我的习惯是在description下面加一个history字段--- name: resume_screener description: ... version: 1.3 history: - 1.0 初版基础匹配评估 - 1.1 补充年限折算规则 - 1.2 新增异常信号识别机制 - 1.3 修改输出格式统一为表格 ---这个做法的价值在于当SKILL在某次迭代后表现突然变差你能快速回溯到上一个稳定版本对比变更内容找出问题。有一次我想给SKILL加多语言支持结果发现输出质量明显下降查history后发现是prompt里双语规则互相干扰导致的对照历史版本一眼就看出来了。版本管理还有一个意想不到的好处它能逼着你每次改动都想清楚我这次为什么这么改避免无意义的反复调整。很多人的SKILL越改越乱就是因为没有版本意识东一锤子西一棒子。5. 完整实战一个简历筛选SKILL的拆解5.1 设计目标与目录搭建理论讲完了下面用一个我最近在做的简历筛选SKILL完整走一遍设计流程。目标岗位是中级后端工程师需要从这个场景里提炼出SKILL应该承载什么样的规则体系。我先明确最小可用版本的定义输入一份简历和岗位描述输出结构化评审意见包括匹配分数、优势、风险点和最终建议。围绕这个定义我把目录搭建如下backend-screener/ ├── SKILL.md ├── reference/ │ ├── scoring-rubric.md │ └── red-flags.md ├── scripts/ │ └── parse_years.py └── examples/ └── sample-output.md这次我把scripts加进来了目的是处理一个很常见的痛点简历里工作年限的表达太混乱。有的人写2018.03 - 至今有的人写3.5年还有的人只写了一段项目经历没写时间。脚本负责把各种格式统一换算成满X年Claude调用它时能拿到标准化数据再去做后续判断。5.2 SKILL.md入口文件的完整写法下面是这个SKILL的SKILL.md完整内容除了YAML头之外身体部分我刻意控制在一屏以内--- name: backend_screener description: 评估后端工程师简历与目标岗位的匹配度输出结构化评审意见。仅适用于技术类岗位不适用于非技术岗位评估。 --- # 后端工程师简历筛选专家 当用户提供候选人简历和目标岗位描述时需要输出包含匹配度评分、核心优势、关注信号和录用建议四部分的评审意见。 ## 评分标准 评分维度与各维度权重见 reference/scoring-rubric.md ## 风险信号识别 简历中值得警惕的特征清单及解释见 reference/red-flags.md ## 年限折算 简历中工作年限格式多样如无法直接判断请先运行 scripts/parse_years.py 进行规范化折算。 ## 输出模板 完整输出格式与样例参照 examples/sample-output.md如果用户没有特殊要求请保持输出格式与样例一致。写完之后特别注意了description中的负面约束不适用于非技术岗位评估这个我在前文提到过用途是防止其他无关请求错误触发。入口文件把全部细节挡在身后Claude只在需要读评分细则时才会去reference目录这比把评分细则直接写在入口里要省很多上下文。5.3 子文件里具体写了什么以及踩过的坑scoring-rubric.md里我定义了五个维度技术栈匹配度(30分)、后端项目复杂度(25分)、工作年限与职级匹配(20分)、系统设计能力(15分)、团队协作与软技能(10分)。每个维度下都有细致的得分档描述比如技术栈匹配度在25-30分要求核心语言与岗位要求一致且有两个以上深度使用的项目佐证15-24分是核心语言一致但深度不足以此类推。red-flags.md里列了四类风险信号频繁短跳三年内换过四家以上公司、技术栈前后矛盾简历自我描述与项目经历表述冲突、空窗期无法解释、过度夸大开源项目star数量与代码质量明显不符。每条都附了出现该信号时建议的追问方向让Claude在后续面试环节也能引用这套SKILL生成针对性问题。踩坑方面最典型的是脚本误用问题。最开始我让Claude在必要时跑parse_years.py它经常自作主张路径写错浪费好几轮对话。后来我把调用条件写死成当用户提供的简历中包含无法直观判断的年限表达时并给出了脚本的相对调用路径和用法示例模式识别立刻稳定了。这件事让我意识到给Claude的条件越模糊它越容易自由发挥自由发挥的结果就是路径写错、参数传错。5.4 三周迭代记录一览这个SKILL三周内从1.0迭代到1.4记录如下你可以感受下迭代节奏版本变更内容起因1.0初版仅包含基础匹配度评估跑通流程1.1新增red-flags补充风险信号多次漏掉账期频繁跳槽的简历1.2新增parse_years.py年限折算脚本年限表达混乱导致判断误差1.3修改输出模板结构化表格化输出风格不稳定格式五花八门1.4细化评分档位描述分数解释不清无法有效说服需求方每次迭代都只解决上一轮客观暴露出的问题。1.3那次我本来还打算同时加面试追问功能后来忍住了专注把输出格式稳定下来。实践证明这个克制是对的功能边界一旦扩大反而容易导致主场景表现退化。6. 常见问题与排查技巧实录6.1 高频问题速查表这几类问题是群里被问了无数次的直接整理成速查表方便你定位问题表现常见原因解决办法SKILL没被触发Claude完全不理description里没有触发边界或边界描述太窄扩充description明确什么问题应该用这个SKILL触发了但回答质量很差SKILL.md信息过载规则被稀释按渐进式披露重构细节拆分到子文件输出格式每次都不统一缺少输出模板或模板约束不严添加examples文件并在入口文档中明确格式必须与示例一致同一个问题换种说法就不灵了指令过于依赖具体措辞改为描述领域事实和判断标准而非固定步骤加载SKILL后对话变慢一次性读取了太多上下文内容精简SKILL.md让Claude按需读取子文件子文件路径引用报错相对路径写错或大小写不一致统一使用相对路径保持引用名与实际文件名严格一致如果你的SKILL出现了以上症状不用大改优先检查描述方式和目录结构多半能解决八成问题。6.2 我踩过最值得说的一次坑最后分享一次印象深刻的翻车经历。有一次我给SKILL加能力想让它同时处理简历筛选和面试问题生成两个功能寻思这样不是更全能吗结果上线试跑后发现一个严重问题当用户同时给两份简历时Claude完全不知道该走筛选流程还是问题生成流程输出内容两头不靠非常尴尬。事后想明白了这和单一职责原则完全违背。一个SKILL就是一件事你要面试问题生成那就再建一个面试问题生成的SKILL文件。两个SKILL可以同时存在于目录里但它们必须各自独立、边界清晰。Claude会根据用户请求自动选择加载合适的那个而不是一个SKILL里塞多个功能。这个教训让我彻底接受了SKILL的小而专定位。它不是一个多功能工具箱更像一个专家库——一个SKILL就是一位专家不同的专家组合在一起才能覆盖更多场景。你要做的是让每一个专家都够专业而不是让一个专家干所有人的活。我在实际使用中逐渐形成了一套自己的判断标准哪天我发现某个SKILL的SKILL.md超过了一千字就会强制自己停下来拆分子文件哪天哪个SKILL的迭代记录超过五条我就会考虑它是不是职责太宽了需不需要拆分。SKILL的设计没有标准答案但如果你写出来的东西让你自己和Claude都觉得轻那大概率方向是对的。用起来顺手、维护起来轻松就是好的SKILL。