最早看到 Claude Skills 这个功能时我心想这不就是把一堆提示词放进一个目录吗有什么好稀奇的。直到我把 awesome-claude-skills 这个精选清单从头到尾翻了一遍又把里面几类高赞技能逐个装进 Claude Code 实际跑了一遍才意识到自己之前完全低估了这套设计。如果你已经在用 Claude Code却总觉得它差点意思或者你看到各种 Skill 仓库但不知道哪些值得装、装了怎么用这篇内容应该能帮你少走不少弯路。我会从概念拆解开始讲到翻清单时怎么挑技能、Windows 下常见的安装报错怎么排查最后带手写一个 Skill 的完整过程以及本地模型、Codex Skills 互通这些进阶玩法。1. Skill是工作手册而不是插件先把这个概念掰清楚很多第一次接触 Skill 的人包括我自己都会下意识拿它跟 MCPModel Context Protocol对比觉得这不就是给 Claude 装插件吗。实际用下来两者逻辑完全不同。MCP 更像给 Claude 装了一双手让它能调用外部 API、读写数据库、操作浏览器而 Skill 是给 Claude 装了一本工作手册让它遇到某一类任务时知道一套成熟的做法、步骤和注意事项。一个是执行能力一个是业务素养。1.1 一个标准Skill的目录长相与SKILL.md一个标准的 Claude Skill 通常长这样my-skill/ ├── SKILL.md └── references/ └── sample-output.md核心就是根目录下的 SKILL.md。这个文件前面有一段 YAML 格式的 frontmatter至少包含name和description两个字段后面是正文正文就是你希望 Claude 在处理这类任务时遵循的操作流程。--- name: frontend-repo-reviewer description: 当需要审查前端项目目录结构、评估组件拆分合理性、查找重复代码时使用。适合 React/Vue 项目不适合后端服务代码审查。 --- # 前端仓库审查 ## 适用场景 ...这里有个容易被忽略的细节SKILL.md 的正文并不会一直放在 Claude 的上下文里只有在模型判断当前任务匹配这个 Skill 时才会把 SKILL.md 全文加载进来。所以正文可以写得非常详细不用像系统提示词那样担心占用上下文窗口。这也是 Skill 跟把一大段提示词塞进项目说明文档最大的区别。1.2 它是怎么被召唤出来的语义匹配与渐进式披露那么 Claude 怎么知道什么时候该用一个 Skill靠的就是 frontmatter 里的description。Claude Code 启动时会扫描所有已安装的 Skill把每个 Skill 的名字和描述做成一个索引在对话过程中根据用户请求做语义匹配。一旦觉得某个 Skill 可能相关就把它的全文作为额外的上下文注入让它开始按手册办事。这种设计叫渐进式披露progressive disclosure。它的核心好处是你可以在一个 Skill 里写进大量的分支处理逻辑、边界情况和检查清单但平时这些内容不会占用任何 token只有真正被触发时才加载。我第一次看到一个处理 PDF 报告的 Skill 正文写了三百多行决策树时才明白官方为什么推荐这种写法——它实际上是把一本操作手册嵌进了模型的工作记忆里而代价几乎为零。1.3 和MCP、自定义指令放在一起看各自管哪一段把三样东西放在一起看会更清楚机制本质解决什么问题类比MCP Server外部工具集合让 Claude 能执行动作查天气、跑 SQL、读写文件给 Claude 装上手Skill提示词流程参考资料让 Claude 知道某类任务的标准做法给 Claude 装上大脑的业务知识区自定义指令全局行为偏好设定语气、输出格式、回答风格给 Claude 定职场规矩一句话总结我现在的理解MCP 决定 Claude 能做什么Skill 决定 Claude 把事情做成什么样自定义指令决定 Claude 以什么风格跟你共事。三者可以配合使用并不冲突。比如一个周报生成Skill 内部可以调用一个读取项目管理的 MCP 工具来拉数据再按 Skill 里定义的模板结构输出周报。2. 翻一遍awesome-claude-skills最值得优先试用的技能方向awesome 类精选清单的价值不在于收藏而在于它把人肉筛选过的资源按主题分类好了能大幅压缩你从零摸索的时间。我按自己的实际使用频率把高赞技能分成了几个方向新手可以直接从这些方向入手体验。2.1 前端开发和页面还原这是我最先装的技能类型也是社区里数量最多、更新最快的方向之一。典型场景是给我一张设计稿截图把它还原成可运行的页面。一个好的前端 Skill 不会只给一句生成 HTML它会要求你先确认目标框架React/Vue/原生、需不需要 Tailwind、响应式断点怎么处理、图片资源从哪来然后按先搭结构、再写样式、最后补交互的顺序产出代码。我实测下来的感受是这类 Skill 最明显的提升是稳定了输出质量。没有 Skill 时Claude 每次生成的前端代码风格都像开盲盒有时用 Tailwind 有时写原生 CSS挂上 Skill 之后它会严格按照技能里约定的组件拆分方式和命名规范走代码风格统一了很多review 成本直线下降。2.2 论文写作与长文档处理社区里流传较广的是论文润色和学术写作方向的技能。这类 Skill 往往内置了完整的审稿人视角先检查逻辑链是否有断裂再查证据引用是否充分最后统一术语和格式。跟普通的一键润色提示词相比这类技能的优势在分阶段处理——它会把阅读全文、列问题清单、逐段修改、生成修改说明拆成独立步骤每一步都在上下文里有明确产出。有意思的是很多这类 Skill 的 SKILL.md 正文会刻意要求模型在修改前先复述一遍原文论点防止润色变重写。这种细节靠临时写提示词很容易漏掉但作为成体系的 Skill 却被保留下来了。写论文比较多的朋友花十分钟装一个这类技能回报率很高。2.3 数据清洗与本地文件批处理数据处理类技能适合经常跟 CSV、Excel、JSON 日志打交道的人。好的数据类 Skill 会规定好操作的顺序先抽样预览、再确认字段含义、接着写清洗脚本、最后输出数据质量报告。它不会上来就乱跑代码而是先把每一列的含义让用户确认一遍避免把手机号当成数字做加减乘除。这类技能还经常配套一批 references 目录里的实用脚本片段比如 pandas 处理日期格式、正则提取非标准文本之类的工具函数。Claude 触发技能后可以直接引用这些片段比自己现写要可靠不少。2.4 让Agent自己测自己调试类技能Agent 测试和技能自测是最近特别火的方向。原理很简单大多数 Skill 你装完没法立刻知道它效果好不好调试类技能就是一套专门用来验证 Claude 行为的流程通常包含怎么设计测试样例、怎么断言输出质量、怎么定位是提示词问题还是模型能力问题等环节。我给自己的 Skill 做回归测试时也会参考这类技能的思路把一批固定输入放在 tests 目录里每次改完 SKILL.md 就跑一遍看输出有没有退化。这听起来有点重但对于会长期维护的 Skill 来说这可能是性价比最高的保障。2.5 快速筛选Skill的四个硬指标清单里项目太多不可能全部装一遍。我现在筛选一个 Skill 时只看四个维度供你参考筛选维度好信号危险信号description 质量写清了适用场景和排除场景只有一句泛泛的help with everything正文结构有步骤、有分支、有检查清单只有一段话没有过程拆分references 目录有示例输出或脚本片段只有一个孤零零的 SKILL.md更新状态近期还有提交半年以上没动且依赖旧版本特性这四个维度能过滤掉大多数看起来不错但实际用不起来的技能。尤其是 description写得太宽泛的技能在运行时经常误触发反而干扰正常对话。3. 跑通一个Skill前必须弄清的四个关键问题从清单里下载技能和把它真正跑起来之间还有几个容易踩坑的环节。我见过不少人栽在目录放错、描述词写太烂这些问题上这里逐个说清楚。3.1 放对目录个人级还是项目级Claude Code 读取 Skill 有两个位置分别对应不同的生效范围个人级目录~/.claude/skills对所有项目生效项目级目录.claude/skills只对当前项目生效如果你希望某个技能成为通用能力比如代码审查、提交信息规范放个人级目录。如果你希望某个技能只在特定项目里出现比如该项目的专属部署流程、数据字典放项目级目录。两者同名时项目级会覆盖个人级。一个常见误区是把下载的 Skill 整个文件夹解压后直接丢进~/.claude/skills但里面多套了一层目录变成了~/.claude/skills/my-skill/SKILL.md与~/.claude/skills/my-skill的嵌套关系。虽然多一层目录一般也能识别但如果你看到某个技能始终不被触发先检查目录层级。标准结构必须是skills 目录下直接是技能名文件夹技能名文件夹里直接是 SKILL.md。3.2 description就是召唤咒语很多新手把大量精力花在写正文上却随便填了一个 description。这是典型的舍本逐末。模型判断是否加载一个 Skill几乎只看description和name的语义匹配度。一个糟糕的 description 会导致两种后果要么该触发时不触发要么不该触发时乱触发。我建议 description 采用何时用 为何用 何时不用的句式。例如description: 当需要将网页设计稿截图转换为响应式前端代码时使用。支持 React、Vue、原生 HTML。适合从 Figma 截图、设计稿图片、现有网站截图开始的项目。不适合用于已经存在完整代码库的增量修改场景。这样写模型能明确知道什么场景点火、什么场景熄火误触发率会明显下降。3.3 权限边界让Claude动手之前先审这几条Skill 本身不直接具备执行能力真正执行命令的是 Claude Code。所以一个 Skill 里往往会写运行以下命令修改以下文件调用以下函数。装任何第三方的 Skill 之前我建议你先打开 SKILL.md 全文逐条检查它指示模型做什么操作是否执行网络请求目标域名是什么是否读写文件会改哪些目录是否安装依赖是否会执行npm install、pip install等命令是否有关键词值得警惕比如把密钥、环境变量发送到外部接口这个习惯不用花太多时间但能避开大多数粗制滥造甚至恶意的技能。Claude Code 对命令执行是有确认机制的但长期使用中你很容易顺手确认所以源头审核比执行时拦截更重要。3.4 技能冲突、重名与干净卸载如果你装了多个功能相似的 Skill可能会发现某个技能始终不被加载或者被另一个覆盖。这多半是重名问题。Claude Code 在加载 Skill 时遇到重名会按项目级优先于个人级、目录名字典序靠前的优先这类规则取舍。我自己的做法是在技能目录名前加命名空间比如fe-page-crafter、fe-component-auditor降低冲突概率。卸载更简单把对应目录删掉或改名即可。但注意如果你用的是 git 管理的技能集合删除后要先同步到远程否则换个机器又会拉回来看起来像删不掉。4. Windows下的高频报错从提示信息逆推排查步骤我在 Windows 上配置 Claude Code 和 Skills 时踩过的坑基本都能从热搜词里看到影子。这里把几个最高频的问题按报错原文 排查链路的方式整理出来。4.1 workspace requires the virtual machine platform先查Windows虚拟化基础在 Windows 上启动 Claude Code 的某些工作区功能时报错会直接提示需要虚拟机平台。这个报错不算 Claude Code 本身的问题而是 Windows 侧的功能开关缺失。先说结论打开控制面板-程序-启用或关闭 Windows 功能勾选虚拟机平台和适用于 Linux 的 Windows 子系统重启电脑大概率能解决。如果已经勾选仍然报错就需要往下排查一层。这个报错在虚拟机里跑 Windows 时尤其常见因为 VMware/VirtualBox 默认不开启嵌套虚拟化需要在虚拟机设置里把 CPU 的虚拟化暴露给客户机操作系统。另外Windows 的 VBS基于虚拟化的安全有时也会干扰出现冲突时可以临时把内存完整性关闭再试。把这几层逐个确认一遍基本能定位到具体瓶颈。4.2 无法将claude识别为cmdletPATH链路排查这是 npm 全局安装后最常见的问题。报错本身说得很清楚终端找不到 claude 命令的路径。一般按三个步骤就能解决第一步执行npm ls -g anthropic-ai/claude-code确认安装确实成功了。如果这里显示没有安装问题在安装环节如果显示了版本号那就是 PATH 没配好。第二步找到 npm 全局目录。执行npm prefix -gWindows 下通常是C:\Users\你的用户名\AppData\Roaming\npm。把目录确认下来。第三步把这个目录加到用户环境变量 PATH 里。加完之后不要直接开原来的终端它缓存的 PATH 没刷新新开一个终端再执行claude --version。还有一个常被遗漏的点某些 Windows 终端工具需要以管理员身份运行时才会加载系统级 PATH如果你平时用普通模式没问题、某一天突然报无法识别先怀疑是不是终端环境变了而不是重装 Claude Code。4.3 Connection dropped (ECONNRESET)网络层问题怎么缩小范围ECONNRESET这类报错本质是 TCP 连接被对端重置但对端到底是谁需要一步步缩小范围。我自己习惯的排查顺序是先确认是不是偶发直接重试一次有些超时重试就好了。接着检查目标地址是否可达。如果用了自定义 API Base URL先确认这个地址在当前网络环境下确实能访问排除本地服务没启动的可能。再看本地是否有安全软件或代理工具在拦截连接这类软件经常会对不认识的进程做 SSL 拦截造成连接重置。排除上面这些之后可以试着在终端里设置更宽松的超时环境变量或者换一个网络环境比如从公司 WiFi 换到手机热点做对照测试。如果换网络后问题消失基本可以断定问题在源网络环境本身而不是 Claude Code 配置的问题。4.4 一个通用验证动作确认Skill真的被加载装好了 Skill怎么知道它真的在生效比较直观的方法是直接在对话里问 Claude你现在有哪些可用的技能如果配置成功它会列出当前上下文可见的 Skill 列表。另外新版 Claude Code 在会话启动时也会显示加载了哪些技能启动横幅里能看到类似 Loaded N skills 的字样。如果启动时没有加载最常见的原因就是目录层级不对或者 SKILL.md 里的 frontmatter 格式写错比如少了一个冒号。可以把 SKILL.md 用本地 YAML 解析器跑一遍语法错误会直接暴露出来。记住一个原则先确认文件能被识别再优化触发效果不要跳过第一步直接调描述。5. 自己写一个Skill从零拆解网页截图转前端代码看再多的开源技能都不如自己动手写一个来得印象深刻。这里我以网页截图转前端代码为例把整个设计过程拆给大家看。5.1 目录与SKILL.md的骨架先建目录fe-screenshot-to-code/ ├── SKILL.md └── references/ ├── react-tailwind-template.md └── test-cases.mdSKILL.md 的骨架如下--- name: fe-screenshot-to-code description: 当用户提供网页截图或设计稿图片希望生成可运行的前端页面时使用。支持 React、Vue、原生 HTML 三种技术栈。适合新页面的整体还原不适合已有项目的小改动。 --- # 网页截图转前端代码 ## 初始信息收集 - 确认目标技术栈React / Vue / 原生 HTML - 确认样式方案Tailwind CSS / CSS Modules / 纯 CSS - 确认图片来源和尺寸 ## 生成步骤 1. 分析截图布局输出线框结构 2. 按组件粒度拆分页面 3. 逐组件生成代码 4. 整体拼装与响应式适配 ## 完成前检查 - [ ] 图片是否懒加载 - [ ] 关键按钮是否有 hover 效果 - [ ] 语义化标签是否合理 ...骨架本身并不复杂关键在于正文的组织方式。写的时候要想象 Claude 正在执行一个完整的工作流每个步骤它都需要明确的信息输入和产出。5.2 description怎么写才不会乱触发我在前面反复强调 description 的重要性这里直接给一个反例和正例对比。反例description: 将截图转换为代码。这句话太短模型无法判断使用场景。比如用户只是贴了张截图想问这个页面的配色是什么它也可能触发技能浪费上下文去走一套完整流程。正例description: 当用户提供网页截图、设计稿图片或 UI 线框图并要求生成完整的、可运行的前端页面时使用。支持 React、Vue 和原生 HTML使用 Tailwind CSS 时效果最佳。如果用户只是询问图片内容、配色分析不需要生成代码则不要使用本技能。正例里明确说了什么时候用和什么时候不用模型做语义匹配时的判断质量会好很多。5.3 用渐进式披露组织执行流程写正文时最需要注意的就是渐进式披露。所谓渐进式披露就是把最核心、最高频的信息放在最前面把分支细节、调试方法放在靠后的位置。这样即使模型的上下文有限它读到前面部分就能开始干活后面的细节按需取用。我通常把正文分成三层第一层是初始信息收集必须最先读。技术栈、样式方案这些不确认清楚后面全是白干。第二层是主流程拆成具体的步骤每一步都要有产出物。比如分析布局的产出是线框结构按组件拆分的产出是组件清单。第三层是分支处理比如遇到表格怎么处理遇到复杂动画怎么降级。这一层平时不一定会被读入但遇到对应情况时 Claude 会继续往下读找到解决方案。5.4 挂载参考资料与示例输出references 目录的价值在于给模型提供标准答案参考。比如我在这个技能里放了一个react-tailwind-template.md里面是一段完整的、符合团队规范的 React 组件代码。模型生成页面时会参考这个模板的写法而不是自由发挥。另一个很有用的文件是test-cases.md里面记录了一批测试截图对应的预期输出。每次我改完 SKILL.md就跑一遍测试用例看输出和预期是否一致。这个习惯能防止改一处流程坏了三处输出的回归问题。写参考文件时尽量让示例贴近真实项目的复杂度。只有一句Hello World的示例没有参考价值模型无法从里面推断出组件拆分、错误处理、样式约定这些关键信息。5.5 测试这个Skill的两种姿势测试一个 Skill我建议先做冒烟测试再做专项测试。冒烟测试最简单在 Claude Code 对话里丢入一个截图直接说按你的技能把这个页面实现出来观察它是否主动加载了 Skill、是否执行了 SKILL.md 里定义的步骤。专项测试则要刻意制造边界情况比如给一个几乎没有视觉层次的长列表页面看它会不会忽略分组给一个深色模式的截图看它是否遵守对比度要求。这些边界情况往往才是 Skill 真正拉开差距的地方。6. 更进阶的玩法本地模型、Codex互通与重量级技能合集把基础概念和写法搞定之后就可以往更远的场景看了。6.1 让Claude Code指向LM Studio的本地模型不少人对用 Claude Code 接本地模型感兴趣主要动机是省 token、离线可用、或者数据不出本机。社区里常用的方式是让 Claude Code 把请求指向本地运行的 LM Studio 服务通过环境变量改 API 地址export ANTHROPIC_BASE_URLhttp://localhost:1234 export ANTHROPIC_API_KEYlm-studioLM Studio 本地服务需要开启兼容 Anthropic API 格式的选项不同版本界面有差异但都在 Server 面板的API 类型里可以切换。如果你的 Claude Code 版本对协议要求较严也可以用兼容层把 Anthropic 格式转成 OpenAI 格式再指向本地模型。需要心中有数的是本地模型的能力上限与 Claude 官方模型还有差距复杂指令的跟随能力尤其明显。Skills 里的渐进式披露设计对本地小模型反而很友好——因为小模型上下文更小按需加载手册的方式能帮它节省很多注意力。我实测下来本地模型跑简单的数据清洗技能效果尚可跑前端整页还原就有些吃力了。6.2 Codex Skills和Claude Skills能互相迁吗Codex 是 OpenAI 的命令行编程工具它同样引入了基于 SKILL.md 的技能机制。好消息是两者在格式层面高度兼容同样是 YAML frontmatter 加 Markdown 正文同样是放 skills 目录下很多 Claude 的 Skill 拿到 Codex 里改一下命名约定就能直接用。我迁移过几个技能过程基本是这三步目录从.claude/skills复制到.codex/skills检查 SKILL.md 里是否有针对 Claude 的特殊措辞比如作为 Claude这类字样改成中性表达逐个对话验证触发效果因为两家模型的指令跟随能力有差异同一个描述在 Codex 上的触发率可能不同反过来Codex 生态里的一些好技能也可以迁到 Claude 上。这种互通大大提升了技能资产的复用价值写的时候尽量不要在正文里绑定特定产品可移植性会更好。6.3 superpower skills这类大合集给我的三点编排启发Superpowers 是社区里非常出名的一套 Claude Code 技能合集里面包含上百个技能。扒完这类大合集我最大的收获不是其中某一个技能多好用而是它体现的编排思路。第一技能粒度要小而专与其做一个前端专家大杂烩不如拆成截图转页面组件审查样式统一三个独立技能触发更精准。第二技能之间可以互相调用一个技能的执行过程中可以触发另一个技能相当于把复杂工作拆成了流水线。第三文件结构本身就是文档好的技能集合看目录结构就能大概理解作者的思路这是一种隐形的可维护性。我现在管理自己的技能集合时也完全借鉴了这套思路并且用 git 做版本管理。每次改动 SKILL.md 都提交一次配合测试用例做回归之后可以随时回退到好用的版本。回头看Claude Skills 最打动我的不是提示词工程的技术含量而是它把经验沉淀变成了一个可积累、可复用、可通过清单传播的载体。我在实际使用中最深的一点体会是不要把技能当成一个一次性配置把它当成一个需要持续维护的代码库。你每次在对话里觉得Claude 又没按流程走都可能是 SKILL.md 写得不到位值得回去改一版而不是硬凑合。最后再分享一个小技巧给你的技能集合建一个统一的 README 文件记录每个技能的触发场景和依赖关系三个月后你会感谢当时的自己。
