1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词单独出现很多人会一头雾水。它不像Claude Code 安装教程那样指向明确也不像数学建模 skills 推荐那样有具体场景。但恰恰是这种模糊性说明它已经从一个普通英文单词演变成了一个特定语境下的专有概念——在 AI 编程助手和智能体Agent的生态里skills 指的是一套可复用、可组合的能力模块通常以SKILL.md这样的文件形式存在用来告诉 AI 在特定场景下该怎么做、按什么流程做、遵循什么规范。你可以把它理解成给 AI 助手准备的操作手册合集。没有 skills 的时候你每次都要在对话里反复交代帮我写代码时先检查类型定义做数学建模时先做数据清洗再选模型有了 skills这些经验就被固化下来AI 在需要时自动调用不用你重复啰嗦。这就是为什么最近围绕 skills 的讨论突然多了起来——它解决的是如何让 AI 稳定地按专业标准干活这个核心痛点。这篇文章适合几类人看刚接触 Claude Code 或类似 AI 编程工具、想搞清楚 skills 到底是什么的新手已经在用但觉得每次都要重复交代背景、想提升效率的中级用户以及想自己动手写 skills、把个人经验沉淀成可复用模块的进阶玩家。我会从概念拆解讲到实操安装再讲到怎么写自己的第一个 skill中间穿插我踩过的坑和实测有效的做法。需要先说明一点skills 这个概念目前主要活跃在 Claude 生态里尤其是 Claude Code 这个命令行工具和 Claude Desktop 桌面端。不同工具对 skills 的支持程度不一样有的直接读SKILL.md有的需要额外配置。下面讲的内容以 Claude Code 为主其他工具会顺带提。2. skills 的核心机制SKILL.md 里到底装了什么2.1 一个 skill 的最小结构很多人以为 skill 是个很复杂的东西其实拆开看它的核心就是一个 Markdown 文件。文件名通常叫SKILL.md放在特定的目录下AI 工具启动时会扫描这些目录把符合条件的 skill 加载进来。一个最简的 skill 大概长这样--- name: code-review description: 对提交的代码进行结构化审查检查类型安全、边界条件和命名规范 --- # 代码审查流程 1. 先通读改动理解意图 2. 检查类型定义是否完整有没有 any 滥用 3. 检查边界条件空值、越界、并发 4. 检查命名是否表意清晰 5. 输出审查意见按严重程度排序上面这段里---包起来的部分叫 frontmatter是元数据告诉工具这个 skill 叫什么、什么时候该用它。下面的正文才是真正的操作指令。AI 在判断当前任务和某个 skill 的 description 匹配时就会把这个 skill 的正文加载进上下文然后按里面的步骤执行。这里有个关键点description 写得好不好直接决定 skill 会不会被正确触发。我见过太多人把 description 写成一个有用的工具这种废话结果 AI 根本不知道什么时候该用它。正确的做法是把触发场景写具体比如当用户要求审查代码、检查代码质量、或提交 PR 前需要自查时使用。2.2 skills 和 prompt、和普通文档的区别有人会问那我直接把要求写在对话里不就行了为什么要搞个 skill 文件区别在于三个字可复用。写在对话里的要求这次用完就没了下次还得重打。写成 skill它就变成了一个持久化的资产任何一次对话只要场景匹配就能自动加载。而且 skill 可以被版本管理、可以分享给别人、可以组合调用——这些是临时 prompt 做不到的。那它和普通的说明文档又有什么区别普通文档是给人看的skill 是给 AI 看的。这个区别体现在写法上给人看的文档可以含糊、可以靠常识补全给 AI 看的 skill 必须把每一步都写清楚因为 AI 不会猜你的意图它只会严格执行你写的东西。所以写 skill 的时候宁可啰嗦不要留白。2.3 为什么是 Markdown 而不是别的格式用 Markdown 有几个实际好处。第一它天然支持结构化标题、列表、代码块都能表达AI 解析起来也顺。第二它人也能读你写完 skill 自己扫一眼就知道逻辑对不对。第三它和 Git 配合得好改了什么一目了然。相比之下如果用 JSON 或 YAML 写 skill 逻辑嵌套一深就没法看了。我实测下来一个 skill 控制在 50 到 200 行之间比较合适。太短了信息不够AI 执行时还得自己发挥太长了会占用大量上下文而且 AI 容易抓不住重点。如果某个 skill 确实需要很长的流程建议拆成多个小 skill用命名区分比如>node -v npm -v如果版本太老Node 低于 18先去官网升级。然后全局安装npm install -g anthropic-ai/claude-code装完之后在终端输入claude如果能看到交互界面就说明成功了。这里有个高频坑Windows 用户有时候会遇到无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称这通常是 npm 全局 bin 目录没加到 PATH 里。解决办法是找到 npm 的全局路径npm config get prefix把这个路径加到系统环境变量 PATH 里重启终端即可。另一个 Windows 上常见的问题是提示需要启用虚拟机平台virtual machine platform这是因为 Claude Code 的某些依赖需要 WSL 支持按提示在启用或关闭 Windows 功能里勾选对应项重启后就好。3.2 skills 放在哪个目录Claude Code 加载 skills 有几个约定位置优先级从高到低大致是位置作用范围适用场景项目根目录.claude/skills/仅当前项目项目专属流程比如这个仓库的代码规范用户目录~/.claude/skills/当前用户所有项目个人通用习惯比如代码审查风格工具内置目录全局官方或第三方分发的 skill 包我的建议是通用能力放用户目录项目特有的放项目目录。比如代码审查提交信息规范这种到哪都用得上的放~/.claude/skills/而这个项目的数据库迁移流程这种只跟特定仓库相关的放项目里的.claude/skills/。每个 skill 一个独立文件夹文件夹里放SKILL.md。目录结构大概是这样~/.claude/skills/ ├── code-review/ │ └── SKILL.md ├── commit-message/ │ └── SKILL.md └──>git clone https://github.com/xxx/awesome-skills.git cp -r awesome-skills/typesafe-review ~/.claude/skills/第三步检查 frontmatter 是否完整。有些分享的 skill 缺name或description这种加载时会出问题。打开SKILL.md确认一下缺了就补上。第四步重启 Claude Code。skills 是在启动时扫描加载的改完不重启不生效。重启后在对话里描述一个匹配的场景看 AI 有没有按 skill 里的流程走以此验证是否加载成功。注意从网上拿来的 skill 不要直接无脑用。先通读一遍内容确认里面没有奇怪的指令比如让它执行某些你不清楚的命令。skill 本质上是给 AI 的指令来源不明的要谨慎。3.4 验证 skill 是否生效的土办法官方没有提供列出已加载 skills的命令我一般用两个土办法验证。第一个是直接问 AI你现在加载了哪些 skills它有时候能答出来。第二个更可靠故意触发某个 skill 的场景看它的行为是否符合 skill 里定义的流程。比如你的code-reviewskill 要求先通读再检查类型那你就丢一段代码给它看它是不是按这个顺序来的。如果它跳过了通读直接挑毛病说明 skill 没加载或者没被匹配上。匹配不上的常见原因是 description 写得太泛。这时候把 description 改得更具体加上明确的触发词重启再试。4. 自己写一个 skill从需求到落地4.1 先想清楚这个 skill 解决什么重复劳动写 skill 之前先问自己我是不是每次做某类任务时都要重复交代同样的背景和要求如果是那它就值得被写成 skill。反过来如果一件事你只做一次写 skill 就是浪费时间。举几个我实际写成 skill 的例子每次让 AI 写 SQL 都要提醒用 CTE 不要用嵌套子查询字段名用下划线加注释说明索引意图——这三条重复了十几次之后我就写了个sql-styleskill。再比如数学建模每次都要交代先做缺失值处理再标准化再选模型最后做交叉验证这套流程固定下来就成了modeling-workflowskill。判断标准很简单重复三次以上的交代就该沉淀成 skill。4.2 frontmatter 的写法细节frontmatter 里最关键的是description。它的作用是让 AI 判断当前任务要不要用这个 skill所以写法上要包含触发场景和关键词。对比一下差的写法description: SQL 相关好的写法description: 当用户要求编写、优化或审查 SQL 查询时使用涵盖 CTE 写法、命名规范、索引注释和性能考量好的写法里编写、优化、审查 SQL是触发场景CTE 写法、命名规范是关键词AI 匹配时命中率会高很多。name字段用短横线连接的小写单词比如code-review、sql-style别用中文或空格避免路径问题。4.3 正文怎么写才让 AI 执行得稳正文是 skill 的灵魂。我的经验是遵循三条原则。第一用编号步骤不用大段描述。AI 对有序列表的执行准确率明显高于散文式段落。把流程拆成 1、2、3、4每步一句话说清楚做什么。第二给出判断标准不给模糊要求。比如不要写检查代码质量要写检查是否存在未处理的 Promise rejection、是否有硬编码的密钥、函数是否超过 50 行。有具体标准AI 才知道怎么算通过。第三关键处给正反例。有些要求光说不够得给例子。比如命名规范写一句变量名用 camelCase常量用 UPPER_SNAKE_CASE再附上一两个正例反例AI 执行起来就准了。下面是一个相对完整的 skill 正文示例# 数据建模工作流 ## 步骤 1. 读取数据后先输出字段类型和缺失值比例 2. 缺失值超过 30% 的字段建议删除并说明理由 3. 数值字段做标准化类别字段做独热编码 4. 按 7:3 划分训练集和测试集随机种子固定为 42 5. 至少尝试三种模型输出对比表格 6. 对最优模型做五折交叉验证报告均值±标准差 ## 注意事项 - 不要在划分数据集之前做标准化会造成数据泄漏 - 类别字段如果基数过高超过 50 类改用目标编码 - 所有随机操作必须固定种子保证可复现这个 skill 里步骤是编号的判断标准是量化的30%、50 类注意事项点出了容易犯的错。AI 拿到这样的指令执行起来就稳。4.4 写完之后的调试循环skill 不是一次写好的得反复调。我的调试流程是写第一版找个真实任务跑一遍观察 AI 哪一步没按预期走针对性改那一句再跑。通常改个三四轮就稳定了。有个细节值得注意如果 AI 总是跳过某一步可能是那一步写得太靠后或者表述不够强。把它提到前面或者加上必须务必这类强调词。反过来如果 AI 在某一步上过度发挥说明那一步写得太模糊得收紧。5. 不同场景下的 skills 实战案例5.1 前端开发场景前端开发里重复交代最多的是组件规范。我写过一个react-componentskill核心是几条硬性要求组件用函数式写法、props 必须有 TypeScript 类型、样式用 CSS Modules 不用内联、副作用统一放 useEffect 并注明依赖。写完之后让 AI 生成组件时基本不用再纠正风格问题。前端还有个高频场景是改完代码要跑什么检查。我把它也写进 skill改完先跑类型检查再跑 lint再跑单元测试三步都过了才算完成。这样 AI 不会改完就交差而是会自己走完验证流程。5.2 数学建模场景数学建模比赛里时间紧、任务重skills 的价值特别明显。我整理过一套建模 skill覆盖从数据预处理到论文撰写的全流程。其中>