最近在折腾 Claude Code 的时候我花了很多时间研究它的 Skills 机制。如果你也关注 AI 编程工具大概已经发现了社区里有一个叫 awesome-claude-skills 的项目特别火它相当于一个“技能超市”把各种现成的 Skills 整理成了清单从前端开发、数据处理、文档写作到终端命令执行几乎都覆盖了。装上之后Claude Code 的能力会直接上一个台阶。这篇文章我想把自己从零开始接触 Skills、扒 awesome 仓库、装技能再到自己写技能的过程完整记录下来给你一份可以直接照着做的参考。我这里的认知有一个变化过程最早我以为 Skills 只是个插件后来发现它和 MCP 完全是两回事。MCP 提供的是外部工具接口而 Skills 是给模型“预装的操作手册”让它知道在某种情形下该按什么步骤做事。这直接决定了为什么 awesome-claude-skills 会有那么多稀奇古怪的玩法。如果你是刚接触 Claude Code 的新手或者已经在用但总感觉 Agent 不够听指挥这篇内容应该能帮你少走不少弯路。1. 先搞清楚 Skills 到底是什么它和 MCP 的区别在哪里1.1 用一个生活例子理解 Skills你可以把 Claude Code 的 Skills 想象成安检员手里的“操作手册”。安检员知道要检查什么、按什么顺序检查但手头没有仪器MCP 里的工具就是那些仪器——金属探测仪、X光机。Skills 提供流程和规范MCP 提供能力接口两者协作才完整。没有 Skills 的模型虽然也能干很多事但它需要现场思考“我该先做什么后做什么”步骤一多就容易跑偏。有了 Skills 就等同拿到一份 SOP稳定性和效率都会明显提升。社区里有人把 Skills 比作“给 AI 吃一根定海神针”我觉得很贴切。实际测试中一个写好的 Skill 能明显减少模型试错的时间尤其是多步骤任务比如“分析这份日志并生成报告”“把项目里所有图片压缩一遍”“按团队规范生成组件”。没有技能时模型往往要连续追问好几轮才能把握好边界有技能后它只要按手册执行即可输出的一致性也高很多。1.2 Skills 与 MCP 的分工从官方定义来看两者不是替代关系而是互补关系。我用一张表来区分维度SkillsMCP本质一段 Markdown 操作手册外部工具/数据协议解决什么问题告诉 AI 按什么流程做事、有什么领域知识让 AI 能调用真实世界的 API、数据库、文件等形态本地文件夹 SKILL.md远程服务或本地子进程学习成本很低会写 Markdown 就能写中等需要理解工具定义和传输协议触发方式根据 description 自动匹配按需调用指定 tool 名典型例子“代码审查步骤”“读取 PostgreSQL 表”举个协作场景我写了一个“订单分析”Skill里面定义了“读取订单表 → 清洗字段 → 计算毛利 → 输出可视化摘要”的完整流程。具体“读取数据库”的动作则交给 MCP 提供的 database 工具去完成。也就是说Skill 负责“怎么想”MCP 负责“怎么拿”。1.3 为什么社区会有 awesome-claude-skillsSkills 的门槛低到令人发指本质上就是一个带 YAML 前置信息的 Markdown 文件。任何人写一个文件夹就能分享所以社区里很快就积累了大量的技能。而 awesome 系列本来就是 Github 生态里的传统项目形式把分散在各处的高质量内容聚合成一份清单。awesome-claude-skills 的价值不在于代码而在于筛选和聚合。你可能花一小时也找不到某个好用技能但这份清单已经把分类、简介、热度列出来了直接按图索骥就行。我在上面找到一个给图片批量重命名的技能比自己写脚本再让 Agent 临场发挥快了不止一倍。不过也要提醒一句凡是 awesome 类清单质量都参差不齐同一个技能可能有人反馈好用有人反馈报错。我的原则是优先看 README 是否提供了使用示例和依赖说明再看 issues 里有没有人提过安装问题最后再决定要不要装。2. 从 awesome-claude-skills 挑选并安装第一个 Skill2.1 仓库结构速览我打开 awesome-claude-skills 之后第一件事是先看目录结构而不是急着下载。整个清单一般会按场景分类比如前端开发、数据处理、文档写作、终端操作、Git 工作流等。每个条目带着名字、简介、功能标签有些还会标注“需要 Node 环境”或“需要 Playwright”。我的建议是别一上来就装“热门 Top 50”先想清楚自己要解决什么问题。比如我想让 Claude Code 帮我管理 Git 提交信息就在仓库里搜 git想让 Agent 帮我整理 Markdown 排版就搜 markdown。判断一个技能靠不靠谱我有几个标准有没有完整的 SKILL.md描述是否清晰具体有没有依赖说明是不是还需要额外装包README 里有没有截图或者演示输出issues 是不是有人在反馈同类型报错满足三条以上基本可以放心试。2.2 手动安装把文件夹丢到 ~/.claude/skills安装方法很简单社区通用的做法是把 Skill 文件夹放入~/.claude/skills/目录然后重启 Claude Code。我第一次装的时候是这么操作的mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/xxx/awesome-xxx my-skill注意我这里把克隆下来的目录重新命名为my-skill因为有些仓库本身是个合集如果你直接把整个仓库克隆进来Claude Code 扫描的时候可能会找不到真正的 SKILL.md或者扫描出一堆乱七八糟的东西。Windows 用户请放到C:\Users\你的用户名\.claude\skillsmacOS 和 Linux 则是~/.claude/skills。放完之后用claude进入交互界面输入/skills可以看到当前加载的所有技能。2.3 验证是否加载成功装完别急着干活先验证。我每次都会做三件事在 Claude Code 里输入/skills确认技能出现在列表中。发一句贴近 description 的任务比如“用 code-review 技能检查一下当前目录的代码”观察是否被触发。如果没触发先检查 SKILL.md 里name和description是否够具体再检查目录路径是否嵌套错层。第三步是一个新手特别容易踩的坑目录层级多套了一层导致扫描不到。常见的错误路径是~/.claude/skills/my-skill/another/SKILL.md正确路径应该是~/.claude/skills/my-skill/SKILL.md。2.4 我实际装过且觉得好用的几个 Skill下面的列表不是广告只是我个人用下来的真实体验供你参考分类技能名作用备注Git 协作git-workflow自动生成规范提交信息、处理 merge 冲突建议适合团队统一 commit 风格前端开发react-component-creator按项目风格生成 React 组件需要提前在 SKILL.md 写入组件规范终端操作terminal-commander安全执行终端命令并解释结果建议设置权限白名单文档打磨markdown-formatter统一标题层级、表格格式对写作输出很友好代码审查code-reviewer从性能、安全、可维护性三方面检查 diff每次 PR 前我都会触发一下这些技能大多不依赖外部服务装完就能用适合作为首批尝试对象。3. 手把手写一个自己的 Skill完整实操3.1 Skill 的目录结构社区技能看多了之后就会发现标准结构其实非常固定my-skill/ ├── SKILL.md ├── scripts/ │ └── rename.py └── assets/ └── 参考文件.mdSKILL.md 是灵魂它告诉模型这个技能什么时候用、怎么用。scripts放执行脚本assets放辅助资料比如参考模板、示例文件。Claude Code 读取 SKILL.md 来决定是否触发以及触发后按什么步骤执行。如果技能里需要调用脚本建议在 SKILL.md 里写明脚本路径和调用方式同时把脚本权限设置好。我见过有的技能写完脚本但没给执行权限结果 Agent 每次都报 Permission denied很尴尬。3.2 SKILL.md 怎么写SKILL.md 采用 YAML frontmatter 加 Markdown 正文。frontmatter 至少要有name和description。description是触发机制的关键模型会通过它来判断这个技能是否适用所以一定要写清楚“什么场景下使用”而不是只写“这是一个图片处理技能”。正文部分要写清楚任务目标、执行步骤、注意事项、输出格式。以下是我常用的一个模板--- name: image-renamer description: 批量重命名图片文件将文件名中的空格替换为下划线并按序号整理。当用户需要整理图片文件名时使用。 --- # 图片批量重命名 目标将指定目录下所有 .png/.jpg/.jpeg 文件按规则重命名。 步骤 1. 列出目录下所有图片文件。 2. 检查文件名是否包含空格或特殊字符。 3. 用脚本将空格替换为 _并按 image_001.png 格式重命名。 4. 输出重命名前后对照表。 注意 - 不要修改非图片文件。 - 如果文件名已经符合规范跳过。 - 重命名前先确认目录路径。这里要特别强调description不能写太泛比如“图片处理”就太宽模型不知道什么时候该用。要带触发场景例如“当用户需要整理图片文件名时”这样命中率会高很多。3.3 实际例子做一个“批量重命名图片”的 Skill以我处理素材库时的场景为例我经常要把一批图片从“微信图片_20250101_123456.png”这种乱七八糟的名字改成规范文件名。我写了一个rename.py在 SKILL.md 中给出调用方式。import os import sys folder sys.argv[1] if len(sys.argv) 1 else . files [f for f in os.listdir(folder) if f.lower().endswith((.png, .jpg, .jpeg))] for i, f in enumerate(sorted(files), 1): ext os.path.splitext(f)[1] new fimage_{i:03d}{ext} os.rename(os.path.join(folder, f), os.path.join(folder, new)) print(f{f} - {new})然后在 SKILL.md 里写清楚调用方式执行脚本 python scripts/rename.py 目标目录这样模型不用现场写一遍逻辑直接执行脚本即可。实测下来这种“SKILL.md 描述流程 脚本落地执行”的组合比纯让 Agent 自由发挥要稳定得多。3.4 加载与调试技巧写完 Skill 放进~/.claude/skills/image-renamer/之后重启 Claude Code。用/skills查看是否出现。我调试时会直接说一句话触发它“把当前目录中的所有图片重命名一下。”如果没触发多半是description里的关键词和用户描述不匹配。我的经验是把触发场景用多种说法写进 description比如“整理图片”“重命名文件”“统一文件名”这样命中率更高。还有一个调试技巧开启 Claude Code 的详细日志看它到底有没有扫描到这个 Skill。在 Windows 上日志路径在%USERPROFILE%\.claude\logsmacOS 上在~/.claude/logs里面会有加载记录能帮你快速定位问题。4. 不同场景下的 Skills 用法与效率技巧4.1 前端开发场景组件生成与样式修复前端开发是 Skills 用得最猛的场景之一。我的习惯是准备一个 react-component-creator 技能里面写清楚公司的组件命名规范、文件组织方式、常用的样式方案Claude Code 就能在生成组件时直接套用不用每次重新描述需求。比如我写了这样一句描述给技能作为触发场景“当需要创建新的 React 组件时按照项目规范自动生成 TSX、样式文件和测试文件。”然后把这个技能的 SKILL.md 里放上一份真实的组件示例。之后我只要说“新建一个下拉选择组件”它就会拉出标准目录结构效率极高。另一个很实用的是“响应式布局检查”让技能定义好需要检查的视口范围、常见断点再用浏览器工具截图对比非常直观。前端重构时尤其能节省时间。4.2 数据处理与文档写作场景Skills 不只能写代码做数据处理和文档整理同样好用。比如“会议纪要整理”技能输入是录音转写的文本输出是主题、结论、待办事项的模板。模型会严格按模板输出不会自由发挥。这种技能做一次就能反复使用我在团队里已经分享了好几次。“CSV 转 JSON”这种重复性较高的任务也很适合做成技能。把脚本和字段映射规则写进 SKILL.md之后就可以把文件路径扔给 Agent等着拿结果。对于不常写代码的同事来说这就等于把“数据清洗专家”塞给了 Claude Code。文档写作方面我还会给技能放几篇已发布的旧文章作为参考样例让模型模仿我的语气。这样一来每次写技术方案时输出的风格都很统一不用花大量时间改稿。4.3 与 VS Code 配合的玩法我的主力编辑器是 VS Code装的是 Claude Code for VS Code 扩展。在这个扩展里Skills 的加载逻辑和 CLI 一致而且扩展连接到的配置目录也是同一个~/.claude所以 CLI 里已经装好的技能在扩展里也能直接看到。如果扩展没有加载新的 Skill重启一下 VS Code 窗口即可。另外要注意在 VS Code 里执行终端命令时Claude Code 默认会请求确认建议把常用命令放进白名单减少频繁确认的打断。我是用claude config set --global permissions.allow Bash(npm run*)这种方式小范围放开的。别一上来就允许所有 Bash那样等于把终端钥匙交给了 AI万一误判删了文件后悔都来不及。4.4 让 Agent 使用终端命令的正确姿势Skills 非常擅长处理终端操作但安全要放在第一位。我总结的规则有只让技能读取或写指定目录不要给整个文件系统权限。在 SKILL.md 中写明哪些命令是安全的哪些必须先询问。执行权限要最小化不要用Bash(*)这种通配全部放行。高风险命令比如rm -rf、git push --force一定要设为“询问后执行”。网上经常有人踩坑尤其是什么都允许导致误删文件很酸爽。我自己也经历过一次所以现在只要是涉及删除或覆盖操作的 Skill都会在 SKILL.md 里加一句“执行前必须输出将要删除的文件列表并请求用户确认”能避免绝大多数问题。5. 常见安装与运行问题的排查实录5.1 “claude”不是可识别的命令Windows 上经常遇到“claude : 无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。这个一般是安装后 PATH 没生效。重新开一个终端或者手动把%USERPROFILE%\.local\bin加入 PATH。macOS / Linux 下则可能要看安装时的输出确认~/.local/bin是否在 shell 的 PATH 里。安装后我一般会先执行claude --version验证如果能正常输出版本号说明 PATH 没问题之后安装 Skills 才会顺利。5.2 报错Claude native binary not installed这个报错意味着 postinstall 步骤没有跑完常见于 Node 版本过低或安装过程中文件下载不完整。处理思路是确认 Node 版本大于等于 18用node -v查看。清除旧的安装缓存再重新安装。如果是用 npm 装的试一下npm install -g anthropic-ai/claude-code --force。出现这个错误时不要只想着重装先确认系统里是否存在残留的旧版本一路npm uninstall -g清干净再试。我遇到过两次都是因为旧版本没卸干净。5.3 Windows 下“workspace requires the virtual machine platform”Claude Code 在 Windows 上通常依赖 WSL2而 WSL2 需要启用虚拟机平台。报错信息里写了需要启用 Virtual Machine Platform。处理方法是以管理员身份打开 PowerShell执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后执行wsl --set-default-version 2重启电脑。这个问题基本只会出现在 Windows 上macOS / Linux 一般不会碰到。如果之前没有装过 WSL还需要先安装 WSL 内核更新包。5.4 Skills 装了但不生效反复排查如果确认技能已经放进目录/skills里还是没有可以从这几方面排查目录名是否无关紧要但 SKILL.md 文件名必须完全正确是SKILL.md大写不要写成skill.md。SKILL.md 是否有完整的 YAML frontmattername不能有拼写错误description不能为空。是否重启了会话。每个新会话会重新扫描 Skills旧会话不会自动加载新技能。确认目录层级是~/.claude/skills/my-skill/SKILL.md而不是~/.claude/skills/my-skill/another/SKILL.md。还有一个容易忽略的点如果你把 Skills 放在项目的.claude/skills下那么它只对当前项目生效而不是全局。需要全局生效就放到用户目录下的~/.claude/skills。5.5 我常用的排查命令清单把排查过程中常用的命令整理成表格方便你直接抄作业场景命令查看 Claude Code 版本claude --version列出已加载 Skillsclaude --list-skills或在交互界面输入/skills查看当前配置claude config list查看运行日志Windows 在%USERPROFILE%\.claude\logsmacOS 在~/.claude/logs检查 Node 版本node -v这些命令能覆盖绝大多数排查场景。遇到问题先跑一遍这几条往往比直接卸载重装更有用。6. 让 Skills 变成自己的工作流版本管理与更新6.1 用 Git 管理你的 Skills 目录如果你和我一样每天都在和 Skills 打交道建议把整个~/.claude/skills目录做成一个 Git 仓库。这样能记录每个技能的改动历史也能在出问题时轻松回滚到上一个可用版本。初始化很简单cd ~/.claude/skills git init git add . git commit -m init skills之后每次新增或修改技能节点性地提交一次。我有一次改坏了某个技能直接git checkout恢复几分钟就搞定了省去了重新手写的时间。6.2 用软链解决跨项目复用有时候一个技能同时要在多个项目里用但你又不想在每个项目里都复制一份。这时候可以用符号链接把全局技能链接到项目目录ln -s ~/.claude/skills/my-skill /path/to/project/.claude/skills/my-skill这样一来全局技能更新后项目里会立即生效不用重复拷贝。Windows 上可以用mklink /J建立目录联接效果类似。6.3 更新与卸载的节奏从 awesome-claude-skills 安装的社区技能如果原作者更新了你直接去原仓库git pull即可。但如果发现某个技能越来越不满足需求或者触发率越来越低别心疼果断卸载。我自己的体会是技能数量超过十五个之后Claude Code 每次扫描和匹配的负担会明显增加响应速度下降命中率也低。精确地维护一份“少而精”的列表比堆砌一堆“好像有用”的技能要爽得多。最后再说一个我实践了很久才明白的道理Skills 的真正威力不在“装了很多”而在于把那些你每天都要重复做的老流程沉淀下来。把“打开工具 → 输入指令 → 等待结果”变成“说一句话 → 完成”。这个转变一旦发生你和 Claude Code 之间的协作方式就完全不一样了。希望这篇记录能帮你更快摸到门道少踩一些我踩过的坑。
