前一阵，我把散落在 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.md

SKILL.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 / Ubuntu）

Claude 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 lang="ts">`，props 使用 defineProps 定义 3. 模板使用语义化标签，根节点用一个 div 包裹 4. 样式使用 scoped，优先用 CSS 变量 5. 生成代码后，标注使用示例，等待用户确认 ## 示例 用户说“做一个商品卡片组件”，要求显示图片、标题、价格、标签，点击跳转详情。 输出组件名 ProductCard，props 包含 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 期间，我几乎把社区里能踩的错都踩了一遍。有些是环境问题，有些是配置问题，还有的是网络问题。下面这张表总结了最常见的几类：

5.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 更有价值。