1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它的时候会以为是某种新编程语言或者框架其实不是。这里的 skills特指围绕 Claude 生态尤其是 Claude Code 和 Claude Desktop构建的一套可复用的能力模块机制。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张技能卡里写清楚了在什么场景下该做什么、怎么做、按什么格式输出。我最早接触这个概念是在折腾 Claude Code 的时候。当时我想让它帮我处理一些重复性的代码审查工作每次都要把同样的要求重新打一遍烦得不行。后来发现社区里已经有人把这类需求封装成了 SKILL.md 文件直接丢进指定目录就能用那一刻的感觉就像是从手动挡换成了自动挡。这也是为什么“skills推荐”“常用skills”“skills技能库网址”这些词会被反复搜索——大家都想找到现成的、好用的技能包而不是从零开始写。那 skills 到底解决了什么问题简单说三个痛点。第一重复提示词的浪费。你每次让 AI 做同一类任务都要重新描述需求、格式、注意事项效率极低。第二输出质量不稳定。同样的需求换个时间问AI 给出的格式和深度可能完全不一样。第三团队协作困难。你调好的一套提示词没法直接分享给同事只能靠截图或者口口相传。skills 机制把这三件事一次性解决了写一次存成文件随时调用还能直接分享。适合谁来了解这个内容我梳理了一下大概三类人受益最明显。一是日常用 Claude Code 写代码的开发者尤其是前端开发和全栈方向skills 能帮你把代码规范、组件模板、审查清单都固化下来。二是做数学建模和数据分析的人华为杯建模比赛里已经有人用 codex skills 来辅助建模流程了效果比纯手搓提示词好很多。三是内容创作者和 AI 漫剧制作者把分镜逻辑、角色设定、台词风格写成 skill每次生成都能保持一致性。哪怕你只是刚接触 Claude 的新手了解 skills 也能让你少走很多弯路。2. skills 的核心机制拆解SKILL.md 到底写了什么2.1 一个 skill 的最小结构很多人以为 skill 是什么高深的东西其实拆开看非常简单。一个标准的 skill 就是一个文件夹里面至少包含一个SKILL.md文件。这个文件用 Markdown 写成头部有一段类似配置的元信息正文部分就是给 AI 看的指令。我拿一个实际例子来说明下面是我自己写的一个代码审查 skill 的简化版本--- name: code-review description: 对指定代码进行结构化审查输出问题清单和改进建议 --- # 代码审查技能 ## 触发条件 当用户要求审查代码、检查代码质量、或者提交了需要 review 的代码片段时使用。 ## 审查维度 1. 命名规范变量、函数、类名是否清晰且符合语言惯例 2. 错误处理是否有未捕获的异常、边界条件是否覆盖 3. 性能隐患是否存在不必要的循环嵌套、重复计算 4. 可读性函数长度是否超过 50 行、注释是否到位 ## 输出格式 按严重程度分三级列出问题 - 严重可能导致 bug 或安全问题 - 建议影响可维护性但不影响功能 - 优化锦上添花的改进点 每条问题需给出位置、原因、修改建议。你看没有什么神秘的。核心就是三件事什么时候用触发条件、做什么审查维度、怎么输出格式要求。这三件事写清楚了一个 skill 就能稳定工作了。2.2 为什么是 Markdown 而不是代码这里有个设计上的考量值得说一下。skills 用 Markdown 而不是 JSON 或 YAML 来写正文是有道理的。Markdown 的优势在于它既是结构化的有标题层级、列表、表格又是自然语言的AI 读起来跟读人类写的文档一样自然。如果你用纯 JSON 来描述审查规则AI 理解起来反而容易出偏差因为 JSON 的表达力有限很多细微的语义需要额外解释。我试过两种写法同样的审查逻辑用 Markdown 写的版本在实际使用中输出质量明显更稳定。原因也不复杂Markdown 的标题和列表天然带有层次感AI 在解析的时候能清楚知道哪些是主规则、哪些是子规则、哪些是例外情况。而 JSON 的嵌套结构虽然机器友好但对 AI 来说反而增加了解析负担。2.3 skills 的加载与触发逻辑skill 写好之后怎么让 Claude 知道它的存在这就涉及到加载机制。目前主流的做法是把 skill 文件夹放在特定目录下Claude Code 启动时会扫描这个目录把所有 skill 的元信息name 和 description读进去。当你提问的时候系统会根据你的问题内容和 skill 的 description 做匹配匹配上了就把完整的 SKILL.md 内容注入到上下文里。这个机制有个关键点description 写得好不好直接决定了 skill 能不能被正确触发。我踩过这个坑。最开始我写了一个 skilldescription 只写了“代码相关”结果 Claude 几乎从来不调用它因为“代码相关”太模糊了跟用户的任何编程问题都能沾边反而匹配不上。后来改成“当用户要求审查代码质量、检查命名规范、或者提交代码片段请求 review 时使用”触发率立刻上来了。提示description 要写得具体包含明确的触发场景关键词但也不要太窄否则会漏掉合理的调用时机。我的经验是控制在 30 到 60 个字之间覆盖两到三个典型场景。3. 从零写一个能用的 skill完整实操流程3.1 先想清楚三件事再动手很多人一上来就开始写 SKILL.md写到一半发现逻辑混乱又回头改。我的建议是先在纸上或者备忘录里回答三个问题第一这个 skill 解决什么重复性问题如果你只是偶尔用一次那没必要写成 skill直接打提示词就行。只有当某个任务你每周至少要做两三次而且每次的要求都差不多才值得封装。第二输入是什么输出是什么输入可能是用户的一段代码、一篇文章、一个数学问题。输出可能是固定格式的报告、代码片段、表格。把输入输出的边界想清楚skill 的正文才不会跑偏。第三有哪些容易出错的点比如你让 AI 做数学建模它可能会忽略单位换算你让它写前端组件它可能不遵守你的命名规范。这些容易出错的点就是 skill 正文里需要特别强调的地方。3.2 目录结构和文件命名想清楚之后开始建文件夹。我推荐的结构是这样的skills/ code-review/ SKILL.md math-modeling/ SKILL.md frontend-component/ SKILL.md每个 skill 一个独立文件夹文件夹名用英文小写加连字符跟 SKILL.md 里的 name 保持一致。这样做的好处是当你 skill 多了之后一眼就能看出哪个文件夹对应哪个技能。我见过有人把所有 skill 都塞在一个文件夹里文件名还起得乱七八糟后期维护起来非常痛苦。SKILL.md 的头部元信息目前最常用的是两个字段name和description。name 就是技能名description 是触发描述。有些实现还支持version和author但这两个不是必须的。我个人的习惯是加上 version方便后续迭代的时候追踪改了哪些东西。3.3 正文写作的四个关键模块正文部分我一般分成四块来写这个结构是我试了七八个 skill 之后固定下来的效果最稳。第一块是角色设定。告诉 AI 在这个 skill 里它扮演什么角色。比如代码审查 skill 里我会写“你是一名有十年经验的资深工程师擅长发现代码中的潜在问题”。这个设定不是摆设它会影响 AI 的输出语气和关注重点。实测下来加了角色设定的 skill 比不加的输出专业度明显高一个档次。第二块是工作流程。把任务拆成有序的步骤一步一步写清楚。比如数学建模 skill 里我会写第一步理解问题背景第二步确定模型类型第三步给出求解思路第四步验证结果合理性。步骤不要太多五到七步比较合适太多了 AI 容易漏掉中间的步骤。第三块是输出格式。这块最重要也最容易被忽视。你必须明确告诉 AI 输出应该长什么样。是用表格还是列表要不要加标题字数控制在多少我一般会直接给一个输出模板让 AI 照着填。比如## 问题清单 | 严重程度 | 位置 | 问题描述 | 修改建议 | |---------|------|---------|---------| | 严重 | 第 23 行 | 未处理空指针 | 增加 null 检查 |第四块是边界和例外。告诉 AI 什么情况下不要用这个 skill或者遇到什么情况需要特殊处理。比如代码审查 skill 里我会写“如果代码片段少于 5 行不需要输出完整报告直接给出简短建议即可”。这块内容能有效防止 AI 在简单场景下过度输出。3.4 测试和迭代skill 写完不是就完了必须测试。我的测试方法分三步。第一步用三个典型场景去触发它看输出是否符合预期。第二步用两个边缘场景去测试看它会不会误触发或者输出异常。第三步故意在输入里埋一些坑比如格式混乱的代码、缺少关键信息的问题看 AI 能不能合理处理。测试过程中发现的问题直接回到 SKILL.md 里改。我一般会迭代三到五轮才能把一个 skill 调到比较稳定的状态。第一版往往输出太长第二版可能触发条件太窄第三版调整格式第四版补充例外情况。这个过程急不得但一旦调好后面用起来就非常省心。注意每次修改 SKILL.md 之后记得重启 Claude Code 或者重新加载 skill 目录否则改动不会生效。这个坑我踩过好几次改了文件发现没反应以为是写法有问题其实是没重新加载。4. 不同场景下的 skills 实战案例4.1 前端开发场景组件生成 skill前端开发是 skills 用得最多的场景之一。我给自己写了一个 React 组件生成 skill核心逻辑是这样的当我说“生成一个 XXX 组件”的时候AI 会按照我预设的规范来输出。规范包括使用函数式组件加 Hooks、样式用 CSS Modules、Props 必须有 TypeScript 类型定义、组件文件里必须包含单元测试的基本结构。这个 skill 帮我省了大量时间。以前每次让 AI 写组件都要重复交代这些规范而且它经常忘记加类型定义。现在只要说一句“生成一个用户卡片组件”出来的代码直接就能用命名规范、类型定义、测试骨架全都齐了。我统计过光是这一项每周至少省下两三个小时的重复沟通时间。写这类 skill 的关键在于把团队规范写死。你不要指望 AI 自己猜到你想要什么风格必须明确写出来。比如命名用 PascalCase 还是 kebab-case导出用 default 还是 named这些细节都要在 skill 里定好。4.2 数学建模场景建模流程 skill数学建模比赛的时间压力很大通常三天要完成从选题到论文的全过程。我帮参加华为杯的朋友写过一个建模 skill把整个流程拆成了几个固定阶段问题分析、模型选择、求解方法、灵敏度分析、论文结构。这个 skill 最大的价值在于防止遗漏关键步骤。人在紧张的时候容易跳过灵敏度分析或者模型验证直接写结论。skill 里明确要求每个阶段必须输出对应的内容AI 会按部就班地引导你走完整个流程。朋友反馈说用了这个 skill 之后论文的完整性明显提升评委最容易挑的“缺少模型验证”这类问题基本不会再出现了。写建模 skill 的难点在于模型选择部分不能写太死。数学建模的题目千变万化你不能规定死用哪种模型。我的做法是给出一个决策树如果问题是优化类优先考虑线性规划或遗传算法如果是预测类优先考虑时间序列或回归分析如果是评价类优先考虑层次分析法或熵权法。这样既有指导性又保留了灵活性。4.3 内容创作场景AI 漫剧脚本 skillAI 漫剧是最近很火的一个方向但很多人做出来的东西前后风格不一致角色说话的方式每一集都在变。我帮一个做漫剧的朋友写了一个脚本 skill核心是维护一个角色设定表和世界观规则每次生成新脚本的时候AI 会先读取这些设定确保新内容跟之前的保持一致。这个 skill 的结构比较特殊它包含了一个额外的characters.md文件里面记录了每个角色的性格、说话习惯、与其他角色的关系。SKILL.md 里写明了生成脚本时必须参考这个文件。实测下来角色一致性问题基本解决了观众也不会再吐槽“这个人怎么突然换了性格”。4.4 代码审查场景自动化 review skill代码审查 skill 是我用得最频繁的一个。它的触发条件写得很明确当用户提交代码片段并请求审查时使用。审查维度包括命名规范、错误处理、性能隐患、可读性、安全性五个方面。输出格式是分级问题清单每条问题都要求给出位置、原因和修改建议。这个 skill 有个细节我想特别说一下我在正文里加了一条规则“如果代码没有问题不要强行找问题直接说‘未发现明显问题’即可”。这是因为早期版本里AI 为了显得有用经常在一些完全没问题的代码里挑刺比如把“变量名可以更短”这种无关痛痒的建议也列出来反而干扰了真正的审查重点。加了这条规则之后输出质量明显提升。5. 安装、配置与常见问题排查5.1 Claude Code 的安装与 skill 目录配置Claude Code 的安装方式根据操作系统不同有所差异。Windows 用户需要注意某些版本可能需要启用虚拟机平台功能才能正常运行。安装完成之后skill 目录的默认位置通常在用户主目录下的.claude/skills文件夹。如果你用的是 VS Code 集成的 Claude Code配置方式略有不同需要在 VS Code 的设置里指定 skill 目录路径。我建议把 skill 目录放在一个固定的、容易找到的位置比如~/my-skills然后在 Claude Code 的配置里指向这个目录。这样做的好处是你可以在多个项目之间共享同一套 skill不用每个项目都复制一遍。配置好之后启动 Claude Code 时它会自动扫描目录下的所有 skill 文件夹。提示如果你在命令行输入claude提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没有配置好。检查一下安装路径是否加入了 PATH或者直接用完整路径来启动。5.2 skill 不触发怎么办这是最常见的问题。你写了一个 skill但 Claude 好像完全不知道它的存在。排查思路按顺序来第一检查文件位置对不对。SKILL.md 必须在 skill 文件夹的根目录下不能多套一层。我见过有人写成skills/code-review/skill/SKILL.md多了一层文件夹导致扫描不到。第二检查头部元信息格式。---包裹的元信息块必须放在文件最开头前面不能有空行或者注释。name 和 description 的冒号后面要有空格。第三检查 description 是否太模糊。前面说过“代码相关”这种描述基本触发不了。改成具体的场景描述比如“当用户要求审查代码、检查代码质量时使用”。第四检查是否重新加载了。修改 SKILL.md 之后必须重启 Claude Code 或者执行重新加载命令否则改动不生效。5.3 skill 输出格式不稳定怎么办有时候 skill 能触发但输出格式每次都不一样。这个问题通常出在正文的格式要求写得不够具体。我的经验是不要用文字描述格式直接给模板。比如你要表格就直接在 SKILL.md 里写一个 Markdown 表格的示例让 AI 照着填。你要分三级标题就直接写出### 一级、### 二级的示例。另一个技巧是在正文末尾加一句“严格按照上述格式输出不要添加额外的解释性文字”。这句话能有效减少 AI 的自由发挥。我试过加了这句话之后格式一致性从大概七成提升到了九成以上。5.4 多个 skill 冲突怎么处理当你装了很多 skill 之后可能会出现两个 skill 同时被触发的情况。比如你有一个“代码审查”skill 和一个“代码优化”skill用户提交代码请求改进的时候两个都可能被匹配上。这时候 Claude 可能会把两个 skill 的指令混在一起执行输出变得混乱。解决办法有两个。一是在 description 里明确区分触发场景让两个 skill 的适用范围不重叠。二是在 skill 正文里加优先级说明比如“如果同时匹配到代码优化 skill优先执行本 skill 的审查流程审查完成后再考虑优化建议”。我一般用第一种方法从源头避免冲突。5.5 常见问题速查表问题现象可能原因解决方法skill 完全不触发文件位置错误或元信息格式不对检查 SKILL.md 是否在文件夹根目录元信息是否以---开头skill 偶尔触发description 太模糊或太窄调整 description覆盖两到三个典型场景关键词输出格式每次不同格式要求写得太抽象直接在 SKILL.md 里给输出模板修改后不生效没有重新加载重启 Claude Code 或执行重新加载命令多个 skill 冲突触发场景重叠调整 description 区分场景或在正文里加优先级规则输出太长或太短没有字数约束在正文里明确要求字数范围6. 进阶技巧让 skill 真正融入日常工作流6.1 组合使用多个 skill单个 skill 的能力有限但多个 skill 组合起来就能覆盖完整的工作流。我现在的做法是把日常开发流程拆成几个阶段每个阶段对应一个 skill。比如“需求分析”阶段用需求拆解 skill“编码”阶段用组件生成 skill“审查”阶段用代码审查 skill“文档”阶段用文档生成 skill。每个 skill 各司其职串起来就是一条完整的流水线。组合使用的关键是要定义好 skill 之间的输入输出衔接。比如代码审查 skill 的输出格式要能被文档生成 skill 直接读取。我一般会在审查 skill 的输出里保留一个结构化的摘要部分文档 skill 读取这个摘要就能生成变更日志。6.2 版本管理与团队共享skill 写多了之后版本管理就变得重要了。我的做法是把整个 skills 目录纳入 Git 管理每次修改都提交一次commit message 写清楚改了什么、为什么改。这样万一改坏了可以随时回滚到之前的版本。团队共享的话直接把 Git 仓库分享给同事就行。每个人拉下来之后在自己的 Claude Code 配置里指向这个目录。如果团队有特殊的规范可以在仓库里放一个 README说明每个 skill 的用途和使用方法。我见过一些团队把 skill 仓库当成团队知识库来维护新成员入职直接拉下来就能用省去了大量培训成本。6.3 持续迭代的思路skill 不是写完就固定不变的。随着你使用场景的变化skill 也需要不断调整。我一般每个月会回顾一次自己常用的 skill看看哪些地方经常需要手动纠正 AI 的输出这些纠正点就是 skill 需要补充的规则。另一个迭代思路是收集失败案例。每次 skill 输出不符合预期的时候把输入和输出都记下来分析是哪个环节出了问题。是触发条件不对还是正文里的规则不够明确还是输出格式没有约束好找到原因之后针对性修改比盲目调整有效得多。提示我习惯在 SKILL.md 的末尾加一个“更新日志”区域记录每次修改的内容和原因。这样过几个月回头看能清楚知道这个 skill 是怎么一步步演化的也方便判断某条规则是不是已经过时了。6.4 关于 skill 库的选择建议现在网上已经有不少公开的 skill 库可以下载但我的建议是不要盲目全装。skill 装太多会导致触发混乱而且很多公开 skill 的质量参差不齐。我的做法是先看 description 判断是否跟自己的工作场景匹配匹配的下载下来之后先在小范围测试确认输出质量稳定之后再正式纳入日常使用。另外公开 skill 下载下来之后最好根据自己的习惯做一轮定制。别人的规范不一定适合你比如命名风格、输出格式这些改成自己顺手的样式用起来才顺手。我一般会把下载的 skill 当作参考模板取其结构换其内容最终形成一套完全贴合自己工作流的技能库。6.5 一个容易被忽视的细节skill 的命名最后说一个很多人不注意的点skill 的命名。name 字段虽然不直接参与触发匹配但它会影响你在使用时的调用体验。我建议 name 用英文小写加连字符简短且能表意。比如code-review、math-modeling、frontend-component。不要用中文也不要用太长的名字否则在命令行里输入的时候很麻烦。description 则相反要写得详细具体。这两者的分工是name 给人看description 给系统看。把这两个字段各司其职skill 的可用性会提升很多。我在实际使用中最大的体会是skills 这套机制的价值不在于技术有多复杂而在于它强迫你把重复性的工作结构化地沉淀下来。写第一个 skill 的时候可能觉得麻烦但写到第五个、第十个的时候你会发现自己的工作效率有了质的提升。那些以前需要反复交代的事情现在一句话就能搞定省下来的时间和精力可以放在真正需要创造力的地方。
Claude Skills 实战指南：从 SKILL.md 编写到多场景工作流落地
1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它的时候会以为是某种新编程语言或者框架其实不是。这里的 skills特指围绕 Claude 生态尤其是 Claude Code 和 Claude Desktop构建的一套可复用的能力模块机制。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张技能卡里写清楚了在什么场景下该做什么、怎么做、按什么格式输出。我最早接触这个概念是在折腾 Claude Code 的时候。当时我想让它帮我处理一些重复性的代码审查工作每次都要把同样的要求重新打一遍烦得不行。后来发现社区里已经有人把这类需求封装成了 SKILL.md 文件直接丢进指定目录就能用那一刻的感觉就像是从手动挡换成了自动挡。这也是为什么“skills推荐”“常用skills”“skills技能库网址”这些词会被反复搜索——大家都想找到现成的、好用的技能包而不是从零开始写。那 skills 到底解决了什么问题简单说三个痛点。第一重复提示词的浪费。你每次让 AI 做同一类任务都要重新描述需求、格式、注意事项效率极低。第二输出质量不稳定。同样的需求换个时间问AI 给出的格式和深度可能完全不一样。第三团队协作困难。你调好的一套提示词没法直接分享给同事只能靠截图或者口口相传。skills 机制把这三件事一次性解决了写一次存成文件随时调用还能直接分享。适合谁来了解这个内容我梳理了一下大概三类人受益最明显。一是日常用 Claude Code 写代码的开发者尤其是前端开发和全栈方向skills 能帮你把代码规范、组件模板、审查清单都固化下来。二是做数学建模和数据分析的人华为杯建模比赛里已经有人用 codex skills 来辅助建模流程了效果比纯手搓提示词好很多。三是内容创作者和 AI 漫剧制作者把分镜逻辑、角色设定、台词风格写成 skill每次生成都能保持一致性。哪怕你只是刚接触 Claude 的新手了解 skills 也能让你少走很多弯路。2. skills 的核心机制拆解SKILL.md 到底写了什么2.1 一个 skill 的最小结构很多人以为 skill 是什么高深的东西其实拆开看非常简单。一个标准的 skill 就是一个文件夹里面至少包含一个SKILL.md文件。这个文件用 Markdown 写成头部有一段类似配置的元信息正文部分就是给 AI 看的指令。我拿一个实际例子来说明下面是我自己写的一个代码审查 skill 的简化版本--- name: code-review description: 对指定代码进行结构化审查输出问题清单和改进建议 --- # 代码审查技能 ## 触发条件 当用户要求审查代码、检查代码质量、或者提交了需要 review 的代码片段时使用。 ## 审查维度 1. 命名规范变量、函数、类名是否清晰且符合语言惯例 2. 错误处理是否有未捕获的异常、边界条件是否覆盖 3. 性能隐患是否存在不必要的循环嵌套、重复计算 4. 可读性函数长度是否超过 50 行、注释是否到位 ## 输出格式 按严重程度分三级列出问题 - 严重可能导致 bug 或安全问题 - 建议影响可维护性但不影响功能 - 优化锦上添花的改进点 每条问题需给出位置、原因、修改建议。你看没有什么神秘的。核心就是三件事什么时候用触发条件、做什么审查维度、怎么输出格式要求。这三件事写清楚了一个 skill 就能稳定工作了。2.2 为什么是 Markdown 而不是代码这里有个设计上的考量值得说一下。skills 用 Markdown 而不是 JSON 或 YAML 来写正文是有道理的。Markdown 的优势在于它既是结构化的有标题层级、列表、表格又是自然语言的AI 读起来跟读人类写的文档一样自然。如果你用纯 JSON 来描述审查规则AI 理解起来反而容易出偏差因为 JSON 的表达力有限很多细微的语义需要额外解释。我试过两种写法同样的审查逻辑用 Markdown 写的版本在实际使用中输出质量明显更稳定。原因也不复杂Markdown 的标题和列表天然带有层次感AI 在解析的时候能清楚知道哪些是主规则、哪些是子规则、哪些是例外情况。而 JSON 的嵌套结构虽然机器友好但对 AI 来说反而增加了解析负担。2.3 skills 的加载与触发逻辑skill 写好之后怎么让 Claude 知道它的存在这就涉及到加载机制。目前主流的做法是把 skill 文件夹放在特定目录下Claude Code 启动时会扫描这个目录把所有 skill 的元信息name 和 description读进去。当你提问的时候系统会根据你的问题内容和 skill 的 description 做匹配匹配上了就把完整的 SKILL.md 内容注入到上下文里。这个机制有个关键点description 写得好不好直接决定了 skill 能不能被正确触发。我踩过这个坑。最开始我写了一个 skilldescription 只写了“代码相关”结果 Claude 几乎从来不调用它因为“代码相关”太模糊了跟用户的任何编程问题都能沾边反而匹配不上。后来改成“当用户要求审查代码质量、检查命名规范、或者提交代码片段请求 review 时使用”触发率立刻上来了。提示description 要写得具体包含明确的触发场景关键词但也不要太窄否则会漏掉合理的调用时机。我的经验是控制在 30 到 60 个字之间覆盖两到三个典型场景。3. 从零写一个能用的 skill完整实操流程3.1 先想清楚三件事再动手很多人一上来就开始写 SKILL.md写到一半发现逻辑混乱又回头改。我的建议是先在纸上或者备忘录里回答三个问题第一这个 skill 解决什么重复性问题如果你只是偶尔用一次那没必要写成 skill直接打提示词就行。只有当某个任务你每周至少要做两三次而且每次的要求都差不多才值得封装。第二输入是什么输出是什么输入可能是用户的一段代码、一篇文章、一个数学问题。输出可能是固定格式的报告、代码片段、表格。把输入输出的边界想清楚skill 的正文才不会跑偏。第三有哪些容易出错的点比如你让 AI 做数学建模它可能会忽略单位换算你让它写前端组件它可能不遵守你的命名规范。这些容易出错的点就是 skill 正文里需要特别强调的地方。3.2 目录结构和文件命名想清楚之后开始建文件夹。我推荐的结构是这样的skills/ code-review/ SKILL.md math-modeling/ SKILL.md frontend-component/ SKILL.md每个 skill 一个独立文件夹文件夹名用英文小写加连字符跟 SKILL.md 里的 name 保持一致。这样做的好处是当你 skill 多了之后一眼就能看出哪个文件夹对应哪个技能。我见过有人把所有 skill 都塞在一个文件夹里文件名还起得乱七八糟后期维护起来非常痛苦。SKILL.md 的头部元信息目前最常用的是两个字段name和description。name 就是技能名description 是触发描述。有些实现还支持version和author但这两个不是必须的。我个人的习惯是加上 version方便后续迭代的时候追踪改了哪些东西。3.3 正文写作的四个关键模块正文部分我一般分成四块来写这个结构是我试了七八个 skill 之后固定下来的效果最稳。第一块是角色设定。告诉 AI 在这个 skill 里它扮演什么角色。比如代码审查 skill 里我会写“你是一名有十年经验的资深工程师擅长发现代码中的潜在问题”。这个设定不是摆设它会影响 AI 的输出语气和关注重点。实测下来加了角色设定的 skill 比不加的输出专业度明显高一个档次。第二块是工作流程。把任务拆成有序的步骤一步一步写清楚。比如数学建模 skill 里我会写第一步理解问题背景第二步确定模型类型第三步给出求解思路第四步验证结果合理性。步骤不要太多五到七步比较合适太多了 AI 容易漏掉中间的步骤。第三块是输出格式。这块最重要也最容易被忽视。你必须明确告诉 AI 输出应该长什么样。是用表格还是列表要不要加标题字数控制在多少我一般会直接给一个输出模板让 AI 照着填。比如## 问题清单 | 严重程度 | 位置 | 问题描述 | 修改建议 | |---------|------|---------|---------| | 严重 | 第 23 行 | 未处理空指针 | 增加 null 检查 |第四块是边界和例外。告诉 AI 什么情况下不要用这个 skill或者遇到什么情况需要特殊处理。比如代码审查 skill 里我会写“如果代码片段少于 5 行不需要输出完整报告直接给出简短建议即可”。这块内容能有效防止 AI 在简单场景下过度输出。3.4 测试和迭代skill 写完不是就完了必须测试。我的测试方法分三步。第一步用三个典型场景去触发它看输出是否符合预期。第二步用两个边缘场景去测试看它会不会误触发或者输出异常。第三步故意在输入里埋一些坑比如格式混乱的代码、缺少关键信息的问题看 AI 能不能合理处理。测试过程中发现的问题直接回到 SKILL.md 里改。我一般会迭代三到五轮才能把一个 skill 调到比较稳定的状态。第一版往往输出太长第二版可能触发条件太窄第三版调整格式第四版补充例外情况。这个过程急不得但一旦调好后面用起来就非常省心。注意每次修改 SKILL.md 之后记得重启 Claude Code 或者重新加载 skill 目录否则改动不会生效。这个坑我踩过好几次改了文件发现没反应以为是写法有问题其实是没重新加载。4. 不同场景下的 skills 实战案例4.1 前端开发场景组件生成 skill前端开发是 skills 用得最多的场景之一。我给自己写了一个 React 组件生成 skill核心逻辑是这样的当我说“生成一个 XXX 组件”的时候AI 会按照我预设的规范来输出。规范包括使用函数式组件加 Hooks、样式用 CSS Modules、Props 必须有 TypeScript 类型定义、组件文件里必须包含单元测试的基本结构。这个 skill 帮我省了大量时间。以前每次让 AI 写组件都要重复交代这些规范而且它经常忘记加类型定义。现在只要说一句“生成一个用户卡片组件”出来的代码直接就能用命名规范、类型定义、测试骨架全都齐了。我统计过光是这一项每周至少省下两三个小时的重复沟通时间。写这类 skill 的关键在于把团队规范写死。你不要指望 AI 自己猜到你想要什么风格必须明确写出来。比如命名用 PascalCase 还是 kebab-case导出用 default 还是 named这些细节都要在 skill 里定好。4.2 数学建模场景建模流程 skill数学建模比赛的时间压力很大通常三天要完成从选题到论文的全过程。我帮参加华为杯的朋友写过一个建模 skill把整个流程拆成了几个固定阶段问题分析、模型选择、求解方法、灵敏度分析、论文结构。这个 skill 最大的价值在于防止遗漏关键步骤。人在紧张的时候容易跳过灵敏度分析或者模型验证直接写结论。skill 里明确要求每个阶段必须输出对应的内容AI 会按部就班地引导你走完整个流程。朋友反馈说用了这个 skill 之后论文的完整性明显提升评委最容易挑的“缺少模型验证”这类问题基本不会再出现了。写建模 skill 的难点在于模型选择部分不能写太死。数学建模的题目千变万化你不能规定死用哪种模型。我的做法是给出一个决策树如果问题是优化类优先考虑线性规划或遗传算法如果是预测类优先考虑时间序列或回归分析如果是评价类优先考虑层次分析法或熵权法。这样既有指导性又保留了灵活性。4.3 内容创作场景AI 漫剧脚本 skillAI 漫剧是最近很火的一个方向但很多人做出来的东西前后风格不一致角色说话的方式每一集都在变。我帮一个做漫剧的朋友写了一个脚本 skill核心是维护一个角色设定表和世界观规则每次生成新脚本的时候AI 会先读取这些设定确保新内容跟之前的保持一致。这个 skill 的结构比较特殊它包含了一个额外的characters.md文件里面记录了每个角色的性格、说话习惯、与其他角色的关系。SKILL.md 里写明了生成脚本时必须参考这个文件。实测下来角色一致性问题基本解决了观众也不会再吐槽“这个人怎么突然换了性格”。4.4 代码审查场景自动化 review skill代码审查 skill 是我用得最频繁的一个。它的触发条件写得很明确当用户提交代码片段并请求审查时使用。审查维度包括命名规范、错误处理、性能隐患、可读性、安全性五个方面。输出格式是分级问题清单每条问题都要求给出位置、原因和修改建议。这个 skill 有个细节我想特别说一下我在正文里加了一条规则“如果代码没有问题不要强行找问题直接说‘未发现明显问题’即可”。这是因为早期版本里AI 为了显得有用经常在一些完全没问题的代码里挑刺比如把“变量名可以更短”这种无关痛痒的建议也列出来反而干扰了真正的审查重点。加了这条规则之后输出质量明显提升。5. 安装、配置与常见问题排查5.1 Claude Code 的安装与 skill 目录配置Claude Code 的安装方式根据操作系统不同有所差异。Windows 用户需要注意某些版本可能需要启用虚拟机平台功能才能正常运行。安装完成之后skill 目录的默认位置通常在用户主目录下的.claude/skills文件夹。如果你用的是 VS Code 集成的 Claude Code配置方式略有不同需要在 VS Code 的设置里指定 skill 目录路径。我建议把 skill 目录放在一个固定的、容易找到的位置比如~/my-skills然后在 Claude Code 的配置里指向这个目录。这样做的好处是你可以在多个项目之间共享同一套 skill不用每个项目都复制一遍。配置好之后启动 Claude Code 时它会自动扫描目录下的所有 skill 文件夹。提示如果你在命令行输入claude提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没有配置好。检查一下安装路径是否加入了 PATH或者直接用完整路径来启动。5.2 skill 不触发怎么办这是最常见的问题。你写了一个 skill但 Claude 好像完全不知道它的存在。排查思路按顺序来第一检查文件位置对不对。SKILL.md 必须在 skill 文件夹的根目录下不能多套一层。我见过有人写成skills/code-review/skill/SKILL.md多了一层文件夹导致扫描不到。第二检查头部元信息格式。---包裹的元信息块必须放在文件最开头前面不能有空行或者注释。name 和 description 的冒号后面要有空格。第三检查 description 是否太模糊。前面说过“代码相关”这种描述基本触发不了。改成具体的场景描述比如“当用户要求审查代码、检查代码质量时使用”。第四检查是否重新加载了。修改 SKILL.md 之后必须重启 Claude Code 或者执行重新加载命令否则改动不生效。5.3 skill 输出格式不稳定怎么办有时候 skill 能触发但输出格式每次都不一样。这个问题通常出在正文的格式要求写得不够具体。我的经验是不要用文字描述格式直接给模板。比如你要表格就直接在 SKILL.md 里写一个 Markdown 表格的示例让 AI 照着填。你要分三级标题就直接写出### 一级、### 二级的示例。另一个技巧是在正文末尾加一句“严格按照上述格式输出不要添加额外的解释性文字”。这句话能有效减少 AI 的自由发挥。我试过加了这句话之后格式一致性从大概七成提升到了九成以上。5.4 多个 skill 冲突怎么处理当你装了很多 skill 之后可能会出现两个 skill 同时被触发的情况。比如你有一个“代码审查”skill 和一个“代码优化”skill用户提交代码请求改进的时候两个都可能被匹配上。这时候 Claude 可能会把两个 skill 的指令混在一起执行输出变得混乱。解决办法有两个。一是在 description 里明确区分触发场景让两个 skill 的适用范围不重叠。二是在 skill 正文里加优先级说明比如“如果同时匹配到代码优化 skill优先执行本 skill 的审查流程审查完成后再考虑优化建议”。我一般用第一种方法从源头避免冲突。5.5 常见问题速查表问题现象可能原因解决方法skill 完全不触发文件位置错误或元信息格式不对检查 SKILL.md 是否在文件夹根目录元信息是否以---开头skill 偶尔触发description 太模糊或太窄调整 description覆盖两到三个典型场景关键词输出格式每次不同格式要求写得太抽象直接在 SKILL.md 里给输出模板修改后不生效没有重新加载重启 Claude Code 或执行重新加载命令多个 skill 冲突触发场景重叠调整 description 区分场景或在正文里加优先级规则输出太长或太短没有字数约束在正文里明确要求字数范围6. 进阶技巧让 skill 真正融入日常工作流6.1 组合使用多个 skill单个 skill 的能力有限但多个 skill 组合起来就能覆盖完整的工作流。我现在的做法是把日常开发流程拆成几个阶段每个阶段对应一个 skill。比如“需求分析”阶段用需求拆解 skill“编码”阶段用组件生成 skill“审查”阶段用代码审查 skill“文档”阶段用文档生成 skill。每个 skill 各司其职串起来就是一条完整的流水线。组合使用的关键是要定义好 skill 之间的输入输出衔接。比如代码审查 skill 的输出格式要能被文档生成 skill 直接读取。我一般会在审查 skill 的输出里保留一个结构化的摘要部分文档 skill 读取这个摘要就能生成变更日志。6.2 版本管理与团队共享skill 写多了之后版本管理就变得重要了。我的做法是把整个 skills 目录纳入 Git 管理每次修改都提交一次commit message 写清楚改了什么、为什么改。这样万一改坏了可以随时回滚到之前的版本。团队共享的话直接把 Git 仓库分享给同事就行。每个人拉下来之后在自己的 Claude Code 配置里指向这个目录。如果团队有特殊的规范可以在仓库里放一个 README说明每个 skill 的用途和使用方法。我见过一些团队把 skill 仓库当成团队知识库来维护新成员入职直接拉下来就能用省去了大量培训成本。6.3 持续迭代的思路skill 不是写完就固定不变的。随着你使用场景的变化skill 也需要不断调整。我一般每个月会回顾一次自己常用的 skill看看哪些地方经常需要手动纠正 AI 的输出这些纠正点就是 skill 需要补充的规则。另一个迭代思路是收集失败案例。每次 skill 输出不符合预期的时候把输入和输出都记下来分析是哪个环节出了问题。是触发条件不对还是正文里的规则不够明确还是输出格式没有约束好找到原因之后针对性修改比盲目调整有效得多。提示我习惯在 SKILL.md 的末尾加一个“更新日志”区域记录每次修改的内容和原因。这样过几个月回头看能清楚知道这个 skill 是怎么一步步演化的也方便判断某条规则是不是已经过时了。6.4 关于 skill 库的选择建议现在网上已经有不少公开的 skill 库可以下载但我的建议是不要盲目全装。skill 装太多会导致触发混乱而且很多公开 skill 的质量参差不齐。我的做法是先看 description 判断是否跟自己的工作场景匹配匹配的下载下来之后先在小范围测试确认输出质量稳定之后再正式纳入日常使用。另外公开 skill 下载下来之后最好根据自己的习惯做一轮定制。别人的规范不一定适合你比如命名风格、输出格式这些改成自己顺手的样式用起来才顺手。我一般会把下载的 skill 当作参考模板取其结构换其内容最终形成一套完全贴合自己工作流的技能库。6.5 一个容易被忽视的细节skill 的命名最后说一个很多人不注意的点skill 的命名。name 字段虽然不直接参与触发匹配但它会影响你在使用时的调用体验。我建议 name 用英文小写加连字符简短且能表意。比如code-review、math-modeling、frontend-component。不要用中文也不要用太长的名字否则在命令行里输入的时候很麻烦。description 则相反要写得详细具体。这两者的分工是name 给人看description 给系统看。把这两个字段各司其职skill 的可用性会提升很多。我在实际使用中最大的体会是skills 这套机制的价值不在于技术有多复杂而在于它强迫你把重复性的工作结构化地沉淀下来。写第一个 skill 的时候可能觉得麻烦但写到第五个、第十个的时候你会发现自己的工作效率有了质的提升。那些以前需要反复交代的事情现在一句话就能搞定省下来的时间和精力可以放在真正需要创造力的地方。
