1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术群还是内容社区“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新出的编程语言或者框架其实不是。这里的skills特指围绕 Claude 生态尤其是 Claude Code、Claude Desktop 这类工具构建的一套可复用的能力模块机制。你可以把它理解成给 AI 助手装的“技能插件”——每个 skill 就是一份结构化的说明文档告诉模型在特定场景下该怎么思考、怎么调用工具、怎么输出结果。我最早接触这个概念是因为身边做前端的朋友在群里问“前端开发skills有没有推荐的”后来做数学建模的、做 AI 漫剧的、甚至参加华为杯建模比赛的队伍都在讨论“好用的 codex skills”。这说明 skills 已经从一个技术圈的小众玩法扩散到了多个垂直领域。它的核心载体通常是一个叫SKILL.md的文件里面用自然语言加结构化格式描述这个技能干什么、什么时候触发、需要哪些输入、输出成什么样。为什么它值得单独拿出来讲因为过去我们用 AI靠的是“提示词工程”——每次都要重新写一大段 prompt效果还不稳定。而 skills 把这种一次性提示词变成了可版本管理、可分享、可组合的资产。你写好一个 skill别人可以直接拿去用甚至能像开源项目一样在 GitHub 上传播。这就解决了三个痛点一是重复劳动二是效果不可复现三是团队协作时标准不统一。这篇文章适合谁看如果你是刚听说 skills、想搞清楚它到底怎么用的小白我会从最基础的概念讲到手动安装如果你已经在用 Claude Code但只会跑默认功能我会拆解 SKILL.md 的写法、常见坑和排查技巧如果你是团队里负责搭工具链的人我会分享怎么把 skills 组织成一套可维护的技能库。全文基于我自己的实操记录和社区里高频出现的问题整理不堆概念直接上能抄作业的内容。2. skills 的整体设计思路为什么是“文档驱动”而不是“代码驱动”2.1 核心机制用自然语言描述能力边界传统插件或扩展的开发模式是写代码、编译、注册接口。skills 走的是另一条路用 Markdown 文档描述能力。一个典型的 SKILL.md 大概长这样——开头说明这个技能叫什么、解决什么问题中间列出触发条件和执行步骤最后给出输出格式示例。模型读到这份文档后会在对话中判断当前任务是否匹配如果匹配就按照文档里的流程来执行。这种设计的好处非常明显。第一门槛极低。你不需要会写 Python 或 TypeScript只要能把一件事的流程讲清楚就能做出一个 skill。第二可读性极强。任何人打开 SKILL.md 都能看懂这个技能在干什么不像代码需要逐行理解。第三迭代快。改一个流程只需要改几行文字不用重新构建和部署。但这里有个关键点很多人会忽略skills 不是“写完了就自动生效”的。它依赖模型对文档的理解和判断。所以文档写得清不清楚、边界划得明不明白直接决定了这个 skill 好不好用。我见过太多人写 SKILL.md 时犯一个错误——把文档写成了一篇散文没有明确的结构和触发条件结果模型根本不知道什么时候该用它。2.2 与提示词工程的区别从“一次性”到“可沉淀”很多人会问这不就是高级一点的提示词吗区别在于沉淀和复用。提示词是你每次对话时临时写的关掉窗口就没了。skills 是存在文件系统里的可以提交到 Git、可以分享给同事、可以在不同项目之间迁移。更重要的是skills 可以被组合。比如你有一个“代码审查”skill一个“生成测试用例”skill还有一个“写提交信息”skill它们可以在同一个工作流里被依次触发。我自己的做法是把团队里反复出现的任务都抽成 skill。比如“根据接口文档生成前端请求函数”“把 SQL 查询结果转成图表配置”“检查配置文件里的敏感字段”。每个 skill 单独一个文件夹里面放 SKILL.md 和必要的示例文件。这样新同事入职时不用口口相传直接让他看 skills 目录就能上手。2.3 适用场景与不适用场景skills 最适合的场景是流程明确、输出格式固定、重复频率高的任务。比如数学建模里的数据预处理、前端开发里的组件生成、内容创作里的标题优化。这些任务有固定的套路写成 skill 之后每次都能稳定输出。反过来如果你的任务每次都需要大量创造性判断或者输入输出极不固定那写 skill 的投入产出比就不高。我试过给“头脑风暴”写 skill结果发现模型每次都会给出不同的方向文档里的流程反而限制了它的发挥。所以我的经验是先观察自己一周内重复做了哪些事挑出重复三次以上、且步骤基本一致的再考虑做成 skill。3. SKILL.md 的核心细节解析从零写一份能用的技能文档3.1 文件结构四个必须说清楚的模块一份能稳定工作的 SKILL.md我总结下来必须包含四个部分。缺了任何一个模型在使用时都会出现理解偏差。第一部分是元信息。通常放在文件最开头用类似 YAML front matter 的格式写明技能名称、版本、作者、适用场景。这部分不是给模型看的是给人看的方便管理和检索。我习惯加上tags字段比如frontend、>npm install -g anthropic-ai/claude-code装完之后在终端输入claude如果能看到交互界面就说明成功了。如果提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”通常是两个原因一是 npm 全局路径没加到系统 PATH 里二是安装过程中断了。前者可以通过npm config get prefix查看全局路径然后手动加到环境变量后者重新装一遍就行。Windows 用户可能会遇到一个提示说需要启用虚拟机平台。这是因为 Claude Code 的某些功能依赖 WSL 或虚拟化环境。如果你只是用基础的 skills 功能可以忽略这个提示但如果要用到文件系统深度集成建议按提示开启。4.2 手动安装 GitHub 上的 skills社区里已经有不少人把自己写的 skills 开源到了 GitHub。手动安装的过程其实很简单就是把 skill 文件夹放到 Claude Code 能识别的目录里。默认情况下Claude Code 会读取项目根目录下的.claude/skills文件夹以及用户主目录下的.claude/skills。具体步骤先从 GitHub 上把仓库 clone 下来找到里面的 SKILL.md 所在的文件夹整个文件夹复制到.claude/skills下面。注意不要只复制 SKILL.md因为有些 skill 会附带示例文件或模板文件缺了这些文件可能导致 skill 无法正常工作。复制完之后重启 Claude Code然后在对话里输入/skills或者类似的查看命令应该能看到新安装的 skill 出现在列表里。如果没有出现检查文件夹结构是不是对的——必须是.claude/skills/技能名/SKILL.md这种层级不能多一层也不能少一层。4.3 写第一个 skill以“生成前端请求函数”为例我拿一个实际用过的 skill 来演示。假设我们团队经常需要根据后端接口文档生成前端请求函数每次都要手动写类型定义和 fetch 调用很烦。于是我写了一个 skill放在.claude/skills/gen-request/SKILL.md。文档开头是元信息--- name: gen-request version: 1.0.0 tags: [frontend, typescript, api] ---然后是触发条件当用户提供接口文档片段并要求生成前端请求函数时触发。不适用于生成后端代码或数据库查询。执行步骤我写了六步解析接口文档中的 URL、方法、请求参数和响应结构根据参数类型生成 TypeScript interface生成请求函数包含错误处理和 loading 状态输出完整的 .ts 文件内容在文件顶部添加必要的 import最后附上一句使用示例。输出示例里我贴了一个完整的生成结果包括 interface 定义和 async 函数。写完之后我在对话里丢了一段接口文档模型果然按照 skill 的流程生成了代码。第一次生成时漏了错误处理我回去把步骤里的“包含错误处理”改成了“必须包含 try-catch 并在 catch 中抛出带有状态码的错误”再试就稳定了。4.4 验证 skill 是否生效的三种方法怎么确认 skill 真的被触发了我常用三种方法。第一种是看输出结构。如果模型严格按照 SKILL.md 里的步骤和格式输出说明 skill 生效了。第二种是在文档里加一个标记。比如在输出示例里加一行注释// generated by gen-request skill如果生成结果里有这行就说明走的是 skill 流程。第三种是故意给一个不满足触发条件的输入看模型是否会拒绝使用这个 skill。如果它仍然套用流程说明触发条件写得太宽了。这三种方法我通常会组合使用。先用标记法确认生效再用边界输入测试触发条件的准确性。实测下来一个 skill 从写完到稳定工作通常需要三到五轮调整。5. 常见问题与排查技巧实录5.1 skill 不触发或触发错误的排查思路这是最高频的问题。模型没有按预期使用 skill原因通常有三个。第一是触发条件太模糊。比如只写了“当用户需要帮助时”这几乎等于没有条件。解决办法是把触发条件具体化到任务类型、输入特征和排除条件三个维度。第二是文件位置不对。Claude Code 对目录结构有要求SKILL.md 必须在技能文件夹的根层级。我见过有人把 SKILL.md 放在子文件夹里结果一直不生效。第三是文档格式有误。比如 YAML front matter 的冒号后面没加空格或者代码块没有正确闭合都会导致解析失败。排查时我习惯从简到繁先确认文件路径再检查文档格式最后调整触发条件。如果还不生效就新建一个最简单的 skill 测试环境是否正常。5.2 输出格式不稳定的三种约束手段即使 skill 触发了输出格式也可能飘。我总结了三层约束。第一层是模板约束在 SKILL.md 里用代码块给出完整的输出结构。第二层是语言约束明确写出“不要添加解释性文字”“不要使用 Markdown 标题”这类否定指令。第三层是示例约束给一个输入输出对照表让模型有明确的参照。这三层叠加之后格式稳定性会大幅提升。如果还是不稳定我会在 skill 里加一个“自检”步骤让模型在输出前先检查一遍格式是否符合模板如果不符合就重新生成。这个技巧在处理 JSON 输出时特别有效。5.3 多个 skill 冲突时的优先级处理当你装了很多 skill 之后可能会出现两个 skill 都想处理同一个任务的情况。比如一个“代码审查”skill 和一个“代码优化”skill在用户说“帮我看看这段代码”时都可能触发。这时候模型会怎么选实测下来它倾向于选择触发条件更具体的那个。所以我的做法是在触发条件里明确写出优先级关系。比如在“代码优化”skill 里加一句“当代码审查 skill 也适用时优先使用代码审查 skill”。另一个技巧是用命名区分场景。不要叫“代码处理”而叫“前端代码审查”和“后端代码优化”这样模型在匹配时更容易区分。5.4 常见问题速查表问题现象可能原因解决方法skill 完全不触发文件路径错误或格式错误检查.claude/skills/名称/SKILL.md层级验证 YAML 格式触发过于频繁触发条件太宽泛增加任务类型、输入特征、排除条件三层约束输出格式飘忽缺少模板或否定指令添加代码块模板和“不要添加解释”类指令多个 skill 冲突触发条件重叠在文档中写明优先级或用更具体的命名区分安装后看不到 skill未重启或目录不对重启 Claude Code确认目录层级正确执行步骤漏掉步骤描述太抽象把每步拆到可独立验证的颗粒度5.5 几个我踩过的坑第一个坑是在 SKILL.md 里写太多背景介绍。我一开始觉得要把来龙去脉讲清楚结果文档写了三千字模型反而抓不住重点。后来我把背景压缩到三行以内把篇幅留给触发条件和执行步骤效果立刻好转。第二个坑是用中文写触发条件但用英文写输出示例。这种混用会导致模型在判断时出现偏差。现在我统一用中文写说明输出示例根据实际需要选择语言但会在文档里明确标注。第三个坑是忘记更新版本号。skills 是会迭代的改了内容但不改版本号团队里其他人就不知道有新版本。现在我养成了习惯每次修改 SKILL.md 都更新 version 字段并在文件末尾加一行变更记录。6. 不同领域的 skills 应用实例与扩展思路6.1 数学建模场景从数据清洗到论文排版数学建模比赛里时间紧、任务重很多步骤是固定的。我帮一个参赛队伍整理过一套 skills包括“缺失值处理”“特征相关性分析”“模型结果可视化”“论文格式检查”。每个 skill 都写清楚了输入是什么格式的数据、输出是什么格式的图表或段落。比赛时他们直接调用这些 skill省下了大量重复劳动的时间。这里的关键是输入输出格式要统一。比如数据清洗 skill 的输出必须是标准化的 CSV这样后续的分析 skill 才能直接读取。如果每个 skill 的格式都不一样组合起来就会很痛苦。6.2 前端开发场景组件生成与代码审查前端开发是 skills 应用最成熟的领域之一。除了前面说的请求函数生成我还见过有人做“根据设计稿生成组件骨架”“自动补全单元测试”“检查 CSS 命名规范”的 skill。这些 skill 的共同特点是规则明确、重复度高、输出可验证。我自己的前端团队现在有一个 skills 仓库里面放了十几个常用 skill。新项目启动时直接把仓库 clone 到.claude/skills下面整个团队的 AI 辅助能力就对齐了。这比每个人自己写提示词要高效得多。6.3 内容创作场景标题优化与结构检查做内容的朋友可能觉得 skills 离自己很远其实不然。我认识一个做 AI 漫剧的团队他们用 skills 来统一分镜脚本的格式、检查角色对话是否符合人设、生成每集的标题备选。这些任务以前靠人工审核现在写成 skill 之后模型能自动完成初筛人只需要做最终确认。内容创作类 skill 的难点在于判断标准比较主观。我的建议是把主观标准拆成可量化的规则。比如“标题要有吸引力”太模糊改成“标题长度在 15 到 25 字之间包含一个数字或疑问词避免使用‘震惊’‘必看’这类词”。这样模型才能稳定执行。6.4 技能库的组织与维护建议当你积累了几十个 skill 之后管理就成了问题。我的做法是按领域分文件夹frontend/、data/、content/、ops/。每个文件夹里放对应的 skill根目录放一个 README 说明每个 skill 的用途和依赖关系。另外建议给每个 skill 加一个examples/子文件夹放输入输出样例。这样新人在使用前能快速了解这个 skill 的实际效果。维护方面我每个月会花半小时过一遍所有 skill把过时的删掉把常用的更新版本号。这个习惯让我们的技能库一直保持可用状态不会变成一堆没人维护的垃圾文件。6.5 从 skills 到工作流组合使用的思路单个 skill 解决单点问题组合起来就能形成工作流。比如“数据清洗 skill → 特征分析 skill → 可视化 skill → 报告生成 skill”就是一条完整的数据分析流水线。组合的关键是接口对齐前一个 skill 的输出格式必须是后一个 skill 能直接读取的输入格式。我通常会在工作流层面再写一个“编排 skill”用来说明这些 skill 的调用顺序和条件分支。比如“如果数据量超过一万行先调用采样 skill 再进入分析流程”。这样整个工作流就变得可配置、可复用而不是每次都要人工判断该用哪个 skill。7. 关于 skills 学习路径的一些个人建议如果你刚开始接触 skills我的建议是不要一上来就写复杂的 skill。先从一个最简单的开始比如“把选中的文本翻译成英文并保持格式”。写完之后跑通感受一下从文档到生效的完整流程。然后逐步增加复杂度加入触发条件、多步骤流程、格式约束。学习资源方面GitHub 上搜 “SKILL.md” 能找到不少开源示例社区里也有专门收集 skills 的仓库。我的习惯是看到好的 skill 就 clone 下来读它的 SKILL.md分析它的触发条件是怎么写的、步骤是怎么拆的。读上十几个之后自己写的时候就有感觉了。最后分享一个我最近在用的技巧给 skill 加一个“自检清单”。在 SKILL.md 末尾列出三到五条检查项让模型在输出前自己过一遍。比如“是否包含了所有必填字段”“是否符合目标语言的语法”“是否遗漏了错误处理”。这个技巧看起来简单但实测下来能减少很多低级错误。我把它用在了所有对格式要求严格的 skill 上效果很稳。