1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新出的编程语言或者框架其实不是。这里的skills指的是围绕 Claude 生态尤其是 Claude Code、Claude Desktop 这类工具构建的一套可复用的能力模块。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一份 skill 本质上是一个结构化的说明文件通常以SKILL.md为核心告诉 Claude 在特定场景下该怎么思考、该调用什么工具、该遵循什么流程。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让它在处理前端项目时自动遵循一套代码规范结果发现光靠 prompt 每次都要重复写一大堆约束效率极低。后来看到有人分享SKILL.md的写法才意识到这就是把“重复的指令”沉淀成“可复用的技能”的思路。打个比方prompt 像是你每次做饭都要口头交代一遍“先放油、再放盐、火候中档”而 skill 相当于把这些步骤写成一张菜谱贴在墙上下次直接说“按菜谱来”就行。这套东西解决的核心问题是一致性和复用性。对于经常用 Claude 做开发、写文档、做数据分析的人来说skills 能让你把一套成熟的工作流固化下来不用每次从零开始调教。它适合的人群其实比想象中广前端开发者可以用它统一组件写法数学建模的人可以用它规范论文格式和求解流程做内容的人可以用它固定选题和写作框架。哪怕你只是刚入门 Claude Code 的新手学会写一个简单的 skill也能明显感觉到输出质量的提升。目前社区里流传的 skills 大致分几类官方或半官方维护的通用技能库、个人开发者分享的垂直场景技能比如专门针对 STM32 开发的、专门做数学建模的、以及各种“超级技能包”superpower skills 这类整合型项目。热词里提到的superpower skills、typesafe ai skills、codex nature skills都属于这个范畴。下面我会从设计思路、文件结构、实操写法、安装配置到常见坑完整拆一遍。2. 拆解一个 skill 的骨架SKILL.md 里到底该写什么2.1 核心文件结构为什么是 SKILL.md 而不是别的一个标准的 skill 目录通常长这样my-skill/ ├── SKILL.md # 核心说明文件必须有 ├── scripts/ # 可选放辅助脚本 ├── templates/ # 可选放模板文件 └── resources/ # 可选放参考资料SKILL.md是整个 skill 的入口和灵魂。Claude 在加载一个 skill 时首先读的就是这个文件。它的格式一般是 Markdown 加 YAML frontmatterfrontmatter 里声明技能的元信息正文部分描述具体的行为规范。为什么用 Markdown 而不是 JSON 或 YAML 纯配置因为 skill 的核心是“给模型看的自然语言指令”Markdown 的可读性和结构化程度刚好平衡——既能让模型理解层级关系又方便人类维护。我见过不少人把 SKILL.md 写成一大段散文结果模型执行时抓不住重点。正确的做法是用清晰的标题分层把“什么时候触发”“触发后做什么”“输出格式是什么”“有哪些禁忌”分开写。这跟写 prompt 的逻辑一样但比 prompt 更正式、更持久。2.2 frontmatter 里的关键字段一个典型的 frontmatter 大概是这样--- name: frontend-component-generator description: 当用户需要生成 React 组件时使用此技能遵循团队代码规范 version: 1.0.0 author: your-name tags: [frontend, react, component] ---这里每个字段都有实际作用。name是技能的唯一标识安装后 Claude 用它来索引description最关键它决定了模型在什么情况下会自动调用这个技能——写得越具体触发越精准。我踩过的坑是 description 写得太泛比如只写“帮助写代码”结果模型在任何编程场景都想调用它反而干扰了正常对话。后来改成“当用户明确要求生成 React 函数式组件且需要遵循 Airbnb 规范时使用”触发就准确多了。version和author在个人使用时可以随意但如果你打算分享或团队协作这两个字段能帮你管理迭代。tags主要用于分类检索社区技能库通常靠它做筛选。2.3 正文部分的写法把“隐性经验”变成“显性规则”正文是真正干活的地方。我的经验是把它分成四个区块来写每个区块解决一个问题。第一个区块是触发条件。明确写出“当满足以下条件时执行本技能”比如“用户提到‘生成组件’‘写一个 React 组件’等关键词且项目目录下存在 package.json”。这一步是为了避免误触发。第二个区块是执行步骤。用有序列表把流程拆开每一步都要具体到可操作。比如“第一步读取项目根目录的 .eslintrc 文件确认规范第二步根据用户描述确定组件名和 props第三步按模板生成代码”。这里不要写“生成高质量代码”这种空话模型需要的是明确动作。第三个区块是输出格式。规定好返回内容的结构比如“先输出组件代码块再输出 props 说明表格最后附上使用示例”。格式约束能大幅提升输出的稳定性。第四个区块是禁忌与边界。写明“不要做什么”比如“不要引入未在 package.json 中声明的依赖”“不要修改用户未指定的文件”。这一块很多人会忽略但实际用下来边界声明能减少大量意外行为。提示SKILL.md 的正文不要超过 500 行。太长的技能文件会稀释模型的注意力重点反而抓不住。如果逻辑确实复杂拆成多个 skill 组合使用比堆在一个文件里效果好。3. 手把手写第一个 skill从前端组件生成器开始3.1 场景选择与需求拆解拿一个最实用的场景练手前端 React 组件生成器。选它是因为前端开发里组件模板重复度高而且规范细节多命名、props 类型、样式方案、导出方式正好适合用 skill 固化。需求拆解下来有这么几条用户描述组件功能后自动生成符合团队规范的函数式组件props 必须有 TypeScript 类型样式默认用 CSS Modules组件文件命名用 PascalCase同时生成一个基础的测试文件。这些规则如果每次靠 prompt 交代至少得写五六行而且容易漏。写成 skill 后一句“帮我生成一个用户卡片组件”就能触发完整流程。3.2 完整 SKILL.md 示例与逐段解析下面是我实际在用的一个版本做了简化处理--- name: react-component-generator description: 当用户要求生成 React 函数式组件且当前项目包含 TypeScript 配置时使用 version: 1.2.0 tags: [frontend, react, typescript] --- # React 组件生成器 ## 触发条件 - 用户明确提到“生成组件”“写一个组件”“create component” - 当前工作目录存在 tsconfig.json - 用户未指定使用 class 组件 ## 执行步骤 1. 读取项目根目录的 tsconfig.json确认 strict 模式是否开启 2. 从用户描述中提取组件名称转换为 PascalCase 3. 生成组件文件包含以下内容 - 函数式组件声明使用箭头函数 - Props 接口定义字段类型明确 - CSS Modules 导入语句 - 默认导出 4. 生成对应的 .module.css 文件包含基础样式占位 5. 生成 .test.tsx 测试文件包含一个渲染测试 ## 输出格式 先输出文件树再依次输出每个文件的完整代码每个代码块标注文件路径。 ## 禁忌 - 不要使用 any 类型 - 不要引入未声明的第三方库 - 不要修改用户已有的其他文件逐段看触发条件里加了“存在 tsconfig.json”这个约束是为了避免在纯 JavaScript 项目里误触发。执行步骤第 1 步读取配置是为了让生成结果适配项目实际设置而不是套死模板。输出格式要求先给文件树是因为多文件输出时读者需要先看到整体结构才知道每个文件的位置。禁忌部分的三条每一条都对应我之前踩过的坑——比如不加约束时模型有时会自作主张引入 lodash 或 styled-components导致项目依赖混乱。3.3 参数计算与命名转换的细节组件命名转换看起来简单实际有讲究。用户可能说“用户卡片”“user card”“UserCard”都要统一转成 PascalCase。规则是按空格或连字符拆分每个词首字母大写其余小写然后拼接。比如“user-profile-card”变成UserProfileCard。这个逻辑如果写在 skill 里模型执行时会自动处理如果不写它可能生成userprofilecard这种没法看的结果。Props 类型定义也有细节。我要求模型根据用户描述推断字段比如“用户卡片需要显示头像、昵称、简介”就生成interface UserCardProps { avatarUrl: string; nickname: string; bio?: string; }注意bio加了问号因为简介可能是可选的。这种推断规则我会在 skill 里补一句“无法确定是否必填的字段默认设为可选”。这就是把隐性经验显性化的价值。4. 安装与配置把 skill 真正跑起来4.1 Claude Code 环境准备与常见报错先说环境。Claude Code 目前主要通过命令行工具使用安装方式根据系统不同有差异。Windows 用户经常会遇到一个报错claudes workspace requires the virtual machine platform on windows。这个提示的意思是系统缺少虚拟机平台组件需要在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启。重启后如果还报claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称说明环境变量没配好需要把安装目录加到 PATH 里。macOS 和 Linux 相对省事用包管理器装完基本就能用。装好后在终端输入claude能进入交互界面就算环境通了。VS Code 用户如果想在编辑器里直接用可以装对应的扩展然后在设置里配置 Claude Code 的路径。这一步热词里提到的vscode配置claude code、vscode安装claude code说的就是这个流程。注意安装过程中如果提示当前地区不支持属于正常的服务范围限制换个网络环境或稍后再试即可不要在这上面纠结太久。4.2 手动安装 GitHub 上的 skill社区里的 skill 大多托管在 GitHub 上安装方式分两种。第一种是手动放置把整个 skill 目录克隆或下载下来放到 Claude Code 的技能目录里。这个目录通常在用户主目录下的.claude/skills/具体路径因版本而异可以在 Claude Code 里输入/skills查看当前加载路径。放进去后重启 Claude Code输入/skills就能看到新技能出现在列表里。第二种是通过技能库网址安装。有些社区维护了技能索引站提供一键安装命令。热词里提到的skills技能库网址、skills网页版进入指的就是这类入口。不过我的建议是不管哪种方式装完先打开 SKILL.md 读一遍确认它做的事情符合你的预期再启用。我见过有人装了个来路不明的 skill结果它会在每次对话时读取项目里的敏感配置文件这种风险必须自己把关。4.3 验证 skill 是否生效装完后怎么确认它真的在工作最直接的办法是构造一个触发场景。比如装了组件生成器 skill就在一个 TypeScript 项目里输入“帮我生成一个按钮组件”观察输出是否符合 skill 里定义的格式——有没有生成测试文件、有没有用 CSS Modules、props 类型是否完整。如果输出跟没装之前一样说明触发条件没匹配上需要回头检查 description 和触发条件部分。另一个验证方法是看 Claude Code 的日志。部分版本会在调用 skill 时打印一行提示比如Using skill: react-component-generator。看到这行就说明技能被正确加载和调用了。5. 进阶玩法组合技能与垂直场景实战5.1 数学建模场景的 skill 设计热词里数学建模skills推荐、华为杯建模比赛好用的codex skills出现频率很高说明这个场景需求真实。数学建模的痛点在于论文格式要求严、求解流程长、代码和文档要同步。我帮朋友设计过一套建模 skill拆成三个独立技能论文格式检查器、求解流程引导器、图表生成器。论文格式检查器的 SKILL.md 里写死了竞赛要求的字体、行距、参考文献格式模型每次生成内容后自动对照检查。求解流程引导器则把“读题、选模型、写代码、验证、写论文”这个流程固化下来每一步都要求输出中间结果。图表生成器负责把数据转成符合规范的图表连坐标轴标签的字体大小都规定好。三个技能组合使用比一个大而全的技能稳定得多。5.2 用 skill 规范 AI 漫剧脚本创作ai漫剧常用skills这个热词背后是一类内容创作需求。漫剧脚本有固定结构场景描述、角色对白、镜头提示、音效标注。我写过一个脚本生成 skill核心是把这些结构做成模板模型填充内容时不会漏项。关键设计在于角色一致性——skill 里要求模型维护一个角色表每次生成新场景前先读取已有角色设定避免出现“第一集叫小明第三集变成小华”这种问题。这个思路其实可以迁移到任何长内容创作场景。skill 的价值不只是单次生成更在于跨会话的一致性维护。把角色表、世界观设定、已用过的桥段都写进 skill 的 resources 目录模型每次调用时都能读到相当于给 AI 装了个长期记忆。5.3 技能组合的调用顺序设计多个 skill 同时存在时调用顺序会影响结果。我的经验是约束类技能优先生成类技能其次检查类技能最后。比如同时装了代码规范 skill 和组件生成 skill应该让规范先加载生成时才能遵循生成完再调用检查 skill 做一遍校验。这个顺序可以通过在 description 里写明依赖关系来引导比如“本技能应在代码生成技能之前使用”。如果发现技能之间互相干扰比如两个 skill 都想处理同一个触发词解决办法是收窄各自的触发条件。宁可触发条件写得窄一点也不要让多个技能抢同一个场景。6. 常见问题与排查技巧实录6.1 技能不触发怎么办这是最高频的问题。排查顺序是这样的先确认 skill 目录位置对不对用/skills命令看列表里有没有再看 description 是否足够具体把触发词写得太抽象是常见原因然后检查触发条件里有没有互相矛盾的约束比如同时要求“项目有 tsconfig.json”又要求“项目是纯 JavaScript”。最后看文件编码SKILL.md 必须是 UTF-8用 GBK 保存会导致 frontmatter 解析失败。6.2 技能触发后行为不符合预期如果技能被调用了但输出不对问题多半出在正文的步骤描述上。模型执行时会严格按你写的步骤来如果步骤有歧义结果就会飘。解决办法是把每一步都写成“动词对象标准”的格式比如“读取 tsconfig.json 并确认 strict 字段的值”而不是“检查配置”。另外输出格式部分要给出具体示例模型对示例的遵循度远高于对抽象描述的理解。6.3 常见问题速查表问题现象可能原因解决方向技能列表里看不到目录放错或未重启确认路径重启 Claude Code触发词命中但不执行description 太泛或冲突收窄触发条件增加具体约束输出格式混乱正文缺少格式示例在输出格式区加完整示例多技能互相干扰触发条件重叠拆分场景明确调用顺序frontmatter 解析失败编码或缩进错误用 UTF-8YAML 缩进用空格技能执行到一半中断步骤过长或依赖缺失拆分成多个小技能6.4 几个我踩过的坑第一个坑是在 skill 里写死绝对路径。早期我图省事在 SKILL.md 里写了/Users/myname/project/...结果换台机器就废了。正确做法是用相对路径或环境变量让技能具备可移植性。第二个坑是技能文件里塞了太多示例代码。有次我为了让模型理解输出格式贴了三百行示例结果模型直接照抄示例内容完全不看用户的实际需求。后来改成只给结构骨架具体内容让模型根据输入生成问题就解决了。第三个坑是忽略版本管理。skill 改来改去最后忘了哪版好用。现在我会在 frontmatter 里认真写 version每次改动都留记录出问题能快速回滚。提示调试 skill 时可以临时把 description 改得极其具体比如加上“仅当用户输入包含‘测试技能触发’时使用”这样能快速验证加载链路是否通畅验证完再改回正常描述。7. 技能库的维护与迭代思路7.1 个人技能库的组织方式技能多了以后管理就成了问题。我的做法是按领域分目录frontend/、writing/、data/、misc/每个目录下放对应的 skill。这样找起来快也方便整体备份。另外我会维护一个README.md放在技能库根目录记录每个技能的用途、触发词、最近修改时间。这个习惯是从管理代码仓库迁移过来的对技能库同样适用。定期清理也很重要。热词里提到tibo关于清理skills的方法推荐核心思路就是用不到的技能及时移除。技能不是越多越好每个加载的技能都会占用模型的注意力预算。我一般每个月过一遍把三个月没用过的技能归档需要时再装回来。7.2 从个人使用到团队共享如果想把技能分享给团队有几个额外工作要做。第一是把硬编码的个人偏好抽出来做成可配置项比如代码缩进用 2 空格还是 4 空格不要写死。第二是补充文档说明技能的适用场景和依赖条件。第三是建立更新机制技能改了怎么通知使用者。我们团队的做法是把技能库放在内部 Git 仓库里用 tag 标记版本更新时发个简短说明大家按需拉取。7.3 技能迭代的触发信号什么时候该更新一个技能我的判断标准有三个一是发现模型在某个场景反复出错说明 skill 里的规则不够明确二是工作流程本身变了比如团队换了新的代码规范三是看到社区里有更好的写法可以借鉴。迭代时不要大改一次改一个点改完立刻测试确认有效再继续。这样出问题容易定位。8. 关于 skills 学习路径的一点个人建议如果你刚开始接触 skills我的建议是先抄再改。去社区找几个现成的技能装上去用观察它们怎么组织 SKILL.md、怎么写触发条件、怎么约束输出。用顺手了再试着改一改比如把触发词换成你自己的习惯用语把输出格式调成你喜欢的样式。改的过程中自然就理解了每个部分的作用。然后找一个你每天都要重复做的任务把它写成 skill。不用追求完美先跑通再说。我写的第一个 skill 只有二十行功能就是让模型每次生成代码时自动加上文件头注释。虽然简单但那次成功让我摸清了整个链路后面写复杂技能就有底了。最后别把 skills 当成万能药。它解决的是“重复性指令固化”的问题对于一次性的、高度依赖上下文的任务直接写 prompt 反而更灵活。工具的价值在于用对地方而不是用得最多。