Claude Skills完全指南：从SKILL.md结构到文档、代码、创意技能实战

写程序写得年头久了都会积攒下一套自己的“工作定式”代码怎么排版、注释写到什么程度、周报按什么结构写、需求文档分几个章节。这些经验以前只能靠复制粘贴旧文档来延续直到我完整梳理了一遍Claude官方Skills仓库之后才意识到2026年这个问题的标准答案已经变了——把个人规范变成一套可安装、可复用、可分享的“技能包”让AI在接手文档、代码、创意这三类活儿时自动遵循你预设的行为准则。这篇指南就围绕这个体系展开我会把仓库机制、目录结构、三类核心技能怎么写、怎么调试全部拆开讲清楚适合所有想让Claude稳定发挥而不是每次碰运气的开发者。1. Skills在解决什么问题告别“每次都要重新调教AI”先说一个我自己遇到过的场景。2025年年底我接手了一个跨平台桌面项目代码量不小每周要做一次Code Review。我最初的处理方式是每次审查前复制一大段提示词模板里面写了“请从安全性、性能、可维护性三个角度审查”但问题在于同样的提示词今天让Claude输出的是表格明天它就变成大段段落后天又换了评级口径。这种不稳定性在个人使用时尚可忍受一旦要在团队里统一质量基线就完全行不通。这就引出了Claude Skills这套机制的核心价值它把“提示词”从一次性交互文本升级为持久化的行为配置文件。一个技能本质上就是一个文件夹里放一份SKILL.md文件文件里用Markdown写清楚“我是什么技能、在什么场景下触发、具体按什么步骤干活、最终输出成什么格式”。Claude在对话中会根据用户需求自动匹配并加载这些技能而不是每次依靠用户手动粘贴规则。1.1 从“对话式调教”到“文件式配置”的本质区别以前用普通Prompt相当于每次开会前口头交代一遍工作要求用Skills相当于把岗位说明书放进员工抽屉里开工前它自己会去翻。这个区别在实际体验中非常明显。举个例子我写了一个叫meeting-minutes的技能专门用来处理会议纪要。没装这个技能之前我需要在对话里写“请根据以下会议记录生成纪要要求包含议题、决议、行动项行动项需要标注负责人和截止时间……”而装了技能之后我只需要把原始会议记录粘贴进去说一句“整理一下”Claude就会自动读取meeting-minutes技能里的配置按照预设的格式输出。这个过程中技能文件里的描述字段决定了Claude“什么时候该用它”正文部分决定了“它该怎么做”。另一个角度看这种机制也在强迫你梳理自己的工作流。因为写技能文件本身就是一种知识显性化你原以为自己“会写文档”真要把流程标准化成文字你会发现很多环节是模糊的。比如“代码审查”到底先看什么后看什么错误分级的标准是什么这些如果不定义清楚AI就只能在模糊地带自由发挥所以写技能的过程同时也是一次流程优化的机会。1.2 为什么官方Skills仓库值得优先关注社区里其实已经有了很多整理好的Prompt集合、插件市场那为什么非官方仓库不可我的判断是三点规范一致性官方仓库对SKILL.md的格式、字段定义、目录组织方式有一致的规范照着它学换一台机器、迁移一套配置不需要重新适应。演进速度快官方仓库会跟随Claude模型能力更新而调整推荐写法比如对长上下文场景下的技能拆分策略、对工具调用类技能的推荐格式都是别人摸过一遍坑之后沉淀出来的经验。配置的安全性第三方Prompt可能夹带恶意指令而官方仓库的Skill文件是公开透明的格式锁定之后可以自己审阅再安装不存在被隐藏指令劫持的风险。当然这不意味着只能使用官方仓库里的现成技能。我的建议是用官方仓库掌握标准用来构建自己的私有技能集这样才能真正贴合个人工作习惯。2. 动手前的底层认知SKILL.md的组成结构与设计逻辑想真正用好Skills仓库第一步不是急着复制别人的技能文件而是理解这个系统的“语法”。这套语法并不复杂核心概念就三个目录结构、frontmatter信息、正文指令。理解这三者的协作关系后面写任何技能都顺手。2.1 技能仓库在磁盘上的组织方式Claude会从两个位置读取技能全局技能目录和项目级技能目录。全局目录对应当前用户身份下的.claude/skills文件夹项目级目录则放在当前工作目录的.claude/skills下。两者采用完全相同的文件组织方式区别只在于可见范围放全局目录里所有对话都能用放项目目录里只有打开该项目时才会被加载。每个技能占一个子目录目录名就是技能名。目录内至少包含一个SKILL.md文件。比如.claude/skills/ ├── code-reviewer/ │ ├── SKILL.md │ └── scripts/ │ └── scan.py ├── meeting-minutes/ │ └── SKILL.md └── content-planner/ ├── SKILL.md └── assets/ └── template.md注意我在code-reviewer里放了一个scripts子目录这是官方仓库里一个非常有用的扩展能力技能不光能写指令还能附带脚本。当技能被触发时Claude可以调用这些脚本来执行检查、抓取信息、生成数据甚至可以把脚本的输出结果作为后续分析的输入。这使得技能从“静态提示词”升级为“小型自动化工具”。比如我可以让code-reviewer技能先运行一个静态检查脚本再把脚本输出的警告列表交给Claude二次分析整个流程一气呵成。2.2 SKILL.md的frontmatter定义技能“何时出场”SKILL.md文件的开头是三横线包裹的YAML信息最常见的是两个字段name和description。name是技能的唯一标识Claude用它来做上下文切换和引用description则是一段描述告诉模型“这个技能适合处理什么任务”。这段描述几乎直接决定了技能被调用的准确率。我踩过的一个典型坑是description写得过于宽泛。比如我给一个“周报生成”技能写的描述是“帮助用户生成周报”结果发现它在很多场景下都会跳出来甚至我让它写月度总结时它也调用周报技能。后来我把描述改成了“当用户提供本周完成的任务列表或希望按周报格式整理工作内容时使用适用于每周五的定期回顾输出包含本周进展、下周计划、风险与阻塞三项”调用准确率立刻显著提升。原因在于description越明确模型的语义匹配就越精准。2.3 SKILL.md正文定义技能“怎么干活”frontmatter之后就是正文正文是Markdown格式的指令用来描述行为流程。官方仓库推荐的结构通常包含角色定位、执行步骤、输出格式、注意事项四块但并不强制要求固定模板你可以根据技能类型自由组织。对比文档类、代码类、创意类三类任务正文设计的偏向也不同。文档类任务强调结构稳定需要明确章节顺序和格式模板代码类任务强调检查点和判定标准需要枚举出具体的检查维度创意类任务强调信息收集和发散路径需要定义输入条件、思维框架和收敛方式。后面第三部分我会分别给出可直接套用的写法。3. 文档 / 代码 / 创意三类技能怎样从零写成一个能用的版本理解了底层结构接下来就应该动手写真正的技能了。我从官方仓库里的思路出发结合自己的实际项目经验分别抽取出文档处理、代码审查、内容创意三个类别的关键技术点和一份可以直接改用的参考文件你拿到之后替换掉具体领域名词就能跑起来。3.1 文档类技能让输出格式成为肌肉记忆文档类技能是我个人使用频率最高的一类包括会议纪要、技术方案、需求分析、项目复盘。这类任务的核心痛点是格式不统一团队协作时尤其明显。技能要解决的就是把格式规范固化下来。这里有一份我实际用的会议纪要技能文件做了脱敏处理--- name: meeting-minutes description: 当用户提供会议讨论记录、语音转写文本或希望按统一格式整理会议纪要时使用。适合周会、项目同步会、评审会输出格式固定为六段式结构。 --- 你是团队的项目助理负责将会议内容整理为标准格式的纪要。 ## 处理步骤 1. 阅读用户提供的会议材料提取关键信息。 2. 识别材料中出现的决策事项、待办任务和风险点。 3. 按以下模板输出不得遗漏章节。 ## 输出模板 # 会议纪要 - 会议主题一句话概括 - 会议时间根据材料推断缺失则标注待补充 - 参会角色用角色名替代人名如产品负责人、前端开发 ## 1. 背景与目标 简述本次会议要解决的问题。 ## 2. 讨论要点 - 按主题分条列出每条不超过三行。 ## 3. 决策记录 | 编号 | 决策内容 | 依据 | | --- | --- | --- | ## 4. 行动项 | 任务 | 负责人 | 截止时间 | 关联决策 | | --- | --- | --- | --- | ## 5. 风险与阻塞 - 风险描述 影响范围 初步应对建议 ## 注意事项 - 若材料中没有明确信息标注“材料中未提及”不得编造。 - 行动项必须明确负责人负责人不明时标注【待指派】。这份文件的关键设计在于“处理步骤”和“输出模板”分离。处理步骤规定的是思考路径输出模板规定的是交付物格式。Claude在执行时先按步骤走再套模板输出这样每一步都可控。实测下来团队拿到的会议纪要整齐划一不再有“今天表格明天段落”的随机情况。文档类技能的进阶玩法是加入辅助文件。比如对于技术方案类技能我会在assets文件夹里保存一份过往的优秀方案作为参考案例正文里写“参考assets/example-plan.md的风格”。这样每次生成方案时都有具体的风格锚点而不是抽象的“要求语言精炼”。3.2 代码类技能把Review清单和修复建议做成自动化流程代码类技能的应用场景更丰富除了代码审查还有重构、测试用例生成、接口文档生成、Bug分析。代码类技能与文档类最大的不同在于它往往需要“前置检查动作”而不仅仅是信息整理。我写代码审查技能时参考了官方仓库里对“应不应该用脚本”的判断标准如果检查目标是纯文本层面的用规则描述即可如果涉及工程级扫描就应该捆绑脚本。比如一个原子性的错误判断——检测函数是否缺少类型注解——完全可以靠模型指令完成但要统计整个仓库中未捕获的异常分布最好运行一个Python脚本来聚合数据。下面是我目前挂在项目目录下的code-reviewer技能的主干结构--- name: code-reviewer description: 当用户提供一段代码或一个代码文件路径希望进行审查、发现Bug、评估代码质量时使用。适用于提交前的自查、Code Review、代码重构前的评估。 --- 你是资深后端工程师从正确性、性能、安全性、可维护性四个维度进行代码审查。 ## 前置动作 如果用户提供的是文件路径先读取文件内容如果仓库内有scripts/scan.py运行它获取基础检查结果。 ## 审查维度 1. 正确性是否存在空指针、数组越界、并发竞争、资源未关闭等问题。 2. 性能是否存在不必要的循环嵌套、重复查询、大对象复制。 3. 安全性是否有SQL注入、命令注入、敏感信息硬编码。 4. 可维护性命名是否清晰、函数是否过长、职责是否单一。 ## 输出格式 - 整体评价一句话说明代码质量等级优/良/需改进。 - 问题列表按下表输出按严重程度排序 | 严重级别 | 位置 | 问题描述 | 建议修复 | | --- | --- | --- | --- | - 补充说明列出值得肯定的设计方便团队互相学习。 ## 约束 - 每条建议必须给出具体的修改方向禁止只报错不给方案。 - 对不确定的问题标注“疑似”区分事实判断和推测判断。这套配置的实用之处在于将审查维度前置枚举Claude就不会随意发挥。你也许注意到我在“前置动作”里写了运行scan.py的逻辑这就是脚本与指令协同的典型例子。脚本负责机械扫描模型负责语义分析二者互补。对于代码类技能我还有一条建议description里尽量不要放具体编程语言名除非你真的只希望它在遇到该语言时触发。因为实际调用时你手里的代码文件往往混着多种语言把描述写成“分析Python代码质量”会降低触发率不如写成“分析用户提供的代码质量常见语言包括Python、JavaScript、Go”。3.3 创意类技能给发散思维设定一套可复用的流程创意类任务看起来最“反模板化”但恰恰最需要结构。没有结构时AI容易在“嗯、不错、然后呢”的循环里空转有了流程才能把灵感一步步收敛成可执行方案。Claude官方Skills仓库里对创意类技能的设计逻辑是先诊断需求再分方向探索最后收敛成提案。我做过一个content-planner技能用途是生成内容选题和策划纲。它的处理步骤是向用户确认目标目标受众是谁内容目的为了引流、品牌曝光还是内部培训分析用户给的参考素材提炼核心概念。输出“三个方向的独立方案”每个方案包含核心主张、内容大纲、独特卖点。给每个方案标注适用场景和预期效果让用户选择。写出这个流程之后我才意识到创意技能的关键不在于“教AI怎么创意”而在于“规定输出的比较维度”。当AI被要求从多角度给出方案时它自然会调用更多知识面再配合“输出适用场景”这一约束方案的落地感就会显著增强。所以写创意类技能时别把重点放在让AI“想得更开”要放在让AI“想得更有结构”。比如对选题类技能规定了“必须输出用户痛点列表 解决方案角度 标题候选池”三块之后AI给出的结果立刻比无脑发散时实用很多。4. 完整实操从技能设计到首次生效的六个关键环节前面拆完了原理和三份参考写法这一部分就进入实战节奏。我会按实际操作的顺序把从0到1安装、调试、验证一个技能的完整流程走一遍顺手把参数设计背后的考量记录下来。4.1 创建技能目录与文件骨架第一步很简单在合适的位置创建技能目录。如果是个人通用技能放在全局目录如果是某个具体项目专用放在项目目录。以全局技能为例打开终端执行mkdir -p ~/.claude/skills然后为具体技能建子目录比如mkdir -p ~/.claude/skills/doc-writer touch ~/.claude/skills/doc-writer/SKILL.md需要注意的是目录名和SKILL.md中的name字段的关系。官方规范建议二者保持一致这样模型在引用技能时不会混淆。比如目录名叫doc-writer那么name字段也写doc-writer。别看这是个小细节不一致时排查起来非常隐蔽你可能会以为是加载逻辑出问题其实是引用名对不上。4.2 编写frontmatter明确技能边界这一步是整个技能能否被准确调用的关键。写description时牢记一个原则“描述你在什么情况下使用这个技能而不是描述这个技能能做什么”。同样一个文档技能差别很大。推荐写法“当用户要求撰写技术设计文档且提到需包含背景、方案对比、风险评估时使用”而不是“帮助用户写文档”。前者给了模型丰富的触发锚点后者几乎能匹配所有文档任务导致误触率飙升。我通常会在description里写两到三个具体场景外加一到两个明确不适用场景。比如“不适用于用户仅要求翻译或润色现有文本的场景”这是一种负面排除法能在语义模糊时帮模型快速决策。4.3 编写正文指令用两层结构稳定输出正文我建议明确区分为“处理步骤”和“输出格式”。处理步骤控制思维过程输出格式控制交付物。这两个部分分开写比写成一整段流水的效果要好很多。原因在于模型对步骤清单的遵循率显著高于对散文式指令的遵循率。当步骤是序号列表时模型会按顺序执行当步骤被藏在段落里时模型可能直接跳过中间环节。另外输出格式部分能定义表格就用表格表格是一种强约束模型填充表格时比自由文本更不容易偏离结构。4.4 用真实数据测试技能触发效果写完文件之后立刻打开Claude进行实测。我的标准流程是准备三条测试输入分别覆盖典型场景、边缘场景、错误场景。以doc-writer技能为例典型场景输入“帮我写一份登录模块的技术设计文档需要包含背景、方案对比、风险评估。”边缘场景输入“帮我写个技术设计文档”这种极简描述。错误场景输入“帮我把这段话翻译成英文”。观察结果分两层第一层是技能有没有被触发第二层是触发后的输出是否符合格式规范。边缘场景可能触发可能不触发这取决于描述写得是否精准错误场景如果触发了说明排除条件没生效必须改描述。4.5 参数微调与迭代优化首次测试结果很少是完美的更多情况是需要迭代两到三轮。以我在调试code-reviewer时遇到的情况为例最初版本只写了四个审查维度实测后发现问题AI对“性能”维度的检查偏浅经常会漏掉数据库查询次数的分析。于是我在“性能”里补充了一条子规则——“关注循环中是否有查询、是否可以在循环外预加载数据”。加上这条之后审查质量立刻提升了一个台阶。这种迭代逻辑提示我们技能文件不是一次性写成的而是要根据你在真实使用中发现的短板不断补规则。官方仓库里的成熟技能也不是从天而降的它们背后都有大量的使用反馈作为支撑。4.6 代码类技能如何捆绑脚本并正确调用技能目录里可以放scripts文件夹Claude支持在技能文件里引用相对路径来调用脚本。例如cd ~/.claude/skills/code-reviewer/scripts python scan.py /path/to/target在SKILL.md里就会写成如果scripts/scan.py存在先运行它获取静态检查结果再基于结果进行语义分析。这一步设计时要注意脚本路径用的是相对路径而不是绝对路径。写了绝对路径换台机器就失效得不偿失。另外脚本的退出码处理也要写清楚如果脚本运行失败是终止整个技能流程还是跳过脚本继续分析。我给的建议是后者脚本失败通常是因为环境问题或路径问题不应该阻塞核心分析任务。5. 常见问题与排查技巧实录几乎所有人初次接触Skills仓库时都会遇到几个躲不开的坑。我把自己过去半年反复踩到过的那些问题整理成清单省得你再走一遍弯路。5.1 技能完全没有被加载对话中毫无反应这个问题十有八九是目录位置错误。Claude只从特定的两个目录读取技能放在其他位置都不会加载。第一步检查技能目录是否存在于正确位置第二步检查SKILL.md文件名是否完全一致大小写也要对上。我曾经把文件命名为skill.md而不是SKILL.md结果始终不生效排查了很久才发现是大小写问题。另外还有一种经常被忽视的情况技能被放在项目目录里但你当前打开的对话并不属于该项目。项目级技能的加载范围有严格限制没有打开对应工作目录时项目技能不可见。5.2 技能被其他通用指令“抢跑”表现不稳定当对话中同时存在多个可匹配的技能时Claude可能会选择与你预期不符的那一个。解决这个问题的思路是深入挖掘description的独特性。比如你的项目里同时有week-report和meeting-minutes两个技能用户说“整理一下这周的工作”模型可能匹配任何一个。这时候就需要在description里增加触发边界条件如“当用户提供本周任务清单并要求按周报格式输出时使用”把“周报格式”这个鲜明特征锁死。5.3 frontmatter格式错误导致解析失败YAML格式对缩进和引号有一定要求稍有不慎就解析失败。技能文件加载失败通常会在控制台日志或界面状态中给出提示。如果发现技能毫无反应先检查frontmatter中是否有非法字符比如中英文冒号混用、Tab缩进、未闭合引号。这里我的经验是全部采用ASCII字符编写frontmatter中文字符只出现在description的值内容里不要出现在字段名中也不要出现在缩进里。5.4 技能引用的辅助文件路径失效当技能目录内包含scripts或assets时路径引用问题会很常见。官方推荐的做法是在SKILL.md中使用相对路径且路径基准是技能目录本身。在实测中还要注意工作目录的影响Claude执行脚本时的工作目录可能不是技能目录这时候需要显式处理。我会在技能正文开头加一句全局说明“本技能内所有相对路径均相对于技能目录”。这样模型在解析路径时有明确依据不太容易产生混淆。5.5 长期维护技能库也需要版本管理技能文件改着改着就不知道改了哪条规则、什么时候改的。我自己的做法是把整个.claude/skills目录纳入Git管理每一次调整提交一次commitcommit信息写清楚改了什么原因。这样一旦新版行为异常可以直接回退到上一版。对于团队协作场景可以把技能仓库放在远程Git仓库里成员各自拉取用同一套技能基准。这也是官方Skills仓库设计里很值得学习的一点它不把技能视为一次性配置而是一个有版本、有迭代过程的工程产物。6. 几个值得长期坚持的实践习惯玩Skills仓库这段时间有一些体会是文档里读不到的只有在大量使用之后才会沉淀下来。第一个体会是“技能从薄到厚再从厚到薄”。第一版技能文件往往写得很长生怕漏掉什么用久了以后你会发现很多规则是多余的删掉之后行为反而更稳定。我曾经把会议纪要技能的模板加了九个章节结果AI为了填满模板开始注水。后来收敛回六个章节质量反而更扎实了。所以每个季度值得回头审视自己维护的技能文件找出那些“为了存在而存在”的内容。第二个体会是“不要试图让一个技能包办所有事”。技能设计有很强的单一职责原则。把“写周报”和“写季度述职”合并成一个技能表面上省了文件数量实际上两种任务的输出格式差异很大揉在一起只会让两边的输出水准都被拉低。宁可多建几个技能文件也不要在一个技能里塞入过多的分支逻辑。第三个体会是老生常谈但值得强调技能是给人用的工具不是给你强迫症式的仪式感。判断一个技能是否有价值的唯一标准是它有没有减少你的重复工作。如果一个技能你写完以后从来没有触发过那就说明它对你是多余的删掉它才是正确的选择。这套机制用顺手之后你会发现真正提升效率的其实不是AI本身而是你在整理技能文件时重新梳理过的那些流程和标准。Claude官方Skills仓库给我们提供的是一个很好的模板框架而框架内的内容恰好是每个开发者自己多年经验中最有价值的沉淀。