1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新的编程语言或者框架其实不是。这里的skills特指围绕 Claude 生态尤其是 Claude Code、Claude Desktop构建的一套可复用的能力模块。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张技能卡里写清楚了这个技能是干什么的、什么时候触发、需要哪些输入、按什么步骤执行、输出成什么格式。核心载体是一个叫SKILL.md的文件。这个文件用 Markdown 写里面包含技能的元信息名称、描述、触发条件和具体的执行指令。Claude 在运行时会读取这些技能定义当用户的请求匹配到某个技能的触发条件时就自动加载对应的指令来完成任务。这套机制解决了一个很实际的问题你不需要每次都从头写一大段提示词而是把常用的工作流固化成一个技能随用随调。那为什么现在特别值得关注因为 Claude Code 这个命令行工具把 skills 的威力放大了。Claude Code 本身是一个跑在终端里的 AI 编程助手能读写文件、执行命令、操作 Git而 skills 让它从“通用助手”变成“懂你套路的专属助手”。比如你团队有一套固定的代码审查流程、有一套固定的周报生成格式、有一套固定的数学建模解题模板这些都可以写成 skill以后一句话就能触发。这篇文章适合谁看三类人第一类是完全没接触过 Claude Code 和 skills 的新手想搞清楚这东西到底怎么用第二类是用过 Claude Code 但还没认真研究 skills 机制的开发者想把自己的重复劳动自动化第三类是关注 AI 工作流设计的技术管理者想评估这套东西能不能落到团队里。我会从概念、安装、SKILL.md 写法、实战案例、常见坑几个维度展开尽量把每一步都讲透。2. 核心概念拆解SKILL.md、Agent Skills 和 Claude Code 的关系2.1 SKILL.md 到底长什么样很多人搜“ai skills怎么写”其实答案就藏在 SKILL.md 的结构里。一个典型的 SKILL.md 由两部分组成YAML frontmatter和Markdown 正文。Frontmatter 里定义元数据正文里写具体指令。--- name: code-review description: 对指定文件进行代码审查输出问题清单和改进建议 trigger: 当用户要求审查代码、review 代码、检查代码质量时触发 --- # 代码审查技能 ## 执行步骤 1. 读取用户指定的文件或目录 2. 检查以下维度 - 命名规范 - 错误处理 - 边界条件 - 性能隐患 3. 按严重程度分级输出问题 4. 每个问题给出修改建议和示例代码这个结构看起来简单但有几个关键点容易被忽略。description字段非常重要Claude 靠它来判断当前请求是否匹配这个技能。写得越具体匹配越准。trigger字段是给使用者看的说明实际匹配逻辑还是靠 description 的语义。正文部分就是给 Claude 的指令写得越像一份操作手册越好不要写成散文。2.2 Agent Skills 和普通 prompt 的区别有人会问我直接写一段 prompt 不就行了为什么要搞个 skill 文件区别在于三个层面。第一是复用性prompt 每次都要重新粘贴skill 装一次到处能用。第二是结构化skill 有明确的元数据和触发条件Claude 能自动判断什么时候该用哪个技能不需要你手动切换。第三是可组合多个 skill 可以串联使用比如先触发“数据清洗”技能再触发“可视化”技能最后触发“报告生成”技能。Agent Skills 这个概念强调的是“代理能力”——不是被动等你提问而是主动根据上下文调用合适的技能。这也是为什么 skills 在 Claude Code 里特别有用因为 Claude Code 本身就是一个 agent能自主决定读哪个文件、跑哪条命令加上 skills 之后它的决策空间更大了。2.3 Claude Code 在其中的角色Claude Code 是 Anthropic 推出的命令行 AI 编程工具可以理解成一个跑在终端里的智能助手。它和 skills 的关系是Claude Code 是运行时环境skills 是运行在这个环境里的能力包。你可以在 Claude Code 里通过斜杠命令或者自然语言触发某个 skillClaude Code 会加载对应的 SKILL.md然后按照里面的指令执行。Claude Code 支持的操作包括读写本地文件、执行 shell 命令、操作 Git 仓库、调用外部 API 等。这意味着 skill 的能力边界很大——你可以写一个 skill 让它自动跑测试、自动生成 commit message、自动整理项目文档。这也是为什么最近“claude code stm32”“数学建模skills”这类搜索词特别多因为大家发现这套东西可以套用到各种专业场景里。3. 环境准备从零安装 Claude Code 并配置 skills 目录3.1 安装 Claude Code 的完整流程安装 Claude Code 本身不复杂但新手容易在环境上卡住。先说前提条件你需要一个 Node.js 环境建议 18 以上版本以及一个可用的终端。Windows 用户建议用 WSL 或者 Git Bash因为部分命令在 PowerShell 里会有兼容性问题。安装命令很简单npm install -g anthropic-ai/claude-code装完之后在终端输入claude就能启动。如果你看到“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这种报错说明 npm 的全局 bin 目录没有加到 PATH 里。解决办法是找到 npm 的全局安装路径npm config get prefix然后把那个路径下的 bin 目录加到系统环境变量里。Windows 用户注意加完之后要重启终端才生效。还有一个常见问题是 Windows 上提示“requires the virtual machine platform”这是因为 Claude Code 的某些功能依赖虚拟化支持。解决办法是在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启后即可。3.2 skills 目录应该放在哪里Claude Code 查找 skills 的位置有几个约定。全局 skills放在~/.claude/skills/目录下这里的技能对所有项目生效。项目级 skills放在项目根目录的.claude/skills/下只对当前项目生效。我建议把通用技能比如代码审查、文档生成放全局把项目特定技能比如这个项目的部署流程放项目级。目录结构是这样的~/.claude/skills/ ├── code-review/ │ └── SKILL.md ├── weekly-report/ │ └── SKILL.md └──>--- name: commit-helper description: 读取 git 暂存区改动生成符合约定式提交规范的 commit message trigger: 当用户要求生成 commit message、提交代码、写提交信息时触发 --- # Commit Message 生成技能 ## 前置检查 1. 执行 git diff --cached --stat 确认有暂存内容 2. 如果没有暂存内容提示用户先执行 git add ## 分析改动 1. 执行 git diff --cached 获取详细改动 2. 判断改动类型 - 新增功能文件 → feat - 修复 bug → fix - 只改文档 → docs - 只改格式 → style - 重构不改行为 → refactor - 加测试 → test - 构建/配置 → chore ## 生成 message 1. 格式type(scope): description 2. description 用中文不超过 50 字 3. 如果改动涉及多个类型选最主要的那个 4. 输出后询问用户是否确认确认后执行 git commit -m ... ## 示例 输入新增了用户登录接口 输出feat(auth): 新增用户登录接口这个 skill 写完之后你在 Claude Code 里说“帮我提交代码”它就会自动走这套流程。注意我在里面加了“前置检查”和“确认”步骤这是为了避免它在你没准备好时乱提交。4.3 调试 skill 的实用技巧新写的 skill 第一次跑大概率不会完美。我的调试方法是先手动触发观察 Claude 的执行路径看它在哪一步偏离了预期。如果它没有按步骤走通常是 description 写得不够明确或者步骤之间的逻辑有歧义。另一个技巧是在 skill 里加日志输出。比如让它在每一步执行前打印当前状态这样你能清楚看到它卡在哪。调试稳定之后再把日志去掉。注意skill 的正文不要写得太长。我见过有人写了 2000 字的 skill结果 Claude 执行时反而容易漏步骤。控制在 500 字以内步骤不超过 7 步是最舒服的范围。5. 进阶玩法多 skill 组合与专业场景落地5.1 数学建模场景的 skills 设计最近“数学建模skills”搜索量很高我专门研究了一下这个场景。数学建模比赛的特点是时间紧、任务重、流程固定非常适合用 skills 来提效。我设计了一套三个 skill 的组合第一个是“题目解析”skill输入赛题文本输出问题拆解、涉及领域、可能的模型方向。第二个是“模型选择”skill根据题目类型推荐合适的数学模型并给出求解思路。第三个是“论文框架”skill按照竞赛论文的标准结构生成大纲包括摘要、问题重述、模型假设、符号说明、模型建立、求解、检验、评价等部分。这三个 skill 串联起来基本覆盖了从读题到成文的主干流程。当然模型的具体推导和代码实现还是得人来但框架性的工作能省下大量时间。5.2 前端开发场景的 skills 实践“前端开发skills”也是热词。前端日常有很多重复劳动组件脚手架生成、样式规范检查、接口联调 mock、打包配置优化。我写了一个“组件生成”skill输入组件名和类型表单、列表、弹窗自动生成对应的 Vue 或 React 组件文件包括模板、逻辑、样式三部分并且遵循项目的命名规范和目录结构。还有一个“样式审查”skill读取指定的样式文件检查是否有硬编码颜色值、是否有未使用的类名、是否符合 BEM 命名规范输出问题清单。这类 skill 的价值在于把团队规范固化下来新人也能一键产出符合规范的代码。5.3 skill 之间的调用与依赖管理多个 skill 之间可以互相调用。比如“论文框架”skill 里可以引用“模型选择”skill 的输出。实现方式是在 SKILL.md 里写明依赖关系## 依赖 本技能依赖 model-selector 技能的输出请先执行 model-selectorClaude 在执行时会先检查依赖的技能是否已经运行过如果没有会提示你先跑前置技能。这种设计让复杂工作流可以拆成多个小 skill 来维护每个 skill 只负责一件事组合起来完成大任务。6. 常见问题与排查技巧实录6.1 skill 不触发怎么办这是最高频的问题。排查顺序如下先确认 SKILL.md 是否被正确加载用/skills命令查看再检查 description 是否和你的提问语义匹配最后看是不是有多个 skill 的触发条件重叠导致 Claude 选错了。解决办法把 description 写得更具体加入明确的触发词。比如不要写“处理数据”要写“清洗 CSV 文件中的缺失值和异常值”。触发词越具体匹配越准。6.2 skill 执行到一半卡住常见原因是某一步依赖的外部命令不存在或者文件路径不对。排查方法是让 Claude 输出当前执行到哪一步然后手动验证那一步的命令能不能跑通。另一个原因是 skill 里的指令有歧义Claude 不确定该怎么做就停在那里了。这时候需要把那一步拆得更细。6.3 如何清理不需要的 skills搜“清理skills的方法”的人不少。其实很简单全局 skills 直接删~/.claude/skills/下对应的文件夹项目级 skills 删.claude/skills/下的文件夹。删完之后重启 Claude Code 就生效了。建议定期清理因为 skill 太多会影响 Claude 的匹配效率。问题现象可能原因解决办法skill 不触发description 不匹配加入具体触发词加载失败frontmatter 格式错误检查---是否成对执行中断依赖命令缺失手动验证每步命令选错 skill多个 skill 条件重叠细化各自的 description输出格式不对指令不够明确在 skill 里加输出示例6.4 几个我踩过的坑第一个坑是在 skill 里写了太多“如果……那么……”的分支逻辑结果 Claude 执行时反复横跳。后来我改成每个 skill 只处理一种情况复杂场景拆成多个 skill。第二个坑是忘了处理空输入。有一次写了个“文档生成”skill用户没给文件路径就直接触发Claude 愣在那里不知道读什么。后来我在每个 skill 开头都加了输入校验步骤。第三个坑是skill 名称用了中文在某些系统上路径解析出问题。改成英文之后就没再出现过。7. 关于 skills 生态的一些个人观察这套东西目前还在快速演进中。我观察到几个趋势一是 skills 的分享社区在形成有人专门整理“skills推荐”清单把好用的技能打包分享二是 skills 开始和具体工具链深度结合比如和 VS Code 的集成、和 CI/CD 流程的集成三是出现了针对特定领域的 skill 集合比如专门做数据分析的、专门做安全审计的。如果你刚开始接触我的建议是先从一个小痛点入手写一个最简单的 skill 跑通全流程感受一下从“手动操作”到“一句话触发”的差别。跑通之后你自然就知道该怎么扩展了。不要一上来就设计一个大而全的技能体系那样大概率会烂尾。另外SKILL.md 的写法没有绝对标准不同版本的 Claude Code 对格式的要求可能有细微差异。遇到解析问题时优先参考官方文档的最新说明其次看社区里别人分享的可运行示例。自己多试几次比看十篇教程都管用。