1. 从一次“工具失灵”说起为什么我们需要 SKILL几个月前我在一个自动化项目里尝试让 Claude 按固定流程生成周报。起初我以为只要把流程写成一段很长的系统提示词塞进去模型就能老老实实照做。结果并不理想提示词超过两千字之后模型开始选择性遗忘约束中途跑偏去回答无关问题甚至把几个步骤的顺序完全打乱。我折腾了几轮 prompt 优化收效甚微。后来我接触到了 Anthropic 官方提出的 SKILL 概念才意识到问题不在“提示词写得不够好”而在于我让模型同时承担了“理解流程”和“执行流程”两个任务——这恰恰是 SKILL 想要解决的核心问题。简单说SKILL 是 Anthropic 在 Agent Skills 能力体系下提出的一种结构化技能封装方式把某类任务的完整执行逻辑指令、步骤、资源、示例打包成一个独立的技能模块Claude 在推理过程中按需加载并执行。这篇文章我想结合自己的实操经验从“什么是 SKILL”到“怎么写一个优秀的 SKILL”完整拆一遍重点覆盖官方最佳实践、文件组织方式、提示词设计思路以及我踩过的一些坑。适合正在搭建 AI Agent、做自动化流程编排、或者想把自己重复性工作沉淀成可复用技能的开发者。2. 先弄清楚SKILL、MCP 和 Tool 到底什么关系2.1 SKILL 不是又一种 Tool很多人第一次听说 SKILL第一反应是“这不就是工具Tool吗”。我当时也有同样的困惑直到对比了它们在 Agent 中的运行机制才搞清楚差别。Tool 的本质是一个可被模型调用的外部函数模型负责决定“何时调用、传入什么参数”但工具本身不包含“何时该被用”的上下文理解。比如一个get_weather(city)的 Tool模型知道传入城市名就能拿到天气但模型并不清楚在什么业务流程下该优先调用它、拿到结果后应该如何继续。SKILL 则更像是“一组有上下文的执行流程”。它由三部分构成SKILL.md核心指令文件描述了该技能何时使用、如何执行、有哪些步骤和注意事项scripts/ 资源目录存放技能运行时需要的脚本、数据模板、参考文档可选示例与校验规则帮助模型在调用时快速对齐预期输出。从这个角度来说SKILL 更像是把“工具 使用说明 执行策略 参考案例”捆绑在了一起。模型加载一个 SKILL不只是获得一个可调用的函数而是获得了一套完整的“怎么做这件事”的上下文。2.2 与 MCP 的边界在哪里MCPModel Context Protocol解决的是“模型如何标准化地访问外部数据和工具”的问题它定义了一套协议让不同的数据源和工具能够以统一的方式暴露给模型。SKILL 不依赖特定的传输协议它本质上是存在于文件系统里的技能定义。用一句话来区分MCP 负责“连接”SKILL 负责“流程”。MCP 决定模型能碰到的数据和工具范围SKILL 决定模型面对一个任务时按照什么逻辑一步步完成。两者可以配合使用同一个 Agent 里既可以通过 MCP 接入业务系统的数据接口也可以通过 SKILL 把标准作业流程固化下来。2.3 为什么 Anthropic 强调 SKILL 而不是“更长的提示词”这是我在实践中体会最深的一点。把流程细节全部塞进系统提示词表面上省事实际会遇到三个问题上下文污染与当前任务无关的指令会干扰模型判断尤其当多个任务共享同一个系统提示词时模型常常把 A 任务的规则误用到 B 任务上指令冲突长提示词里前后表述稍有出入模型就可能选择其中一条执行产生不可预测行为维护困难改一个步骤就要重新评估整段提示词对其他任务的影响风险极高。SKILL 的按需加载机制天然规避了这些问题。Claude 在收到用户请求后会先判断“这个任务是否匹配某个已注册的 SKILL”只在匹配时加载对应的 SKILL.md 内容。未匹配的任务完全不受影响。相当于把“全局规则”降维成了“局部上下文”既减少干扰也让每个技能可以独立迭代。3. 官方最佳实践拆解高质量 SKILL 的四个设计原则3.1 原则一明确“何时用”远比“怎么用”更重要翻阅 Anthropic 的官方实践文档时我注意到一个反复出现的强调点SKILL.md 的第一部分必须是“When to use”或“适用场景”而不是开门见山写步骤。原因很直观Claude 需要先判断是否激活这个 SKILL。如果适用场景描述模糊模型可能在任务不匹配时强行调用或者在任务高度匹配时反而错过。Anthropic 建议在 SKILL.md 开头用两三句话精确描述触发条件最好包含正例和反例。比如我写一个“客户邮件分类”的 SKILL适用场景不能只写“用于处理邮件”而要写成当用户需要对邮件进行分诊、标记优先级、提取待办事项时使用。如果用户只是要求撰写一封新邮件不要使用本技能。“不要使用”这种反向约束非常有效。实测下来加入反例之后误调用的频率明显下降因为模型在边界判断上获得了更清晰的信号。3.2 原则二步骤指令要“够细”但“不啰嗦”Anthropic 官方推荐在 SKILL.md 中把执行步骤写成分步指令但每一条指令都要聚焦“模型该做什么”而不是解释“为什么这样做”。原理背景可以放在参考文档里由模型在需要时查阅而不是堆在主指令文件中。举个例子同样是写“数据清洗”的 SKILL不够好的写法“先了解一下数据集的整体情况根据常见的数据质量问题进行处理最后输出干净数据。”更好的写法读取输入文件的列名和前 10 行数据识别缺失值比例超过 30% 的列在报告中列出对保留列中的缺失值数值型用中位数填充分类型用众数填充输出清洗后的文件与一份清洗报告Markdown 格式。第二种写法把模型需要做出的“决策点”前移——哪列该处理、用什么策略、输出什么——每一步都明确模型不需要在“自由发挥”和“猜用户意图”之间摇摆。3.3 原则三用好“示例”约束输出格式模型对齐输出格式最有效的方式不是文字描述而是给一两个示例。Anthropic 的实践文档里也强调在 SKILL 中提供输入-输出对尤其是期望输出的样例结构能让模型稳定复现预期的格式。我常用的做法是在 SKILL.md 里加一个## 输出示例章节放置一个简短的示范片段。比如邮件分类 SKILL 的输出示例{ category: urgent, priority_score: 92, action_items: [回复确认收到, 同步项目负责人], summary: 客户反馈生产环境出现数据延迟要求今日内给出修复时间点 }有了这个示例模型生成的输出结构稳定得多。后来我在多个 SKILL 里都采用了这种方法整体效果比纯文字描述输出字段定义要好上不少。3.4 原则四自带校验机制别把希望全押在“模型自觉”上优秀 SKILL 与平庸 SKILL 之间还有一个显著差异有没有内置“自检”环节。Anthropic 推荐在 SKILL 执行流程中加入最终校验步骤比如要求模型在输出前对照检查清单逐项确认。实际应用中我习惯在每个 SKILL.md 末尾加一个“交付前检查”小节列出三四条可量化的检查项。例如[ ] 输出文件格式是否为 UTF-8 编码的 Markdown[ ] 是否包含全部必填字段summary、action_items[ ] 是否有直接复制原始邮件的未修改文本这种写法的好处不仅是提升输出质量更重要的是当模型执行出现问题时你能快速定位是哪个环节出了偏差而不是面对一堆无法归因的错误输出反复试错。4. 手把手写一个 SKILL从目录结构到完整落地4.1 目录结构与文件规范Anthropic 对 SKILL 的目录结构有一套约定俗成的规范。我通常按下面的结构组织my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py └── references/ └── data_format.mdSKILL.md是唯一必须的文件命名固定全大写。scripts/放可执行脚本references/放参考文档、数据字典、模板文件。Claude 在加载 SKILL 时会读取 SKILL.md并按需访问这些子目录中的资源。这里有一个容易忽略的点SKILL 目录的位置。如果是在 Claude Code 的项目环境中使用SKILL 需要放在.claude/skills/下Claude 启动时会自动扫描该目录注册所有可用 SKILL。放在其他位置则需要在配置里显式声明路径否则无法被发现。4.2 SKILL.md 的推荐模板根据官方实践和我自己的迭代经验推荐使用以下模板--- name: 技能名称 description: 一句话描述该技能适用场景 --- # 技能名称 ## 何时使用 明确说明触发条件包含正例与反例。 ## 输入要求 说明该技能需要哪些输入信息以及这些信息的格式。 ## 执行步骤 1. 第一步... 2. 第二步... 3. 第三步... ## 输出规范 描述输出内容的结构与格式。 ## 输出示例 一个完整的示例输出。 ## 交付前检查 - [ ] 检查项1 - [ ] 检查项2这个模板的每一节都有明确作用。description字段尤其关键因为 Claude 判断是否激活该 SKILL 时主要依赖这个字段和“何时使用”章节的内容。不要在这两处写模糊的口号式描述。4.3 实战案例写一个“会议纪要结构化”SKILL我拿一个实际项目来演示完整过程。假设我需要一个 SKILL能把一段零散的会议录音转写文本整理成结构化会议纪要。SKILL.md 核心内容--- name: 会议纪要结构化 description: 将会议录音转写文本整理为结构化会议纪要提取决策、待办、风险。当用户提供会议转写文本并要求生成纪要及时使用。 --- # 会议纪要结构化 ## 何时使用 当用户提供一段会议讨论的转写文本并需要整理成会议纪要时使用。 如果用户只是询问关于会议的建议并没有提供转写文本不要使用本技能。 ## 输入要求 - 会议转写文本纯文本或 Markdown - 可选会议主题、参会人名单 ## 执行步骤 1. 通读全文识别会议的主要议题分布。 2. 提取每个议题下的关键讨论内容区分“事实陈述”与“主观观点”。 3. 识别明确决策项记录决策内容与提出人如能在文本中对应。 4. 识别待办事项提取负责人、截止时间如有、任务描述。 5. 按模板输出结构化纪要确保无信息遗漏。 ## 输出规范 - Markdown 格式 - 包含字段会议主题、时间如可识别、参会人、议题列表、决策记录、待办事项、风险与关注点 ## 输出示例 ### 会议主题数据平台迁移方案评审 #### 决策记录 - 确认采用双写迁移方案过渡期为两周 - 数据校验由平台组负责业务组配合 #### 待办事项 - [ ] 张伟完成迁移脚本开发截止 6月20日 - [ ] 李娜梳理依赖列表截止 6月18日 #### 风险与关注点 - 双写期间写入性能可能下降需设置监控告警 ## 交付前检查 - [ ] 是否覆盖了所有议题 - [ ] 每条待办是否有负责人 - [ ] 是否有未经文本依据支撑的编造信息这个 SKILL 我用了一段时间效果非常稳定。关键在“交付前检查”里那条“是否有未经文本依据支撑的编造信息”——它显著降低了模型在信息不全时自行脑补的问题。要知道模型在整理纪要时最容易犯的错不是漏项而是“合理想象”出一些原文中不存在的信息。5. 实操经验从零到一调试一个 SKILL 的完整过程5.1 在 Claude Code 中注册与测试我用的主力环境是 Claude Code。把 SKILL 目录放到项目的.claude/skills/下之后重启会话Claude 就会自动识别。可以通过对话直接询问“你有哪些可用的技能”确认 SKILL 是否成功加载。测试阶段我建议准备一组覆盖不同场景的输入至少包含三类典型场景完全符合 SKILL 设计目标的任务边界场景任务部分满足 SKILL 触发条件负向场景任务与 SKILL 无关但看起来容易混淆。用这三组输入反复跑重点观察两个行为启动判断是否在合适的时机激活和执行过程是否严格按步骤走。一旦发现 SKILL 在不该激活时被激活优先回去改“何时使用”部分的表述。5.2 参数调优如何通过输出让模型更稳SKILL 和自定义提示词一样也存在“过犹不及”的问题。我在调试中发现几个值得注意的参数和细节temperature 设置生成类任务可以稍高0.4~0.7结构化提取任务建议调低至 0.2 以下否则字段稳定性会下降步骤数量执行步骤尽量控制在 5~8 步之间超过 8 步模型容易在中途丢失对前序步骤的关注长文本处理如果输入内容很长建议在 SKILL.md 里显式要求模型“分批处理、中间汇总”而不是一次性读完所有内容再输出否则细节容易丢失。5.3 迭代节奏别追求一次写对我现在的习惯是先写一个最小可用版本跑通主流程再逐步增加边界约束和异常处理逻辑。第一版 SKILL 往往只包含“何时使用”“执行步骤”“输出格式”三部分。验证基础流程没问题之后再根据失败案例补充“交付前检查”和“反例描述”。这样做的好处是能快速定位问题来源。一次性写一个功能完整、覆盖各种边界的 SKILL一旦效果不好你会很难判断是步骤设计有问题、场景描述不准确还是输出规范约束不足。分步迭代则让每次改动都有明确变量调试效率高得多。6. 常见问题与排查技巧实录6.1 Claude 没有自动发现 SKILL这是新手最常遇到的问题。排查步骤按顺序来检查 SKILL 目录是否放在.claude/skills/下路径不能有拼写错误检查 SKILL.md 文件名大小写不能错必须叫SKILL.md检查文件头部 YAML 的name字段是否包含非法字符或重复重启 Claude Code 会话再试SKILL 在会话启动时扫描注册运行中加入的新 SKILL 不会被动态发现。6.2 模型偶尔不再遵循 SKILL 指令我遇到过几次 SKILL 在复杂对话中途“失效”的情况后来定位到原因是对话轮次太长早期加载的 SKILL 上下文权重被后续大量对话内容稀释。解决办法是在 SKILL.md 的执行步骤中加入“每一步开始前回顾本技能的核心目标”类似的自提示语句让模型在长流程中持续锚定任务范围。另一个直接有效的做法是把一个大型 SKILL 拆分成多个小型 SKILL每个只负责一个环节通过流程串联。拆细之后每个 SKILL 的指令密度更高被稀释的概率也小得多。6.3 输入输出格式兼容问题如果你在 SKILL 里调用了scripts/下的 Python 脚本处理数据注意脚本的输入输出编码统一使用 UTF-8。我踩过的一个坑是脚本输出的临时文件存在系统临时目录Claude 在后续步骤中读取时因为路径特殊字符解析失败。后续我把所有中间文件都放在项目内的skill_workspace/目录下问题就消失了。对于 Windows 用户还有一个细节路径分隔符不要混合使用。在 SKILL.md 里给出相对路径并约定基于项目根目录解析比写死绝对路径要稳健得多。6.4 SKILL 输出质量不稳定同一个 SKILL 在不同轮次运行产生不同质量的结果这除了模型本身采样随机性之外最常见原因是输入信息不完整。我建议在 SKILL.md 的“输入要求”部分明确列出必需字段若是字段缺失要求模型先向用户澄清而不是自行假设。比如会议纪要 SKILL如果我规定“参会人列表缺失时需要主动向用户确认后再生成最终纪要”输出质量会稳定很多。模型在没有完整信息时倾向于编造合理的默认值这在大规模使用中是个隐患。7. 我对 SKILL 未来形态的一些观察7.1 从“提示词复用”到“技能沉淀”现阶段大部分人的提示词工程还是停留在“复制粘贴一段 prompt 到对话窗口”的层面。SKILL 把这一过程结构化、文件化、可版本管理化本质上是在推动提示词工程向软件开发流程靠拢。我预期未来团队里会出现“技能工程师”这类角色专门负责把业务专家的作业方法转化为可运行的 SKILL 资产。7.2 SKILL 与 API 调用的结合方式如果你是通过 API 接入 ClaudeSKILL 的使用方式会更灵活一些。可以在系统提示词层面通过预定义规则让模型先去匹配可用技能列表再在匹配命中时把 SKILL.md 内容作为上下文注入。这种方式相当于自己在应用层实现了“按需加载”适合需要深度控制 Agent 行为的生产环境。7.3 一个实用的扩展思路SKILL 组合单个 SKILL 解决单一任务但实际业务流程往往是多步骤的。我的做法是把 SKILL 做成“可组合的积木”比如一个“项目周报生成”SKILL内部依赖“数据提取”“异常标注”“格式排版”三个子技能。在 SKILL.md 的执行步骤里显式声明子技能的调用顺序Claude 就能串联执行。这种组合方式让技能维护变得非常清爽修改格式排版不影响数据提取逻辑新增数据源只需要改数据提取那一个子 SKILL。如果你的业务逻辑足够复杂很值得按这个思路拆一拆。最后分享一个我实践下来的体会写 SKILL 的过程其实就是一次次“角色换位”的练习。你得从模型的视角去思考——看到什么描述会激活这个技能执行到哪一步容易产生歧义输出到什么程度才叫完成。这种思维方式一旦建立不仅 SKILL 写得好你设计其他 Agent 能力的整体水平都会跟着上一个台阶。