前一阵我把散落在 GitHub、博客、产品文档和社区帖子里的 Claude Code Skills 翻了一个遍逐个在空目录里装、跑、排查最后整理成了一个名为 awesome-claude-skills 的清单仓库。起因很实际Claude Skills 这个概念火起来之后资料太散了。官方文档讲概念社区仓库给代码偶尔刷到几篇文章又各说各话新同学根本不知道从哪下手。这份清单沉淀下来之后我反而对“Skills 到底是什么、怎么装、怎么写、出问题怎么查”有了比之前更系统的理解。后面这些内容就是我整理和实操过程中反复验证过的做法。想给 Claude Code 加技能、想开发自己的第一个 Skill、或者只是好奇 Agent Skills 这个新玩意的都可以直接参考不用从头踩一遍我踩过的坑。1. 先搞清楚Claude Skills 到底是什么很多人一上来就搜“skills 推荐”“skills 下载平台”然后对着十几个 GitHub 仓库发呆。其实第一步不是找技能而是搞清楚 Skills 在 Claude 生态里的定位。简单说Agent Skills 是一组打包好的“技能目录”里面有一个说明文件 SKILL.md加上若干脚本、模板、参考资源。Claude 在对话中会先扫描这些技能根据描述判断“当前任务该不该用”一旦匹配就会按照你写的步骤和脚本去执行。这样设计有一个非常大的好处它把“怎么做好一件事”的经验固化下来了。平时我们让 Claude 干活要么靠一条写得很长的提示词要么靠模型自己临场发挥。有了 Skills你可以把团队里总结的代码审查规范、周报格式、前端组件封装套路全部变成一个可复用的目录。不同项目、不同人拿到同一个 Skill行为就是一致的。1.1 别把三个概念混在一起Skills、MCP、Prompt在搜“claude skills”的时候你会频繁看到 MCP、Prompt、Agent Skills 三个词一起出现新手很容易搞混。我用一个生活化的方式给你掰开。Prompt 就是口述需求。你直接说“帮我写个 Vue 组件”模型听懂了就写。特点是灵活但每次都要重新描述背景和规范还容易漏细节。MCP 是给模型“配手”的。它可以让 Claude 调用外部系统比如读取文件系统、操作数据库、调用浏览器 API。你可以把它理解成给实习生发钥匙、工牌和打印机让他能真正碰设备、办事。Skills 是给模型“配手册”的。里面写着做一件事的标准流程、注意事项、模板样例甚至还有现成脚本。相当于给实习生一本《项目操作 SOP》。一个完整的协作场景往往是用户提出需求Claude 读取自己的 Skills 手册通过 MCP 连接外部工具拿数据、改文件最后把结果生成出来。想通这一点你就不会把「装一个 MCP 服务器」和「装一个 Skill」当成同一件事了。1.2 扒开一个 Skill 看看它到底长什么样我最初看 Skills 文档的时候最困惑的是“它到底是一个文件还是一个文件夹”。答案是一个目录。一个标准 Skill 的结构大概长这样my-skill/ ├── SKILL.md # 技能说明Claude 最先读取这个文件 ├── scripts/ │ ├── generate_report.sh │ └── stats.py └── resources/ ├── template.md └── examples/ └── demo-output.mdSKILL.md 是整个技能的入口。它一般带一个 YAML 头部里面至少包含 name 和 description 两个字段正文则用自然语言描述触发场景、执行步骤、输入输出格式、注意事项。Claude 会在合适的时机扫描这些技能通过 description 判断当前任务是否匹配。scripts 和 resources 不是必须的但非常有用。脚本负责执行机械化操作比如批量重命名、生成统计表资源目录则放模板、示例文件让模型的输出风格保持一致。你可以这样理解SKILL.md 是大脑scripts 是手脚resources 是参考书。1.3 为什么要维护一份 awesome 清单Claude Skills 这个生态目前最大的问题是“没有统一包管理器”。MCP 好歹有 marketplace、有 npx 一键启动的模式而 Skills 基本还是靠 GitHub 仓库分发。社区里东西很多但命名不统一说明文档各异质量参差不齐。awesome-claude-skills 这类清单的价值就是帮你把“值得用的”和“看看就行的”分开。我整理时会按场景分类前端开发、代码审查、部署运维、数据分析、写作助手等。同时每个收录的技能我都会确认三件事描述写得好不好、脚本能不能跑、有没有明显的外部依赖。还有个小提醒GitHub 官方的“GitHub Skills”是交互式学习课程系统跟 Claude Agent Skills 完全不是一回事。不少人是搜到 GitHub Skills 误入的。另外还有个 Codex Skills那是 OpenAI 那边 Agent 生态的类似概念思路很像但目录格式和触发机制不一样别混用。2. 安装配置从零到能跑起来很多人卡在第一步不是技术不行而是不知道“装好之后到底把技能文件放哪”。实际上 Claude Code 的安装只是开始把 Skills 放进正确的位置才是能用的关键。2.1 安装 Claude Code 的完整步骤macOS / Windows / UbuntuClaude Code 本质上是一个 Node.js 包安装方式很简单。前提是你机器上有 Node.js 18 以上版本。我个人的建议是用 nvm 管理 Node因为不同项目可能要求不同版本nvm 切起来最省心。macOS 和 Linux 上命令都一样npm install -g anthropic-ai/claude-code装完直接运行claude --version能输出版本号就说明装好了。但很多 Windows 用户会遇到「claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称」的报错。这不是没装成功而是 npm 的全局 bin 目录不在 PATH 里。解决办法是先查一下全局路径npm config get prefix在 Windows 上这个路径通常是%APPDATA%\npm把该目录加到系统环境变量的 PATH然后重开一个终端就好了。macOS/Linux 上常见的是~/.npm-global或~/.local/bin。Ubuntu 用户容易踩的一个坑是用系统自带的 apt 装 Node版本往往比较旧导致 Claude Code 安装时报错或者启动异常。我建议在 Ubuntu 上先装 nvm再安装 Node 20 LTS之后用 npm 装 Claude Code。另外注意不要用 sudo 跑全局 npm install权限问题后期会暴露出一堆麻烦比如下面要说的 native binary 安装失败。VS Code 用户可以从插件市场搜 Claude Code 插件装完在侧边栏打开面板即可。桌面版的 Claude 也值得装因为部分操作可以脱离终端完成但它和 CLI 是否读取同一套 Skills 目录不同版本表现不一致。我的建议是先在 CLI 里验证 Skill 生效再切到桌面端或 IDE 观察否则你都不知道问题出在哪一环。2.2 把 skills 放进正确的位置个人级 vs 项目级Skills 放哪里决定了它的作用范围。个人用户级目录是~/.claude/skills/所有项目共用。你在里面建一个子目录比如~/.claude/skills/frontend-vue-beautifier/那么只要是在本机跑 Claude Code任何项目里都能识别到这个技能。适合放你自己总结的通用工作流比如写周报、写 commit message、代码风格审查这种跟项目无关的能力。项目级目录是项目根目录/.claude/skills/。这个目录可以随 git 一起提交团队所有人都能看到、用到。适合放跟当前业务强绑定的技能比如“某项目的数据表结构说明”“某规范下的组件生成器”。新成员把仓库一 clone技能就自动到位这个体验非常爽。放好之后怎么确认加载了不同版本的命令名有差异。我在某一版里用/skills能列出当前可用技能但有些版本插件不同入口也会变成/help里的某个子命令。最稳妥的办法是装完开一个新会话直接按技能描述的场景触发一次看模型有没有按预期行动。如果没反应先检查目录拼写再看 SKILL.md 的 description 是否写在标准字段里。注意Skill 目录名尽量用 kebab-case比如 frontend-vue-beautifier不要带版本号也不要用空格和中文。模型扫描文件系统时目录名、文件名都会进入上下文太乱会拖慢响应也会降低匹配精度。2.3 配置与权限settings.json、permissions 与环境变量Claude Code 的配置集中在.claude/settings.json里项目级和个人级都可以放。这里面的 permissions 配置非常关键它决定了 Claude 能执行哪些命令、读取哪些目录。一个常见的做法是允许 Skill 脚本所在的特定目录并放行可复现的安全命令。比如你的 Skill 要跑python3 scripts/format_data.py那就在 settings 里允许这个具体命令而不是允许通配所有 shell。这样平时不会被权限弹窗打断又不会把大门全敞开。团队协作时我建议把.claude/settings.json提交到仓库里让所有成员的行为一致。但千万不要把密钥、token 一类敏感信息放进去。settings 文件里的环境变量只放非秘密的配置真正敏感的走系统环境变量或者密钥管理器。3. 自己动手写一个 Skill以前端开发为例搜“skills 开发”“前端开发 skills”的人很多但真正能下笔的人很少。其实写 Skill 的门槛比想象中低我拿一个前端场景完整演示一遍你就知道套路了。3.1 怎么选题一件事一个 Skill写 Skill 之前先明确你高频重复的动作是什么。前端场景里很多人反馈最多的就是“要不要帮我生成一个 Vue3 组件”“帮我按项目风格写样式”“帮我审查一遍组件 props 设计”。这些都是非常典型的 Skill 选题因为需求明确、输出物固定、评审标准清楚。我强烈建议一个 Skill 只解决一件事。你看到社区里有些 Skills 号称“万能助手”什么都写实际上 model 触发时会犹豫不决也不知道该按哪套规范执行。写得窄description 精确模型反而更愿意调用。3.2 SKILL.md 结构与写法这是整个 Skill 的灵魂。我用一个实际可跑的示例--- name: frontend-vue3-component-generator description: 根据用户需求生成 Vue3 单文件组件包含 template、script setup、style并遵循项目内部代码风格。用户提到“新建组件、写组件、生成组件”或给出组件功能描述时使用。 --- # Vue3 组件生成器 - 仅在用户要求创建或重构 Vue3 组件时使用 - 输入组件名称、props、业务描述 - 输出一个 .vue 文件或将其写入 src/components/ 下 ## 步骤 1. 如果用户未说明组件用途先问清楚 props 与事件最多一轮 2. 创建 script setup langtsprops 使用 defineProps 定义 3. 模板使用语义化标签根节点用一个 div 包裹 4. 样式使用 scoped优先用 CSS 变量 5. 生成代码后标注使用示例等待用户确认 ## 示例 用户说“做一个商品卡片组件”要求显示图片、标题、价格、标签点击跳转详情。 输出组件名 ProductCardprops 包含 img、title、price、tags事件为 click。这里每个部分都有它的作用。name 是内部标识description 决定模型什么时候调用它所以宁可多写几个触发词也别写过于抽象的话。正文部分用命令式短句直接说明步骤不要写“我需要你……”这种废话。示例则是很好的对齐方式让模型知道用户口头描述会对应什么输出物。3.3 加脚本和模板让 Skill 真正“会动手”光靠 SKILL.md 写文字Skill 的力量还发挥不出来。真正提效的是脚本和模板。比如你要让 Skill 自动生成组件可以在 resources/ 下放一个 template.vue内含项目标准的写法。SKILL.md 里写明总是从 resources/template.vue 读取模板然后填充业务变量。这样无论模型怎么发挥输出风格都统一。再比如你想让 Claude 在生成组件后自动跑一遍 lint 校验可以把校验命令写进步骤里。脚本推荐用系统自带的语言比如 python3、node、bash避免装一堆依赖。脚本必须加 shebang并设置执行权限否则跨机器跑会莫名卡住。我在给 Skill 加脚本时有个习惯先在外面手动跑一遍脚本输入假数据确认它能独立正常工作再把它写进 SKILL.md。否则你不确定是脚本本身的问题还是 Claude 调用方式的问题排查起来会非常痛苦。3.4 调试技巧怎么判断 Claude 到底用了没有写完 Skill 之后第一件事不是去复杂项目里测而是新开一个会话直接说“帮我生成一个商品卡片组件”。接着观察输出。如果模型没有按你 Skill 的步骤走先不要怀疑模型智商大概率是 description 没写好。太窄、太泛、关键词不匹配都会导致不触发。我在 SKILL.md 里留过一个调试小技巧可以在步骤开头写一句“如果使用本技能请先回复使用技能 frontend-vue3-component-generator”。这样你一眼就能看出它到底调没调。如果触发了但输出格式不对多半是正文的描述不够具体。检查步骤里有没有明确指向 resources 下的模板文件脚本路径是否写对。我在调试时会把 SKILL.md 的文本量控制在几分钟内能读完太长的说明书模型也会漏读。4. 扩展玩法MCP 服务器、本地模型与其他生态Skills 装多了之后你会发现单纯靠技能无法覆盖所有场景因为模型需要实时数据、需要操作外部系统。这个时候 MCP 就登场了。4.1 MCP给 Skills 补上“手”MCP 的全称是 Model Context Protocol它解决了“Claude 如何安全访问外部工具”的问题。比如你想让 Claude 直接查询数据库、读取本地文件、操作浏览器可以把这些能力封装成一个个 MCP 服务器。一个很常见的配置是用 npx 直接拉起社区封装好的 MCP 服务器{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] } } }把这段配置写到.claude/mcp.json或通过界面添加重新加载后Claude 就获得了对指定目录的文件读写能力。Skills 和 MCP 的搭配逻辑是Skill 告诉你“怎么做”MCP 帮你“能做到”。比如 Skill 是“写周报”MCP 是“读取 git 提交记录”两者一组合周报就能自动汇总这几天的代码变更。注意MCP 服务器权限范围要小。给了一个目录的读写权限就只会影响那个目录不要图省事给整个磁盘。你永远不知道模型在下一次组合调用时会用你的“手”去做什么。4.2 本地模型实验Claude Code 调用 LM Studio搜热词里有一条“claude code 调用 lmstudio 的本地模型”我也专门测过。实验动机通常是想离线跑、想省钱、想保护隐私或者单纯想验证某个 Skill 的逻辑而不消耗在线额度。LM Studio 提供 OpenAI 兼容的本地推理接口。把 Claude Code 的 base URL 环境变量指向本地地址可以让它把请求转发到本地模型。大致的思路是设置类似 ANTHROPIC_BASE_URL 的环境变量指向 LM Studio 的本地服务端口同时调整模型指向。但这里我必须说实话实测下来本地小参数模型在遵循 Skills 的复杂步骤方面明显弱于官方模型尤其是多步操作、多文件生成的场景经常中途跑偏。它目前更适合做流程验证、测试 SKILL.md 格式是否正确这类开发工作。指望本地开源模型完全替代在线模型当主力开发目前体验差距还很大。4.3 其他生态Codex Skills 和官方 GitHub Skills一类容易让你迷路的搜索结果是“codex skills”。OpenAI 的 Codex 也有类似的功能思路目录结构也是“说明文件脚本”但格式和命名不完全一样。如果你两个生态都玩可以把脚本部分复用但 SKILL.md 要按目标平台的规范改写。同一套思路换皮这事我干过不止一次。至于 GitHub Skills那是 GitHub 官方推出的交互式课程跟 Claude 的技能系统一点关系都没有。搜索时经常被带过去认一认路就好别浪费时间。5. 高频报错与排查记录整理 awesome-claude-skills 期间我几乎把社区里能踩的错都踩了一遍。有些是环境问题有些是配置问题还有的是网络问题。下面这张表总结了最常见的几类症状常见原因快速处理claude 命令找不到cmdlet 不识别npm 全局 bin 目录不在 PATH查 npm prefix把 bin 目录加进 PATHerror: claude native binary not installednpm 安装时 postinstall 没跑权限或 ignore-scripts 问题检查 npm 配置重装避免 sudo 全局安装API Error: Connection Dropped (ECONNRESET)网络到 API 的连接不稳定或本机安全软件拦截先 curl 探测连通性重试或换网络环境your organization has disabled claude subscription access企业账号策略限制了 Claude Code 访问联系组织管理员开通或使用个人账号按组织合规要求workspace requires the virtual machine platform on windowsWindows 的虚拟机平台功能未启用开启“虚拟机平台”功能并重启或安装 WSL25.1 几个让我印象深刻的排查过程native binary not installed 这个报错我最初以为是包损坏反复卸载重装都没用。最后发现是 npm 配置里 ignore-scripts 被某次操作打开了导致安装时的 postinstall 脚本根本没执行。检查npm config get ignore-scripts如果是 true关掉再重装。另外 Windows 上权限不够也容易触达这个错别用命令行乱改 npm 全局目录权限用正规的 nvm 或 nvm-windows 管理环境更稳。ECONNRESET 这类网络错误很多人第一步怀疑本机“网络工具”我建议先冷静做基础检查。用 curl 直接探测https://api.anthropic.com看能不能通如果命令本身能通而 Node 报断连重点排查防火墙、杀毒软件对 Node 进程的拦截。如果基础连通都不稳通常就是当前网络环境的问题换个合规稳定的网络环境再试。调整之后记得把失败的操作重放一遍不要只测一次就下结论。5.2 排查套路先最小复现再拆变量遇到复杂问题时我有个固定习惯建一个全新的空目录放一个只有 SKILL.md、没有任何脚本的最简 Skill然后在新会话里触发。如果最小复现成功了说明是你的项目配置、settings.json 或复杂 Skill 本身有问题。如果最小复现也失败那就是环境级问题跟具体技能无关。接着拆变量。先查版本claude --version和node -v看是不是版本差距过大导致行为不一致。再查环境变量有些配置只在当前终端生效新窗口就失效了所以要确保修改后用全新终端验证。最后看日志CLI 一般有日志输出里面会记录模型请求、工具调用的详细信息我排查 skills 未触发时基本都靠日志定位。6. 我整理这份清单踩过的坑与经验最后分享几个我沉淀下来的心得不一定写在哪份文档里但对实际使用很重要。6.1 怎么判断一个 Skill 值不值得收GitHub 星数是最不可靠的指标。我见过一些几百星的仓库description 写得极其含糊脚本里甚至藏着依赖系统不在本机的危险命令。我现在筛选 Skill 有一套自己的标准description 是否具体到“触发场景输出物”有没有 README 说明前置依赖脚本是否带基本的参数校验和日志输出最近半年有没有维护记录。如果四个条件里缺了两个以上哪怕是熟人推荐的我也先下载到隔离目录测试不会直接放进主目录。测试的方法很简单在空项目里跑一次看它输出的结果和说明文档是否一致。不一致的直接拉黑。6.2 使用 Skills 的正确姿势少而精装得越多越智能是个错觉。每个 Skill 的 description 都会被模型扫描如果量大且互相重叠模型会产生“选择困难”。我现在的习惯是维护一个“核心十个”只保留每周至少用两次的技能其余全部移出主目录放进归档目录。另外纠结“Skills 到底能不能帮我完成这个复杂任务”时我倾向于先问一句这个任务是不是高度重复且步骤明确如果是值得做 Skill如果不是也许你需要的是一段 Prompt 或者一个 MCP 工具。Skills 最适合的永远是“有标准答案的重复劳动”。6.3 给新手的第一个 Skill 建议如果这是你的第一个 Skill别一开始就搞复杂脚本。我见过太多人第一版就想要大而全结果一周都调试不完。先做一个最简单、只输出文本的 Skill比如 daily-log让它根据今天做的事整理成固定格式的日记。试试目录放哪里、SKILL.md 怎么写、模型什么时候触发把流程跑通再慢慢加脚本和模板。把这个最简骨架跑顺比一次写出一个完美 Skill 更有价值。
Claude Code Skills 完全指南：安装、编写与调试实战
前一阵我把散落在 GitHub、博客、产品文档和社区帖子里的 Claude Code Skills 翻了一个遍逐个在空目录里装、跑、排查最后整理成了一个名为 awesome-claude-skills 的清单仓库。起因很实际Claude Skills 这个概念火起来之后资料太散了。官方文档讲概念社区仓库给代码偶尔刷到几篇文章又各说各话新同学根本不知道从哪下手。这份清单沉淀下来之后我反而对“Skills 到底是什么、怎么装、怎么写、出问题怎么查”有了比之前更系统的理解。后面这些内容就是我整理和实操过程中反复验证过的做法。想给 Claude Code 加技能、想开发自己的第一个 Skill、或者只是好奇 Agent Skills 这个新玩意的都可以直接参考不用从头踩一遍我踩过的坑。1. 先搞清楚Claude Skills 到底是什么很多人一上来就搜“skills 推荐”“skills 下载平台”然后对着十几个 GitHub 仓库发呆。其实第一步不是找技能而是搞清楚 Skills 在 Claude 生态里的定位。简单说Agent Skills 是一组打包好的“技能目录”里面有一个说明文件 SKILL.md加上若干脚本、模板、参考资源。Claude 在对话中会先扫描这些技能根据描述判断“当前任务该不该用”一旦匹配就会按照你写的步骤和脚本去执行。这样设计有一个非常大的好处它把“怎么做好一件事”的经验固化下来了。平时我们让 Claude 干活要么靠一条写得很长的提示词要么靠模型自己临场发挥。有了 Skills你可以把团队里总结的代码审查规范、周报格式、前端组件封装套路全部变成一个可复用的目录。不同项目、不同人拿到同一个 Skill行为就是一致的。1.1 别把三个概念混在一起Skills、MCP、Prompt在搜“claude skills”的时候你会频繁看到 MCP、Prompt、Agent Skills 三个词一起出现新手很容易搞混。我用一个生活化的方式给你掰开。Prompt 就是口述需求。你直接说“帮我写个 Vue 组件”模型听懂了就写。特点是灵活但每次都要重新描述背景和规范还容易漏细节。MCP 是给模型“配手”的。它可以让 Claude 调用外部系统比如读取文件系统、操作数据库、调用浏览器 API。你可以把它理解成给实习生发钥匙、工牌和打印机让他能真正碰设备、办事。Skills 是给模型“配手册”的。里面写着做一件事的标准流程、注意事项、模板样例甚至还有现成脚本。相当于给实习生一本《项目操作 SOP》。一个完整的协作场景往往是用户提出需求Claude 读取自己的 Skills 手册通过 MCP 连接外部工具拿数据、改文件最后把结果生成出来。想通这一点你就不会把「装一个 MCP 服务器」和「装一个 Skill」当成同一件事了。1.2 扒开一个 Skill 看看它到底长什么样我最初看 Skills 文档的时候最困惑的是“它到底是一个文件还是一个文件夹”。答案是一个目录。一个标准 Skill 的结构大概长这样my-skill/ ├── SKILL.md # 技能说明Claude 最先读取这个文件 ├── scripts/ │ ├── generate_report.sh │ └── stats.py └── resources/ ├── template.md └── examples/ └── demo-output.mdSKILL.md 是整个技能的入口。它一般带一个 YAML 头部里面至少包含 name 和 description 两个字段正文则用自然语言描述触发场景、执行步骤、输入输出格式、注意事项。Claude 会在合适的时机扫描这些技能通过 description 判断当前任务是否匹配。scripts 和 resources 不是必须的但非常有用。脚本负责执行机械化操作比如批量重命名、生成统计表资源目录则放模板、示例文件让模型的输出风格保持一致。你可以这样理解SKILL.md 是大脑scripts 是手脚resources 是参考书。1.3 为什么要维护一份 awesome 清单Claude Skills 这个生态目前最大的问题是“没有统一包管理器”。MCP 好歹有 marketplace、有 npx 一键启动的模式而 Skills 基本还是靠 GitHub 仓库分发。社区里东西很多但命名不统一说明文档各异质量参差不齐。awesome-claude-skills 这类清单的价值就是帮你把“值得用的”和“看看就行的”分开。我整理时会按场景分类前端开发、代码审查、部署运维、数据分析、写作助手等。同时每个收录的技能我都会确认三件事描述写得好不好、脚本能不能跑、有没有明显的外部依赖。还有个小提醒GitHub 官方的“GitHub Skills”是交互式学习课程系统跟 Claude Agent Skills 完全不是一回事。不少人是搜到 GitHub Skills 误入的。另外还有个 Codex Skills那是 OpenAI 那边 Agent 生态的类似概念思路很像但目录格式和触发机制不一样别混用。2. 安装配置从零到能跑起来很多人卡在第一步不是技术不行而是不知道“装好之后到底把技能文件放哪”。实际上 Claude Code 的安装只是开始把 Skills 放进正确的位置才是能用的关键。2.1 安装 Claude Code 的完整步骤macOS / Windows / UbuntuClaude Code 本质上是一个 Node.js 包安装方式很简单。前提是你机器上有 Node.js 18 以上版本。我个人的建议是用 nvm 管理 Node因为不同项目可能要求不同版本nvm 切起来最省心。macOS 和 Linux 上命令都一样npm install -g anthropic-ai/claude-code装完直接运行claude --version能输出版本号就说明装好了。但很多 Windows 用户会遇到「claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称」的报错。这不是没装成功而是 npm 的全局 bin 目录不在 PATH 里。解决办法是先查一下全局路径npm config get prefix在 Windows 上这个路径通常是%APPDATA%\npm把该目录加到系统环境变量的 PATH然后重开一个终端就好了。macOS/Linux 上常见的是~/.npm-global或~/.local/bin。Ubuntu 用户容易踩的一个坑是用系统自带的 apt 装 Node版本往往比较旧导致 Claude Code 安装时报错或者启动异常。我建议在 Ubuntu 上先装 nvm再安装 Node 20 LTS之后用 npm 装 Claude Code。另外注意不要用 sudo 跑全局 npm install权限问题后期会暴露出一堆麻烦比如下面要说的 native binary 安装失败。VS Code 用户可以从插件市场搜 Claude Code 插件装完在侧边栏打开面板即可。桌面版的 Claude 也值得装因为部分操作可以脱离终端完成但它和 CLI 是否读取同一套 Skills 目录不同版本表现不一致。我的建议是先在 CLI 里验证 Skill 生效再切到桌面端或 IDE 观察否则你都不知道问题出在哪一环。2.2 把 skills 放进正确的位置个人级 vs 项目级Skills 放哪里决定了它的作用范围。个人用户级目录是~/.claude/skills/所有项目共用。你在里面建一个子目录比如~/.claude/skills/frontend-vue-beautifier/那么只要是在本机跑 Claude Code任何项目里都能识别到这个技能。适合放你自己总结的通用工作流比如写周报、写 commit message、代码风格审查这种跟项目无关的能力。项目级目录是项目根目录/.claude/skills/。这个目录可以随 git 一起提交团队所有人都能看到、用到。适合放跟当前业务强绑定的技能比如“某项目的数据表结构说明”“某规范下的组件生成器”。新成员把仓库一 clone技能就自动到位这个体验非常爽。放好之后怎么确认加载了不同版本的命令名有差异。我在某一版里用/skills能列出当前可用技能但有些版本插件不同入口也会变成/help里的某个子命令。最稳妥的办法是装完开一个新会话直接按技能描述的场景触发一次看模型有没有按预期行动。如果没反应先检查目录拼写再看 SKILL.md 的 description 是否写在标准字段里。注意Skill 目录名尽量用 kebab-case比如 frontend-vue-beautifier不要带版本号也不要用空格和中文。模型扫描文件系统时目录名、文件名都会进入上下文太乱会拖慢响应也会降低匹配精度。2.3 配置与权限settings.json、permissions 与环境变量Claude Code 的配置集中在.claude/settings.json里项目级和个人级都可以放。这里面的 permissions 配置非常关键它决定了 Claude 能执行哪些命令、读取哪些目录。一个常见的做法是允许 Skill 脚本所在的特定目录并放行可复现的安全命令。比如你的 Skill 要跑python3 scripts/format_data.py那就在 settings 里允许这个具体命令而不是允许通配所有 shell。这样平时不会被权限弹窗打断又不会把大门全敞开。团队协作时我建议把.claude/settings.json提交到仓库里让所有成员的行为一致。但千万不要把密钥、token 一类敏感信息放进去。settings 文件里的环境变量只放非秘密的配置真正敏感的走系统环境变量或者密钥管理器。3. 自己动手写一个 Skill以前端开发为例搜“skills 开发”“前端开发 skills”的人很多但真正能下笔的人很少。其实写 Skill 的门槛比想象中低我拿一个前端场景完整演示一遍你就知道套路了。3.1 怎么选题一件事一个 Skill写 Skill 之前先明确你高频重复的动作是什么。前端场景里很多人反馈最多的就是“要不要帮我生成一个 Vue3 组件”“帮我按项目风格写样式”“帮我审查一遍组件 props 设计”。这些都是非常典型的 Skill 选题因为需求明确、输出物固定、评审标准清楚。我强烈建议一个 Skill 只解决一件事。你看到社区里有些 Skills 号称“万能助手”什么都写实际上 model 触发时会犹豫不决也不知道该按哪套规范执行。写得窄description 精确模型反而更愿意调用。3.2 SKILL.md 结构与写法这是整个 Skill 的灵魂。我用一个实际可跑的示例--- name: frontend-vue3-component-generator description: 根据用户需求生成 Vue3 单文件组件包含 template、script setup、style并遵循项目内部代码风格。用户提到“新建组件、写组件、生成组件”或给出组件功能描述时使用。 --- # Vue3 组件生成器 - 仅在用户要求创建或重构 Vue3 组件时使用 - 输入组件名称、props、业务描述 - 输出一个 .vue 文件或将其写入 src/components/ 下 ## 步骤 1. 如果用户未说明组件用途先问清楚 props 与事件最多一轮 2. 创建 script setup langtsprops 使用 defineProps 定义 3. 模板使用语义化标签根节点用一个 div 包裹 4. 样式使用 scoped优先用 CSS 变量 5. 生成代码后标注使用示例等待用户确认 ## 示例 用户说“做一个商品卡片组件”要求显示图片、标题、价格、标签点击跳转详情。 输出组件名 ProductCardprops 包含 img、title、price、tags事件为 click。这里每个部分都有它的作用。name 是内部标识description 决定模型什么时候调用它所以宁可多写几个触发词也别写过于抽象的话。正文部分用命令式短句直接说明步骤不要写“我需要你……”这种废话。示例则是很好的对齐方式让模型知道用户口头描述会对应什么输出物。3.3 加脚本和模板让 Skill 真正“会动手”光靠 SKILL.md 写文字Skill 的力量还发挥不出来。真正提效的是脚本和模板。比如你要让 Skill 自动生成组件可以在 resources/ 下放一个 template.vue内含项目标准的写法。SKILL.md 里写明总是从 resources/template.vue 读取模板然后填充业务变量。这样无论模型怎么发挥输出风格都统一。再比如你想让 Claude 在生成组件后自动跑一遍 lint 校验可以把校验命令写进步骤里。脚本推荐用系统自带的语言比如 python3、node、bash避免装一堆依赖。脚本必须加 shebang并设置执行权限否则跨机器跑会莫名卡住。我在给 Skill 加脚本时有个习惯先在外面手动跑一遍脚本输入假数据确认它能独立正常工作再把它写进 SKILL.md。否则你不确定是脚本本身的问题还是 Claude 调用方式的问题排查起来会非常痛苦。3.4 调试技巧怎么判断 Claude 到底用了没有写完 Skill 之后第一件事不是去复杂项目里测而是新开一个会话直接说“帮我生成一个商品卡片组件”。接着观察输出。如果模型没有按你 Skill 的步骤走先不要怀疑模型智商大概率是 description 没写好。太窄、太泛、关键词不匹配都会导致不触发。我在 SKILL.md 里留过一个调试小技巧可以在步骤开头写一句“如果使用本技能请先回复使用技能 frontend-vue3-component-generator”。这样你一眼就能看出它到底调没调。如果触发了但输出格式不对多半是正文的描述不够具体。检查步骤里有没有明确指向 resources 下的模板文件脚本路径是否写对。我在调试时会把 SKILL.md 的文本量控制在几分钟内能读完太长的说明书模型也会漏读。4. 扩展玩法MCP 服务器、本地模型与其他生态Skills 装多了之后你会发现单纯靠技能无法覆盖所有场景因为模型需要实时数据、需要操作外部系统。这个时候 MCP 就登场了。4.1 MCP给 Skills 补上“手”MCP 的全称是 Model Context Protocol它解决了“Claude 如何安全访问外部工具”的问题。比如你想让 Claude 直接查询数据库、读取本地文件、操作浏览器可以把这些能力封装成一个个 MCP 服务器。一个很常见的配置是用 npx 直接拉起社区封装好的 MCP 服务器{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] } } }把这段配置写到.claude/mcp.json或通过界面添加重新加载后Claude 就获得了对指定目录的文件读写能力。Skills 和 MCP 的搭配逻辑是Skill 告诉你“怎么做”MCP 帮你“能做到”。比如 Skill 是“写周报”MCP 是“读取 git 提交记录”两者一组合周报就能自动汇总这几天的代码变更。注意MCP 服务器权限范围要小。给了一个目录的读写权限就只会影响那个目录不要图省事给整个磁盘。你永远不知道模型在下一次组合调用时会用你的“手”去做什么。4.2 本地模型实验Claude Code 调用 LM Studio搜热词里有一条“claude code 调用 lmstudio 的本地模型”我也专门测过。实验动机通常是想离线跑、想省钱、想保护隐私或者单纯想验证某个 Skill 的逻辑而不消耗在线额度。LM Studio 提供 OpenAI 兼容的本地推理接口。把 Claude Code 的 base URL 环境变量指向本地地址可以让它把请求转发到本地模型。大致的思路是设置类似 ANTHROPIC_BASE_URL 的环境变量指向 LM Studio 的本地服务端口同时调整模型指向。但这里我必须说实话实测下来本地小参数模型在遵循 Skills 的复杂步骤方面明显弱于官方模型尤其是多步操作、多文件生成的场景经常中途跑偏。它目前更适合做流程验证、测试 SKILL.md 格式是否正确这类开发工作。指望本地开源模型完全替代在线模型当主力开发目前体验差距还很大。4.3 其他生态Codex Skills 和官方 GitHub Skills一类容易让你迷路的搜索结果是“codex skills”。OpenAI 的 Codex 也有类似的功能思路目录结构也是“说明文件脚本”但格式和命名不完全一样。如果你两个生态都玩可以把脚本部分复用但 SKILL.md 要按目标平台的规范改写。同一套思路换皮这事我干过不止一次。至于 GitHub Skills那是 GitHub 官方推出的交互式课程跟 Claude 的技能系统一点关系都没有。搜索时经常被带过去认一认路就好别浪费时间。5. 高频报错与排查记录整理 awesome-claude-skills 期间我几乎把社区里能踩的错都踩了一遍。有些是环境问题有些是配置问题还有的是网络问题。下面这张表总结了最常见的几类症状常见原因快速处理claude 命令找不到cmdlet 不识别npm 全局 bin 目录不在 PATH查 npm prefix把 bin 目录加进 PATHerror: claude native binary not installednpm 安装时 postinstall 没跑权限或 ignore-scripts 问题检查 npm 配置重装避免 sudo 全局安装API Error: Connection Dropped (ECONNRESET)网络到 API 的连接不稳定或本机安全软件拦截先 curl 探测连通性重试或换网络环境your organization has disabled claude subscription access企业账号策略限制了 Claude Code 访问联系组织管理员开通或使用个人账号按组织合规要求workspace requires the virtual machine platform on windowsWindows 的虚拟机平台功能未启用开启“虚拟机平台”功能并重启或安装 WSL25.1 几个让我印象深刻的排查过程native binary not installed 这个报错我最初以为是包损坏反复卸载重装都没用。最后发现是 npm 配置里 ignore-scripts 被某次操作打开了导致安装时的 postinstall 脚本根本没执行。检查npm config get ignore-scripts如果是 true关掉再重装。另外 Windows 上权限不够也容易触达这个错别用命令行乱改 npm 全局目录权限用正规的 nvm 或 nvm-windows 管理环境更稳。ECONNRESET 这类网络错误很多人第一步怀疑本机“网络工具”我建议先冷静做基础检查。用 curl 直接探测https://api.anthropic.com看能不能通如果命令本身能通而 Node 报断连重点排查防火墙、杀毒软件对 Node 进程的拦截。如果基础连通都不稳通常就是当前网络环境的问题换个合规稳定的网络环境再试。调整之后记得把失败的操作重放一遍不要只测一次就下结论。5.2 排查套路先最小复现再拆变量遇到复杂问题时我有个固定习惯建一个全新的空目录放一个只有 SKILL.md、没有任何脚本的最简 Skill然后在新会话里触发。如果最小复现成功了说明是你的项目配置、settings.json 或复杂 Skill 本身有问题。如果最小复现也失败那就是环境级问题跟具体技能无关。接着拆变量。先查版本claude --version和node -v看是不是版本差距过大导致行为不一致。再查环境变量有些配置只在当前终端生效新窗口就失效了所以要确保修改后用全新终端验证。最后看日志CLI 一般有日志输出里面会记录模型请求、工具调用的详细信息我排查 skills 未触发时基本都靠日志定位。6. 我整理这份清单踩过的坑与经验最后分享几个我沉淀下来的心得不一定写在哪份文档里但对实际使用很重要。6.1 怎么判断一个 Skill 值不值得收GitHub 星数是最不可靠的指标。我见过一些几百星的仓库description 写得极其含糊脚本里甚至藏着依赖系统不在本机的危险命令。我现在筛选 Skill 有一套自己的标准description 是否具体到“触发场景输出物”有没有 README 说明前置依赖脚本是否带基本的参数校验和日志输出最近半年有没有维护记录。如果四个条件里缺了两个以上哪怕是熟人推荐的我也先下载到隔离目录测试不会直接放进主目录。测试的方法很简单在空项目里跑一次看它输出的结果和说明文档是否一致。不一致的直接拉黑。6.2 使用 Skills 的正确姿势少而精装得越多越智能是个错觉。每个 Skill 的 description 都会被模型扫描如果量大且互相重叠模型会产生“选择困难”。我现在的习惯是维护一个“核心十个”只保留每周至少用两次的技能其余全部移出主目录放进归档目录。另外纠结“Skills 到底能不能帮我完成这个复杂任务”时我倾向于先问一句这个任务是不是高度重复且步骤明确如果是值得做 Skill如果不是也许你需要的是一段 Prompt 或者一个 MCP 工具。Skills 最适合的永远是“有标准答案的重复劳动”。6.3 给新手的第一个 Skill 建议如果这是你的第一个 Skill别一开始就搞复杂脚本。我见过太多人第一版就想要大而全结果一周都调试不完。先做一个最简单、只输出文本的 Skill比如 daily-log让它根据今天做的事整理成固定格式的日记。试试目录放哪里、SKILL.md 怎么写、模型什么时候触发把流程跑通再慢慢加脚本和模板。把这个最简骨架跑顺比一次写出一个完美 Skill 更有价值。