1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在技术社区、AI 工具群或者前端圈子里频繁看到“skills”这个词不用怀疑它确实正在成为 Claude 生态里一个非常关键的拼图。简单来说skills 是一套让 Claude 具备特定领域能力的模块化技能包每个 skill 本质上是一个包含SKILL.md文件的目录里面写清楚了“这个技能是干什么的、什么时候触发、具体怎么执行”。你可以把它理解成给 Claude 装的“插件”或者“外挂大脑”——不装的时候它是个通才装上之后它就能在你的项目里干专业活。我第一次接触这个概念是在折腾 Claude Code 的时候。当时想让 Claude 帮我处理一些前端项目的重复性工作比如自动生成组件模板、检查 TypeScript 类型、按团队规范格式化代码。每次都要把同样的提示词复制一遍效率很低。后来发现 skills 机制之后我把这些重复指令封装成一个 skillClaude 就能在合适的场景自动调用不用我反复交代。这个体验上的提升是非常明显的。skills 解决的核心问题是把“一次性提示词”变成“可复用、可分发、可版本管理的能力单元”。它适合几类人一是日常用 Claude Code 写代码的开发者想减少重复沟通成本二是团队里想统一 AI 辅助规范的技术负责人三是做数学建模、内容创作、数据分析等垂直场景需要 Claude 按固定流程输出的人。哪怕你只是刚装好 Claude Code 的新手理解 skills 也能让你少走很多弯路。目前社区里讨论最多的几个方向包括前端开发 skills、数学建模 skills、superpower skills、AI 漫剧常用 skills以及SKILL.md的写法规范。下面我会从设计思路、核心细节、实操流程、常见问题几个维度把 skills 这件事讲透。2. skills 的整体设计与核心思路拆解2.1 为什么是“文件目录 Markdown”而不是插件系统Claude 的 skills 没有采用传统 IDE 插件那种二进制打包、注册表安装的方式而是选择了纯文件目录 Markdown 描述的极简结构。这个选择背后有很实际的考量。传统插件系统的问题在于安装门槛高、跨平台兼容麻烦、调试困难。你想改一个插件的行为得看源码、重新编译、再加载。而 skills 用 Markdown 写意味着任何人用文本编辑器就能创建和修改不需要编译工具链不需要特定 IDE甚至可以直接扔进 Git 仓库做版本管理。这对团队协作来说太重要了——skill 的变更可以走 code review可以追溯历史可以回滚。另一个原因是Claude 本身就是一个语言模型它最擅长的就是理解自然语言描述。用 Markdown 写 skill 说明Claude 读起来毫无障碍。你不需要用某种 DSL 或者配置文件格式去“编程”一个 skill你只需要用清晰的自然语言告诉它什么情况下用这个技能、步骤是什么、注意什么。这大幅降低了创作门槛。提示不要因为结构简单就轻视它。skill 的质量高低几乎完全取决于SKILL.md里描述是否精准、边界是否清晰、示例是否到位。2.2 skill 的触发机制Claude 怎么知道该用哪个技能这是很多人第一次接触 skills 时最困惑的地方。Claude 不是简单地“看到关键词就触发”而是根据当前对话上下文、项目文件结构、以及 skill 描述里的触发条件综合判断。一个设计良好的 skill它的SKILL.md开头通常会有一段类似“当用户要求 X 或者当前项目包含 Y 文件时使用本技能”的描述。Claude 在收到请求后会扫描可用 skills 列表匹配最合适的那个。如果匹配到多个它会根据描述的 specificity 做优先级判断。这里有个关键点skill 的命名和描述要足够具体避免歧义。比如你写一个叫code-helper的 skill描述是“帮助写代码”那 Claude 几乎在任何编程场景都可能触发它反而干扰正常对话。更好的做法是叫react-component-generator描述里明确“当用户要求生成 React 函数组件且项目使用 TypeScript 时触发”。2.3 与 Claude Code、Codex 等工具的关系skills 并不是孤立存在的。在 Claude Code 里skills 通常放在项目根目录的.claude/skills/或者用户全局配置目录下。Claude Code 启动时会加载这些 skill并在后续对话中按需调用。社区里也有人把 skills 用在 opencode、Codex 等支持类似机制的工具里思路是相通的。热词里出现的“claude code 接入 deepseek”“codex nature skills”“opencode skills”本质上都是在讨论如何把同一套 skill 描述适配到不同 AI 编程工具。因为SKILL.md是纯文本迁移成本很低你只需要确认目标工具是否支持类似的技能加载机制以及触发逻辑是否有差异。2.4 设计一个 skill 前必须想清楚的三个问题我在实际写 skill 的过程中总结出一个经验动手写之前先回答三个问题。第一这个 skill 的输入边界是什么是用户的一句话请求还是某个特定文件的存在还是某个命令的执行结果边界越清晰触发越准确。第二这个 skill 的输出形态是什么是生成一段代码、修改现有文件、输出一份报告还是执行一系列终端命令输出形态决定了你在SKILL.md里要写多详细的步骤。第三这个 skill 的失败处理是什么如果条件不满足、依赖缺失、或者执行出错Claude 应该怎么反馈很多新手写的 skill 只写了“成功路径”一旦遇到异常就胡言乱语。把失败处理写进去skill 的健壮性会提升一个档次。3. 核心细节解析与实操要点SKILL.md 到底怎么写3.1 SKILL.md 的基本结构一个标准的SKILL.md通常包含以下几个部分顺序可以根据需要调整但建议保持一致性方便 Claude 解析。--- name: skill-name description: 一句话说明这个技能做什么以及什么时候触发 --- # Skill 名称 ## 触发条件 - 当用户明确要求... - 当项目目录中存在... ## 执行步骤 1. 第一步... 2. 第二步... ## 注意事项 - 不要... - 必须... ## 示例 输入... 输出...最上面的 frontmatter---包裹的部分非常关键。name是 skill 的唯一标识description是 Claude 做匹配时主要参考的内容。description 要写得像“触发条件”而不是“功能简介”。比如“生成 React 组件”就不如“当用户要求创建新的 React 函数组件且项目使用 TypeScript 和 Tailwind CSS 时使用本技能生成符合项目规范的组件文件”来得有效。3.2 触发条件怎么写才精准触发条件是 skill 的“门禁”。写得太宽Claude 会频繁误触发写得太窄该用的时候用不上。我的经验是采用**“正向条件 反向排除”**的写法。正向条件列出所有应该触发的情况比如“用户提到‘生成组件’‘创建页面’‘新建模块’等关键词”。反向排除则明确不该触发的情况比如“如果用户只是询问组件概念、或者要求修改现有组件的样式不要使用本技能”。这种写法看起来啰嗦但实测下来触发准确率会高很多。Claude 对否定句的理解能力不错明确告诉它“不要做什么”和告诉它“要做什么”同样重要。3.3 执行步骤的颗粒度控制执行步骤写多细这是新手最容易纠结的地方。写太粗Claude 自由发挥结果不可控写太细skill 变得冗长维护成本高。我的建议是关键决策点写细机械性操作写粗。比如“读取项目根目录的package.json判断是否使用 TypeScript”这种需要判断的逻辑要写清楚判断依据和分支走向。而“在src/components/下创建新文件”这种确定性操作一句话带过即可。另外步骤之间如果有依赖关系一定要标明顺序。Claude 虽然能理解上下文但明确的“第一步完成后才执行第二步”能减少很多意外。3.4 注意事项与边界约束这是区分“能用”和“好用”的关键部分。注意事项里应该包含操作禁忌比如“不要直接修改用户已有文件先创建备份或输出 diff 供确认”依赖检查比如“执行前确认项目已安装prettier如果没有则提示用户安装”风格约束比如“生成的代码必须符合项目现有的 ESLint 规则”安全边界比如“不要执行任何删除文件或修改系统配置的命令”注意注意事项不是越多越好。堆砌太多无关约束会让 Claude 在触发时犹豫反而降低效率。只写真正影响执行结果的关键点。3.5 示例部分的价值被严重低估很多人写SKILL.md时会跳过示例部分觉得“步骤写清楚了就行”。但实际使用中示例是 Claude 理解你意图的最快路径。一个好的输入输出示例抵得上三段抽象描述。示例要覆盖两种情况典型成功场景和边界场景。典型场景展示正常流程边界场景展示当条件不完全满足时 skill 应该如何应对。比如一个“生成 API 接口文档”的 skill典型示例是“用户提供 controller 文件路径输出 Markdown 文档”边界示例是“用户只提供了部分接口信息skill 应该提示补充而不是强行生成”。4. 实操过程与核心环节实现从零搭建一个可用 skill4.1 环境准备与目录结构假设你已经在使用 Claude Code无论是桌面版还是 CLI 版本skills 的加载目录通常有两个位置项目级项目根目录/.claude/skills/用户级~/.claude/skills/Windows 下是C:\Users\用户名\.claude\skills\项目级 skill 只对当前项目生效适合团队共享用户级 skill 对所有项目生效适合个人通用能力。我一般把通用性强的放用户级把和具体项目规范强相关的放项目级。创建 skill 的步骤很简单# 进入 skills 目录 cd .claude/skills # 创建 skill 目录目录名就是 skill 名 mkdir my-first-skill # 创建 SKILL.md touch my-first-skill/SKILL.md然后编辑SKILL.md即可。不需要安装任何依赖不需要重启 IDEClaude Code 通常会自动检测新 skill。4.2 一个完整示例前端组件生成 skill下面是我实际在用的一个前端组件生成 skill简化后分享出来。假设项目使用 React TypeScript Tailwind CSS。--- name: react-component-gen description: 当用户要求创建新的 React 函数组件且项目使用 TypeScript 和 Tailwind CSS 时触发。不适用于修改现有组件或生成类组件。 --- # React 组件生成器 ## 触发条件 - 用户说“创建一个组件”“新建页面”“生成模块” - 项目根目录存在 tsconfig.json 和 tailwind.config.js ## 执行步骤 1. 读取 src/components/ 目录结构了解现有组件的命名和文件组织方式 2. 根据用户描述确定组件名使用 PascalCase 命名 3. 创建组件文件 src/components/ComponentName/index.tsx 4. 组件使用函数式写法导出为默认导出 5. 样式使用 Tailwind 类名不写独立 CSS 文件 6. 如果组件需要 props定义 TypeScript interface命名为 ComponentNameProps ## 注意事项 - 不要覆盖已存在的组件文件如果同名文件存在提示用户并建议新名称 - 不要引入项目 package.json 中未声明的依赖 - 生成的组件必须包含基本的无障碍属性如 alt、aria-label ## 示例 输入创建一个用户头像组件接收 name 和 avatarUrl 两个 props 输出生成 src/components/UserAvatar/index.tsx包含 UserAvatarProps 接口和默认导出函数组件这个 skill 写完后我在 Claude Code 里只需要说“创建一个用户头像组件接收 name 和 avatarUrl”它就会自动按项目规范生成文件不需要我每次交代技术栈和目录结构。4.3 参数计算与条件判断的写法有些 skill 需要根据项目情况做条件判断。比如一个“生成 API 请求函数”的 skill需要判断项目用的是 axios 还是 fetch。这种逻辑在SKILL.md里可以这样写## 执行步骤 1. 读取 package.json 的 dependencies 2. 如果存在 axios使用 axios 生成请求函数 3. 如果不存在 axios 但项目使用 fetch使用原生 fetch 生成 4. 如果两者都无法确定询问用户偏好这种写法把判断逻辑显式化Claude 执行时会按分支走结果更可控。不要指望 Claude 自己“猜”项目用什么库明确写出判断依据效率高很多。4.4 多 skill 协作与优先级当项目里有多个 skill 时Claude 需要决定用哪个。我的经验是命名要有区分度不要出现code-helper和code-assistant这种容易混淆的名字description 里写明适用场景的差异比如一个 skill 专门处理“新建”另一个专门处理“重构”避免功能重叠如果两个 skill 都能处理同一类请求Claude 会犹豫触发不稳定如果确实需要多个 skill 协作可以在一个 skill 的步骤里明确写“调用另一个 skill 完成某步骤”。但这种情况比较少见大多数时候一个 skill 应该是一个独立完整的能力单元。4.5 测试与迭代skill 写完不是终点测试和迭代才是。我的做法是第一轮用典型请求测试看是否触发、输出是否符合预期。第二轮用边界请求测试比如信息不完整、项目结构不符合假设看 skill 是否优雅处理。第三轮用无关请求测试看是否误触发。每次发现问题不要急着改步骤先看description和触发条件是否准确。大部分触发问题都出在 description 写得太模糊而不是步骤本身有问题。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。排查顺序如下排查项检查方法常见原因目录位置确认 skill 在.claude/skills/下放错目录Claude 扫描不到文件命名确认文件名是SKILL.md大小写错误或用了.md以外的扩展名frontmatter确认---包裹的元数据格式正确缺少name或descriptiondescription检查是否写得太泛或太窄太泛导致优先级低太窄导致匹配不上重启尝试重启 Claude Code部分版本不会热加载新 skill我踩过最坑的一次是SKILL.md的 frontmatter 里用了中文冒号Claude 解析失败但没有任何报错skill 就是静默不触发。后来改成英文冒号就好了。格式问题往往没有明显提示需要自己仔细检查。5.2 skill 触发了但执行结果不对如果 skill 被正确触发但输出不符合预期问题通常出在步骤描述上。常见情况步骤顺序不明确Claude 按自己的理解调整了顺序导致依赖关系错乱条件判断缺失没有写清楚“如果 A 则 X如果 B 则 Y”Claude 随机选了一个输出格式没约束Claude 自由发挥生成了你不想要的格式解决办法是在SKILL.md里增加明确的输出模板。比如要求生成 JSON 就贴一个 JSON 示例要求生成 Markdown 表格就贴一个表格示例。Claude 对示例的遵循度远高于对抽象描述的理解。5.3 多个 skill 冲突或重复触发当项目里 skill 多了之后可能会出现一个请求触发多个 skill 的情况。这时候 Claude 可能会把多个 skill 的步骤混在一起执行结果一团糟。我的处理方式是定期清理和合并 skill。热词里提到的“tibo 关于清理 skills 的方法推荐”核心思路就是定期审查 skill 列表把功能重叠的合并把不再使用的删除。具体做法是每月检查一次.claude/skills/目录对每个 skill 问过去一个月用过吗触发准确吗输出还需要手动修改吗如果某个 skill 连续一个月没被触发考虑删除或合并如果两个 skill 的触发条件有重叠合并成一个用条件分支处理5.4 Windows 环境下的特殊问题热词里有一条“claudes workspace requires the virtual machine platform on windows. enable”这涉及到 Windows 上运行 Claude Code 桌面版时的虚拟化平台要求。如果你在 Windows 上遇到 Claude Code 无法启动或 skills 不加载的情况可以检查以下几点确认系统已启用虚拟机平台功能在“启用或关闭 Windows 功能”中查看确认 Claude Code 安装的是最新版本如果使用 WSL确认 skills 目录在 WSL 文件系统内而不是 Windows 挂载盘另外Windows 下路径分隔符和大小写敏感性和 Linux/macOS 不同skill 目录名建议全小写避免出现找不到文件的问题。5.5 skill 开发中的常见误区最后整理几个我见过最多的误区供你对照自查把 skill 当提示词仓库skill 不是让你存一堆提示词的地方每个 skill 应该是一个有明确触发条件和执行边界的独立能力description 写成功能列表description 的核心作用是“告诉 Claude 什么时候用”不是“告诉用户这个 skill 有多厉害”步骤写得太抽象比如“优化代码”这种描述Claude 无法执行。要写成“读取文件按 ESLint 规则格式化输出 diff”忽略失败路径只写成功流程遇到异常 Claude 就卡住或乱答不做版本管理skill 也是代码应该进 Git应该有变更记录5.6 数学建模与垂直场景的 skill 设计要点热词里多次出现“数学建模 skills”“华为杯建模比赛好用的 codex skills”说明 skills 在竞赛和垂直场景里也有很大需求。这类 skill 的设计和通用编程 skill 有些不同。数学建模场景的特点是流程固定、输出格式要求严格、时间压力大。一个建模 skill 通常需要覆盖数据预处理、模型选择、参数调优、结果可视化、论文格式输出。设计时要把每个环节的输入输出定义清楚尤其是论文格式部分最好直接嵌入模板。我建议这类 skill 采用**“主 skill 子 skill”**的结构主 skill 负责流程调度子 skill 分别处理数据、建模、绘图、写作。这样在竞赛中可以根据题目类型灵活组合而不是每次重写整个流程。AI 漫剧常用 skills 也是类似思路把角色设定、分镜生成、台词撰写、画面描述拆成独立 skill按需调用。6. 我个人的使用体会与后续扩展方向用了一段时间 skills 之后我最大的感受是它改变了我跟 Claude 协作的方式。以前是我不断重复交代背景和规范现在是 Claude 主动按我预设的流程执行。这种从“对话”到“协作”的转变效率提升不是一点半点。如果你刚开始接触我的建议是从一个小 skill 做起不要一上来就搞复杂的多 skill 系统。先写一个你每天都会重复交代的任务把它封装成 skill用一周时间观察触发准确率和输出质量再逐步迭代。等这个流程跑顺了再扩展到其他场景。后续扩展方面我觉得几个方向值得尝试一是把 skill 和项目的 CI/CD 流程结合让 Claude 在提交代码前自动执行检查 skill二是把团队规范沉淀成共享 skill 库新成员入职直接加载三是探索 skill 之间的组合调用用主 skill 编排多个子 skill 完成复杂任务。踩过几次坑之后我越来越觉得skills 的价值不在于技术多复杂而在于它把“隐性经验”变成了“显性资产”。你脑子里的那些“遇到这种情况应该这样处理”的判断一旦写成 skill就能被复用、被传承、被改进。这件事本身比任何单个 skill 的功能都更有意义。