刚接触 Claude Skills 的朋友十有八九都会问一句话这玩意儿跟我直接把要求写在对话里有什么区别我一开始也是这么想的直到我连续写了十几个 Skill 之后才反应过来——差的不是能不能做到而是每次能不能稳定做到。你手动写 Prompt相当于每次招个临时工重新交代工作流程而 Claude Skills 是把工作流程固化成文件让 Claude 一进对话就知道自己该干什么、按什么顺序干、产出什么格式。这篇指南我按自己的实操路径来写从概念到基础写法再到进阶技巧和避坑实录尽量让零基础的人也能照着做出来一个能用的 Skill。1. 先搞清楚Claude Skills 到底解什么痛点1.1 从临时对话到可复用技能的转变用 Claude 用得越久你越会发现一个问题同一个任务你在这段对话里把要求说得清清楚楚换一段新对话又得从头再说一遍。比如让 Claude 帮你写周报你今天说分成五段重点写问题分析明天说有数据先放数据没有数据写进展每次都很累而且 Claude 的理解还会飘。Claude Skills 解决的就是这个每次重新交代的副作用。它的本质不是魔法而是把一个 Skill 所需的指令、模板、参考文档、甚至是脚本打包成一个独立目录。Claude 在对话开始时就能感知到这些可用的 Skill当你的需求命中某个 Skill 的描述时它会自动加载并按照 SKILL.md 里的说明执行。我打了个比方普通 Prompt 等于你给 Claude 发微信语音交代事情Claude Skills 等于你给 Claude 发了一份岗位说明书加操作手册。新对话新任务它看一眼岗位说明书就能进入状态不用你反复唠叨。这带来的直接好处不是功能变多了而是输出稳定性明显变好——同样的输入出来的格式、语气、内容结构都能保持在同一个水平线上。1.2 Skill 与普通 Prompt 的核心差异很多人把 Claude Skills 当成高级 Prompt大方向没错但差异其实很显著。我整理了一张对比表维度手写 PromptClaude Skills存在形式对话里的一段文本聊完就没了一个独立目录包含 SKILL.md 和资源文件复用性需要复制粘贴难以跨对话复用一次写好所有新对话随时可调用管理方式零散靠记忆保存目录化管理可按项目、功能归类扩展性几乎不可扩展全靠文字描述可携带模板、示例、脚本、参考文档触发方式手动输入每次都要写Claude 根据对话内容自动判断并调用稳定性受对话上下文影响很大有固定指令约束输出波动小这表里最关键的一行是触发方式。手动 Prompt 是你主动告诉 Claude 该干什么而 Skill 模式下你只负责提出需求Claude 自己判断该调用哪个技能。这背后依赖的是语义识别机制你的 Skill 描述写得不清楚模型就认不出什么时候该用它。我自己最大的体感是上手写 Prompt 像是在给 Claude 单独布置作业写 Claude Skills 像在给 Claude 设计一套工作制度。制度一旦建好它会在你无感的情况下自动生效省心程度完全不一样。1.3 谁最需要 Claude Skills不是所有人都需要立刻上 Skill但下面这几类人我建议尽早开始玩内容创作者有固定写作风格、固定文章结构每天产出类似格式的内容。把风格和结构写进一个 Skill等于给 Claude 装了一个你自己的文风外挂。程序员代码审查、重构、写 commit message、生成接口文档这类任务流程高度固定用 Skill 可以把检查清单和规范全部内嵌进去。运营和产品经理周报、竞品分析、数据分析、活动复盘这些任务每次的框架差不多用 Skill 能省掉大量的格式调整时间。知识工作者需要反复处理某一类文档比如合同审核、论文润色、文献摘要Skill 可以把你的审核标准和偏好存下来。说句实话如果你只是偶尔让 Claude 帮忙写个标题、翻译一句话那没必要用 Skill手写 Prompt 更方便。但只要你发现自己每周都会让 Claude 做同一类事那就值得把它固化成 Skill一次投入长期复用。2. 上手前必须搞懂的四个核心名词2.1 SKILL.md一切的核心一个 Skill 的目录里最核心的文件就是 SKILL.md。这个文件是所有指令的中枢Claude 加载 Skill 之后主要就是读这个文件来决定怎么干活。SKILL.md 一般由两部分组成头部元信息和正文指令。头部元信息使用 frontmatter 格式就是被三个横线包起来的那段 YAML通常包含 name 和 description 两个字段。name 是这个 Skill 的唯一标识description 是给 Claude 看的描述用来判断什么时候该用这个技能。很多人写 SKILL.md 时只重视正文忽略了 frontmatter这是个大坑。尤其 description 字段它直接决定了 Claude 在什么情况下会想到调用你这个 Skill。description 写得像生成周报模型就只能在你明确说生成周报时才触发如果你写的是当用户需要整理本周工作内容、撰写周总结、盘点工作进展时使用触发场景就宽得多也更贴合真实使用习惯。2.2 目录与附属资源Skill 不是一个孤零零的文件而是一个完整的目录。你可以在这个目录里放模板、参考文档、示例输出、甚至脚本。Claude 在执行任务时可以通过相对路径来引用这些资源。我的习惯是给目录分三个子文件夹templates 放输出模板examples 放优质示例references 放参考规范。这样主文件 SKILL.md 只需要写流程和逻辑具体的细节内容全部丢到子文件里避免单个文件过长导致 Claude 抓不住重点。目录命名也有讲究。SKILL.md 文件本身必须叫这个名字父目录名最好跟技能功能强相关。我见过有人建一个叫test的目录过两周自己都忘了里面是什么功能更别说靠语义识别去触发的模型了。目录名直接用小写字母加短横线比如 weekly-report-generator一目了然。2.3 触发机制与 description 的写法Skill 的自动触发依赖的是 Claude 对对话内容的理解。当你发起对话时模型会先看你配置了哪些 Skill再结合你的当前需求做匹配。这个过程不是精确的字符串匹配而是语义级别的匹配。这带来一个很实际的影响description 的写法质量直接决定 Skill 的出勤率。我踩过不少坑最典型的是写得太具体比如当用户说帮我写周报时使用结果用户换了个说法帮我整理一下这周干了啥Skill 就不触发了。或者写得太宽泛处理文档这种描述会导致 Claude 什么任务都想来用它。比较好的写法是先写清楚场景再列几个常见说法作为关键词最后加一句不要用在不满足条件的情况。比如--- name: weekly-report-generator description: 根据用户提供的一周工作内容生成结构清晰的项目周报。适用于写周报、整理本周进展、汇总工作结果等场景。当用户没有提供任何本周工作信息时不要自动生成。 ---2.4 版本管理与命名规范Skill 也是代码是代码就该有版本管理。虽然很多人用 Skill 时都是在自己电脑上维护没有纳入版本控制但我建议至少做到两点第一文件开头或目录里留一个版本号第二改动 Skill 时保留改动记录别直接覆盖完事。我个人的做法是给每个 Skill 目录里放一个 CHANGELOG.md哪怕只是简单记几行v1.1 改了输出格式增加了数据缺失时的兜底逻辑。原因很现实Skill 的效果好坏往往依赖于你反复调试后的微小改动如果不记录你很难知道哪个改动导致了变好还是变坏过段时间想回退都没办法。命名上我统一用这样一个规范功能名-版本。目录用功能名SKILL.md 的 frontmatter 里记小版本号。别用最终版绝对不改版这种沙雕命名相信我你一定会改的。3. 从零写出第一个 Skill五步实操3.1 明确任务边界和输入输出我建议第一个 Skill 不要贪大选择一个你每周都要做、流程相对固定的任务。我就用周报生成器作例子因为几乎所有上班族都能立刻理解这个场景。开始写之前先回答三个问题Skill 的输入是什么输出是什么不做什么周报生成器的输入是用户零散发来的本周工作流水输出是按固定模板生成的结构化周报不做的事是没有数据时自己编造工作内容。把边界想清楚后面写指令时就会顺畅很多。这里特别提醒一次只做一个功能。很多人第一次写 Skill 就想做一个全自动超级助手既写周报又分析数据还能安排日程结果 SKILL.md 写得又长又乱Claude 反而哪个都做不好。Skill 的设计哲学是单一职责功能越聚焦指令越清晰效果越稳定。3.2 搭建目录结构在动手写内容之前先把目录搭好。我用的结构是my-skills/ └── weekly-report/ ├── SKILL.md ├── templates/ │ └── weekly-report-template.md ├── examples/ │ └── sample-report.md └── references/ └── writing-guide.mdSKILL.md主指令文件Claude 首先读它。templates/weekly-report-template.md输出模板规定周报的段落结构和格式。examples/sample-report.md一份完整示例给 Claude 模仿格式。references/writing-guide.md补充写作原则比如语气、详略、数据分析要求。把这几个文件先创建好哪怕内容是空的也能强迫你把 Skill 当软件工程来做而不是随手丢个 prompt 文件夹。3.3 编写 SKILL.md 正文这是最关键的一步。SKILL.md 的正文部分我建议按下面几个区块来组织Claude 对这种结构化的指令理解最好角色定义一句话说明这个 Skill 是干什么的。执行流程用有序列表写清楚步骤从接收输入到输出最终结果。输出要求格式、标题层级、字数范围越具体越好。禁止事项写清楚不能做什么比如不能编造数据、不能遗漏用户明确提出的内容。参考文件告诉 Claude 在什么情况下去读 templates 和 examples。一个精简的示例--- name: weekly-report-generator description: 根据用户提供的一周工作内容生成结构化周报适用于写周报、整理本周进展、汇总工作结果等场景。 --- # 周报生成器 你是一个周报撰写助手。用户会提供本周的工作流水或项目进展你需要将它们整理成一份结构清晰、重点突出的周报。 ## 执行流程 1. 阅读用户提供的所有工作内容按项目或主题归类。 2. 对每项内容提炼做了什么、结果如何、下一步计划。 3. 如果信息不足先向用户提问补齐不得自行编造。 4. 按模板输出最终周报。 ## 输出要求 - 必须使用 templates/weekly-report-template.md 中的格式。 - 分为本周完成问题与风险下周计划三大部分。 - 使用要点式表达每项不超过两行。 - 在周报开头用一句话概括本周整体进展。 ## 禁止事项 - 不要虚构用户未提到的工作内容。 - 不要在没有时间数据时强行编造时间节点。 - 不要输出与模板不符的格式。实际编写时还有两个技巧。第一尽量用短句把长段落拆成可勾选的清单模型对清单的执行力远高于大段描述。第二善用必须不得这类强约束词比可以尝试尽量有效得多能明显减少模型自由发挥的空间。3.4 用真实对话测试和校验Skill 写完不是终点测试才是大头。我的测试方法是新建对话用三种问法来触发同一个 Skill看是不是每次都能正确调用直白型帮我写周报。口语型我这一周干了好多事你帮我整理整理出个周报。隐晦型这周的进展总结一下。如果三种问法都能触发说明 description 写得及格了。接着再检查产出质量比如模板格式是否严格遵循、内容是否归类合理、信息缺失时是否会自动追问。发现问题就回 SKILL.md 修改改完再测。还有一个容易被忽略的测试点边界测试。刻意用车险、菜谱这种毫不相关的问题测试看 Skill 会不会被错误触发。如果错误触发了说明 description 里缺少排除性说明需要加上仅在用户明确提到周报场景时使用。3.5 记录基线效果并持续迭代我会建议你在第一次测试通过后把你认为满意的示例输出存进 examples 目录作为这个 Skill 的效果基线。后续每次修改 Skill都用同一份测试输入跑一遍对比新输出和基线输出的差异。这一步的意义在于Skill 调优经常出现东边修好西边坏的情况有了基线对比你能快速发现某个改动是否引入了新问题。我自己做过一个数据分析类 Skill第三版改动后输出格式完美但漏了数据口径说明就是靠基线对比才发现的。4. 进阶把单个 Skill 做成生产级技能4.1 用子文件拆解复杂任务当 Skill 的指令越来越长你会在测试中发现一个问题SKILL.md 文件太长时Claude 会选择性失忆抓不住重点。这时候就需要拆文件。核心原则是SKILL.md 只留流程骨架和关键约束把大段的参考规范、模板细节、示例放到子文件里。比如一个复杂的数据分析 SkillSKILL.md 里只写按 references/data-analysis-guide.md 里的流程执行模板见 templates/report-template.md具体细节都在子文件里。这样做的另一个好处是方便替换内容。比如模板要改版你只需要改 templates 目录下的文件SKILL.md 几乎不用动。这种解耦思路跟写代码时把配置和业务逻辑分开是一个道理。4.2 内置模板和示例少让模型自由发挥想让输出稳定最有效的手段之一就是提供示例。模型是你给它看什么它就模仿什么。一个没有示例的 Skill相当于只给了员工规章制度没给案例参考效果全看个人发挥。我写每个 Skill 都至少放一份完整示例。这份示例不是随便写的我会按照自己最满意的输出标准逐字打磨因为模型会把它当作格式和风格的最高参照。示例里的内容可以脱敏处理但结构和措辞要保持真实可用。放示例的时候有个小技巧在 SKILL.md 里明确告诉 Claude先阅读 examples 目录下的示例文件再开始执行任务。否则模型可能只读主文件根本不看子文件你的示例就白放了。4.3 多轮任务的状态保持技巧有些任务不是一轮就能完成的比如分析这周数据并生成完整报告中间可能要多次追问。这也是 Skill 最容易翻车的地方执行到一半Claude 忘了该按你的 Skill 流程走开始自由发挥。我试过比较有效的办法是在流程里显式加入状态节点。比如在 SKILL.md 中写每完成一步用一句话总结这一步的结果并说明下一步要做什么。这等于逼着 Claude 做阶段小结让整个任务在多轮对话中始终有迹可循。另一种方式是要求 Claude 在最终输出前做一次对照检查读取 SKILL.md 中的检查清单逐项确认输出是否满足要求。这种自检环节会显著减少因为对话过长导致的格式漂移尤其是处理长报告时特别明显。4.4 错误处理与边界兜底生产级的 Skill 不能只考虑正常流程还要考虑异常情况。我通常会在 SKILL.md 里写一个异常处理小节覆盖三种情况信息不足时先提问不猜测。输入格式混乱时先整理归类再开始处理。触发条件不符时明确告诉用户这个 Skill 帮不了而不是硬做。边界兜底的意义在于防止 Claude硬着头皮执行。比如用户没给任何本周工作内容结果 Claude 为了完成任务编了一堆进展这在真实工作场景里是绝对不能接受的。写清楚信息不足时必须停止并提问才能避免这种低级错误。5. 常见问题与排查技巧实录5.1 问题速查表我把自己和身边朋友在实际使用 Claude Skills 时踩过的坑整理了一份速查表覆盖面比较典型现象可能原因排查方向Skill 从来没被触发description 写得太窄或太泛检查描述里的触发场景增加常见说法输出格式不稳定SKILL.md 里没有强制约束增加必须按模板输出的强指令内容质量忽高忽低缺少示例文件增加 examples 目录并在主文件中要求先读示例错误触发什么任务都调用它description 与场景不匹配加排除性描述缩小适用范围长任务执行到一半偏离主题SKILL.md 流程不够结构化加入分步小结和检查清单换目录后无法加载相对路径写错检查子文件引用路径尽量用相对路径这张表是我排查问题时的第一反应路径。遇到问题先别急着重写整个 Skill按表里对应的方向微调大概率能解决。5.2 description 和命名的隐性规则关于 description有几个文档里不容易注意到的隐性规则。第一不要用否定式开头比如不要在处理邮件时使用语义匹配对这种写法支持很差容易被误读。第二不要在 description 里放完整的指令文本它只是索引写简洁的场景描述就够了详细流程放正文。第三控制长度描述过长会被截断反而影响匹配效果。命名上除了前面说的目录名规范还有一个容易被忽略的细节Skill 的 name 字段最好和目录名保持一致避免出现目录叫 weekly-report里面的 name 却是 report-helper 这种错位情况。命名不一致可能导致加载异常排查起来还挺隐蔽。5.3 实测心得与效率技巧最后分享几条我在大量实践中沉淀下来的效率技巧。第一建立一个测试用例集。给每个 Skill 准备一组固定的测试输入包括正常场景、边界场景和错误场景。这样每次修改后都能快速回归而不是凭感觉测试。第二Skill 也要分层管理。高频低复杂度的技能比如写 commit message尽量做得轻量SKILL.md 控制在几十行低频高复杂度的技能比如季度业务复盘可以做得重一些带完整的模板和示例。不要把简单技能复杂化否则每次调用的成本反而变高。第三定期审查你的 Skill 列表。我每个月会过一遍所有已创建的 Skill把两个月都没用过的归档或者删除。Skill 不是越多越好维护成本是真实存在的精简掉用不上的反而能提升常用 Skill 的加载准确性。在我实际使用中最深的体会是Claude Skills 的学习曲线不陡但天花板很高。刚开始你只需要把一段写得不错的 Prompt 存成文件就能感受到稳定性的提升但要做到生产级的可靠技能还是需要花时间打磨流程、补示例、做测试。建议先从一个你每周都要做的小任务入手做成一个能稳定复用的 Skill再慢慢拓展到更多场景。等你的技能库积累到一定量级你会发现 Claude 不再是一个每次都要从头交代的对话工具而是一个真正懂你工作方式的助手了。