去年年底到今年年初AI 编程圈子里最热的关键词已经从“补全代码”悄悄变成了“Agent 干活”。Claude Code 算是我用得最顺手的一个终端 Agent而真正让它从“一个能聊天的命令行工具”变成“一个能稳定交付任务的同事”的是 Skills 这套机制。这篇文章我想把 Claude 的 Skills 从概念到实操到怎么自己写完整梳理一遍。先说这东西解决了什么问题。用过 Claude Code 的人应该都有体会如果只是让它改个 bug、写个正则直接聊就行。但一旦你让它“按项目规范写一个带完整测试的前端组件”它就开始自由发挥——目录乱建、代码风格漂移、前后端约定没对齐。Skills 做的事情就是把这些“约定”“流程”“知识库”打包成一套可复用的指令包让 Agent 在接到任务时先加载对应技能再按里面的规范和步骤干活。你可以把它理解成给大模型插上了“岗位说明书”。这篇文章适合三类人刚听到 Claude Skills 想搞清楚它和 Prompt、MCP 区别的新手已经在用 Claude Code 但总觉得 Agent 不听话、想通过 Skills 提升稳定性的开发者以及想自己封装专属技能、甚至对外发布的人。我会把安装、配置、排错、开发、测评一整条链路都讲透所有内容都基于我自己在真实项目里跑过的流程不是文档搬运。1. 先搞清楚Claude Skills 到底是什么1.1 Skills 与 Prompt、MCP 的区别很多人第一次接触 Skills第一反应是“这不就是个加强版 Prompt 吗”我在团队内部做分享时发现即便是写过不少 Prompt 的人也会把这三者搞混。我自己的理解是这样的Prompt 是“一次性对话上下文”。你把它贴在对话里告诉模型当前任务、约束、输出格式。它的特点是临时性换个会话就要重新贴而且没有结构化的“加载”逻辑。MCPModel Context Protocol是“给 Agent 接外部工具和数据的管道”。比如你要让 Claude Code 查数据库、读 GitHub Issue、操作浏览器这些都要通过 MCP Server 暴露成工具。Skills 则处于两者中间它不是即时对话的话术也不是实时的工具管道而是一组可复用的指令、流程、规范、示例文件的集合。当用户的任务匹配到某个 Skill 时Agent 会把该 Skill 目录下的内容注入到上下文里通常是说明文件加参考示例让 Agent 在后续执行中遵循这套“剧本”。可以这么类比Prompt 是你随口交代的一句话MCP 是给工人提供电钻、扳手等工具Skills 则是给工人一本 SOP 手册。你当然可以把 SOP 直接念给工人听在 Prompt 里写全但每次都要念一遍很累而且容易漏。Skills 就是把 SOP 归档到固定位置需要时自动调取。1.2 为什么说 Skills 是 Agent 时代的“插件思维”Claude Skills 的目录结构是固定的一个.claude/skills目录下面每个技能一个子目录目录里必须有SKILL.md描述文件可以附带脚本、模板、示例代码。这个设计本身没多复杂但它的意义在于把“知识”和“执行”分离了。传统 Prompt 工程里知识是写死在对话里的换个项目就得重写。Skills 则像是 IDE 时代的插件——你不用每次装完 VSCode 都重新配一遍快捷键装个插件就好。Skill 也一样团队里抽一套“前端组件开发规范”A 项目用B 项目也能用新人入职把 skills 仓库 clone 下来Claude Code 立刻就是一个“懂你们团队规范的老同事”。有人可能会问那我在 system prompt 里把这些规范写死不也一样不一样。系统 Prompt 是所有会话、所有任务都加载的内容一多模型注意力会被稀释无关任务也会被干扰。Skills 则是有选择地加载Agent 会先理解用户意图再决定该激活哪个技能包。这种“按需注入”的机制比把所有内容都塞进上下文要省 token效果也更稳。2. 五分钟装好环境Claude Code 安装与配置2.1 从零安装npm 全局安装与登录Claude Skills 目前不是独立产品它是 Claude Code 的一个功能模块。所以第一步还是先把 Claude Code 跑起来。安装方式很简单前提是你本机装了 Node.js 18 以上的版本。npm install -g anthropic-ai/claude-code装完以后终端执行claudeclaude首次运行会引导你登录 Anthropic 账号把终端里显示的链接复制到浏览器完成授权后回到终端回车即可。这里提醒一下登录过程如果是在服务器或者远程开发机上要注意终端回显的 URL 是否被包裹了换行复制的时候尽量选中完整的链接我见过不少人是在这一步卡住的。装完后确认版本claude --version如果输出类似1.0.x的版本号说明安装成功。这里我再多一句我建议保持 Claude Code 更新到比较新的版本因为 Skills 功能在早期版本里还很不稳定claude update或者在装完依赖后重启终端都是值得做的操作。2.2 VSCode 集成与桌面端的取舍除了纯终端Claude Code 也可以作为 VSCode 的插件使用。直接在 VSCode 扩展市场搜 “Claude Code” 安装即可。装完后侧边栏会多出对话面板你依然是在终端里操作但可以同步把当前打开的代码文件作为上下文。那claude desktop是怎么回事其实 Claude Desktop 是 Anthropic 出的桌面客户端它和 Claude Code 并不完全是一回事。Claude Desktop 主要侧重大模型对话未来也会支持更多的 Agent 能力和 mcp 配置。但如果你要做代码、做工程目前我仍然建议以 Claude Code 为主毕竟它的 Skill 机制和文件系统交互更成熟。我自己目前的搭配是VSCode 里开终端跑 Claude Code同时用 Claude Desktop 做日常问答和长文档分析。两边账号是同一个互不冲突。3. 核心实操安装与验证你的第一个 Skills3.1 用 superpowers 快速上手术语叫 Skills但真正让这个概念出圈的是一个叫superpowers的开源项目作者是 Jesse Vincentobra 主导。它把软件工程里的各种工作流封装成了几十个 Skill包括编写规格说明、TDD 开发、代码审查、缺陷修复、与 AI 协作做架构设计等。安装方式直接看它的 README简单说就是 clone 项目然后把里面的 skills 目录复制到你的全局目录或者项目目录git clone https://github.com/obra/superpowers.git mkdir -p ~/.claude/skills cp -r superpowers/skills/* ~/.claude/skills/复制完成后你在 Claude Code 里可以执行claude 请列出你当前可用的所有 skills如果 Claude 的回答里出现了 superpowers 相关的技能列表说明加载成功。这里我想特别强调一下“全局”和“项目级”两个概念的差异。放在~/.claude/skillsmacOS/Linux或%USERPROFILE%\.claude\skillsWindows下的是全局 Skills所有项目都能用放在项目根目录.claude/skills下的是项目级 Skills只有那个仓库能用。合理的做法是个人的编码习惯、通用规范放全局某个项目特有的约定、流程放项目目录里还可以纳入 git 版本管理。3.2 自己动手装一个裁剪版 Skill如果 clone 一整个 superpowers 对你来说太重完全可以自己写一个最小的 Skill 先跑起来。我举个例子做一个“commit message 规范生成”的技能。在项目根目录创建以下结构.claude/skills/commit-style/ └── SKILL.mdSKILL.md的内容写成这样--- name: commit-style description: 根据当前仓库的 git diff 生成符合团队规范的提交信息。当用户要求“写提交信息”“commit message”“整理提交说明”时使用该技能。 --- # Commit Message 规范 1. 格式type(scope): subject 2. type 取值feat新功能、fix修复、docs文档、refactor重构、test测试、chore构建/工具 3. subject 不超过 50 个字符使用祈使句首字母小写 4. 如果 diff 涉及多个模块拆成多个 commit message 候选不要合并保存后回到 Claude Code修改一个文件然后输入“帮我写个 commit message”。正常情况下 Claude 会加载这个 Skill然后严格按规范生成提交信息。这段体验非常关键因为它一下子让你理解 Skills 的本质Claude Code 会把SKILL.md的内容注入到上下文然后按里面的指令执行。这才是“技能”不是一次性对话。3.3 VSCode 配置 Claude Code 的注意点如果你打算把 Claude Code 深度绑定在 VSCode 里我建议在 VSCode 的配置文件里设置一下全局快捷键和默认工作目录。这样就不用每次手动切到终端再输入路径。比较常见的做法是在 VSCode 的settings.json里面配置claude-code.autoRunOnSave之类的选项不过不同插件版本配置项可能不同。最稳妥的方式还是装完插件后在插件详情页把键盘快捷键绑定到claude命令上让整个交互路径最短化。另外有一点务必留意Claude Code 的会话记录和配置会写入用户目录里的.claude文件夹里面有settings.json可以配权限、ama 模式开关。如果你的系统里有多个开发者账号建议把全局 Skills 和全局配置放在一个单独的配置文件管理仓库里用dotfiles的方式维护换新机器可以一键恢复。4. 常见报错与解决实录4.1 启动失败Claude Code 在 Windows 上要求启用虚拟机平台这应该是近期 Windows 用户碰到的头号问题。表现为启动或执行某些命令时报错Claudes workspace requires the Virtual Machine Platform on Windows. Enable it and try again.或者Failed to start Claudes workspace原因是 Claude Code 为了在 Windows 上实现隔离的沙箱工作区依赖 WSLWindows Subsystem for Linux里的虚拟机平台功能。如果你只装了 WSL 1、或者根本没启用“虚拟机平台”这个可选功能就会触发这个报错。解决办法在管理员权限的 PowerShell 里执行Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform执行完重启系统。然后确认你的 WSL 版本wsl --set-default-version 2如果之前装的是 WSL 1需要针对具体发行版升级一下wsl --set-version 发行版名称 2重启之后再运行claude这个报错一般就消失了。这里再补一句如果你公司电脑在域环境、被 IT 策略限制可能Enable-WindowsOptionalFeature会失败需要联系管理员开通对应策略或者走便携版装到开发机上。4.2 “无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这个问题在 Windows 和部分类 Unix 环境里都见过。原因基本都是安装路径没有被加入 PATH或者安装失败。先检查是否装上了npm list -g anthropic-ai/claude-code如果列表里没有说明安装失败了重装npm install -g anthropic-ai/claude-code如果列表里有但终端还是认不出claude那就是 PATH 的问题。查一下 npm 全局 bin 目录在哪npm prefix -g在 Windows 上这个目录通常是C:\Users\你的用户名\AppData\Roaming\npm把它加进系统环境变量 PATH然后重开终端。在 macOS/Linux 上可以把这个目录加到.zshrc或.bashrc里export PATH$(npm prefix -g)/bin:$PATH临时救急的办法是用 npx 直接跑npx anthropic-ai/claude-code注意用 npx 每次都会检查更新速度略慢适合临时用不建议长期依赖。4.3 安装后提示 “unfortunately, claude is not available to new users right now”这个报错一般是账号层面的限制常见于注册邮箱所属地域不在服务开放列表里或者账号刚创建、还没完成风控验证。重点检查三点账号注册地区是否属于 Anthropic 支持的区域是否完成了手机或邮箱验证代理节点是否干净——如果同一 IP 段下有大量账号注册也会被临时限制。如果只是地区暂未开放我的建议是不必硬绕可以等待官方放开或者用受支持地区的账号。如果短期就要用也可以关注代码开源和模型本身的 API 调用方式很多功能在某种程度上是可替代的。4.4 报错排查速查表报错关键词常见原因优先处理方向Virtual Machine Platform / Failed to start Claudes workspaceWindows 缺少虚拟机平台或 WSL 版本不对启用 VirtualMachinePlatform升级 WSL 2无法将“claude”项识别为 cmdletnpm 全局目录不在 PATH或安装失败检查 npm 全局目录修改环境变量重开终端unfortunately, claude is not available to new users账号/地区/风控限制核对账号地区完善验证换网络出口403 / authentication expired登录态失效重新执行claude login或清掉.claude下的凭据缓存Skills 没生效 / Agent 没有按 SKILL.md 执行SKILL.md 描述写得不够触发条件或放在了错误目录检查description是否覆盖用户指令中的关键词确认目录位置为.claude/skills/技能名/SKILL.md这张表我自己打印了一份贴在工位上因为这些问题在团队里出现的频率远比你想象的高。5. 深入开发怎么写一个自己的 Skills5.1 SKILL.md 的规范拆解一个可用的 Skill 其实不复杂核心就一个SKILL.md文件但写好的不多。我读过大量开源仓库里的 SKILL.md发现质量差异非常大。最基础的 YAML front matter 需要写两部分name和description。name是技能的唯一标识description是触发匹配的依据Claude 会把它与用户的指令做语义匹配。这里有个容易被忽视的技巧description 里不要只写一句“用于前端开发”而要写清楚触发场景和排除场景。比如--- name: react-component description: 当你需要创建、重构或审查 React 组件时使用。包括函数组件、hooks、样式方案、测试用例。如果只是简单的文案改动不要使用。 ---这样写模型在判断“该不该用这个技能”时会有更明确的边界不容易出现“我在聊普通问题它却加载了一堆组件规范”的情况。正文部分则建议包含这几块工作流程、规范清单、模板/示例、可复用命令。工作流程要写成明确的步骤序列比如“第一步阅读需求第二步确认组件边界第三步生成实现第四步列出自测清单”。模型在执行时对步骤的遵循度远高于对自由文本的遵循度。5.2 从需求到实现一个前端开发 Skill 的完整示例我以“新页面开发”为例写一个生产环境实际能用的 Skill。目录结构.claude/skills/frontend-page/ ├── SKILL.md ├── templates/ │ ├── PageComponent.tsx.tpl │ └── index.scss.tpl └── scripts/ └── scaffold.shSKILL.md正文不要写空话直接上干货--- name: frontend-page description: 在当前 React TypeScript 项目中开发新页面时使用。生成页面组件、路由配置、API 模块和基础样式。当用户说“新建页面”“开发页面”“页面模板”时触发。 --- # 新页面开发流程 1. 确认路由路径和菜单名称 2. 调用 scripts/scaffold.sh 生成目录结构和模板文件 3. 根据后端 API 文档在 services 目录下创建 API 模块 4. 组件实现要求 - 使用函数组件 hooks - 样式使用 SCSS Module类名前缀与页面名一致 - 必须补充 loading 态和 empty 态 5. 完成后在页面底部附上 checklist逐项自查有了这个 Skill我让 Claude 开发一个新页面时它会自动去调用脚本生成脚手架然后按规范补全代码。你可能会说“我直接跟它说清楚不就好了”但对一个几百人协作的项目来说把规范沉淀成 Skill比每次在 Prompt 里重复要可靠得多也少了扯皮空间。5.3 怎么测评一个 Skills 的好坏Skill 是拿来用的不是拿来摆设的。我以前装了一堆超级炫酷的 Skill结果发现大部分时候它们帮倒忙——不是触发不准确就是注入的内容太长把上下文塞满。从那以后我开始用一套比较务实的评估维度。第一触发率。你把一个 Skill 装好后故意用几种不同的措辞下达同类任务看它能否每次都正确识别。如果识别率低于 60%说明 description 写得不对要调整关键词覆盖范围。第二上下文开销。SKILL.md越长注入的 token 越多。200 行以内的说明一般没问题超过 500 行就得考虑精简或者把大量细节拆到单独的附加文件里按需读取而不是全部塞进主说明。第三错误率。注意看 Agent 在加载 Skill 后是否还频繁偏离规范。比如我在 Skill 里明确要求“组件必须先写 loading 态”但它偶尔还是会漏掉。这种情况要么是 Skill 的措辞不够强制性要么是后面生成的流程被更长上下文冲淡了。我的经验是把“必须”“禁止”这类词用在关键位置并且把检查项放在流程最后一步让 Agent 在收尾时再回顾一遍。第四复用性。这个 Skill 换一个项目、换一个队友的机器还能不能用如果能说明它写的是通用方法论如果绑死了当前项目的路径和专有名词那它更像一次性脚本。通用和专用需要平衡我的判断标准是技能描述的是“方法”还是“特定路径”如果是特定路径应该拆成项目级 Skill而不是全局 Skill。这四点评测下来一个 Skill 是否值得留在你的仓库里基本就有数了。6. 生态盘点与避坑心得6.1 值得关注的 Skills 资源除了 superpowers目前社区里也冒出不少高质量仓库。有个awesome-claude-skills类型的项目专门收集了各种 Skills我建议你不要一次性全装而是按需选择前端开发装组件规范和项目脚手架后端装接口设计规范数据相关装 SQL 编写规范和图表选择逻辑。另外如果你看到某些“超级 Skill”宣称“一键完成全栈开发”要降低预期。Skills 本质上是增强 Agent 对流程和规范的遵循它不是魔法代码还是代码出错了还是得排查。那些宣称过于神奇的仓库往往只是把一堆 Prompt 组合在一起缺乏实际结构的把控。git clone https://github.com/xxx/awesome-claude-skills.git装之前先看它的目录层级和 SKILL.md 质量不要光看 README 吹了什么。我一般会抽查两三个技能的 description 和正文如果描述模糊、步骤抽象直接放弃这个仓库。6.2 与 Codex Skills 的横向对比OpenAI 的 Codex 也有类似叫 “Skills” 的功能网上搜“codex 好用的 skills”热度也很高。两者在思路上确实方向一致——都是把技能定义成文件让 Agent 按需加载。但落地上差异明显。从我的使用体验看Claude Code 的 Skills 更新频率更高社区资源更丰富而且对文件目录的依赖更轻你不需要先把 skill 文件“注册”到某个中心化配置里只要放到.claude/skills目录就能识别。Codex 的 Skills 则更偏向通过配置文件和运行时定义工程化更强适合重度定制的用户但对于想快速上手的人来说门槛稍微高一点。结构图、论文润色、数据可视化这些技能两个生态里都有对应实现。我不是建议你站队而是说你可以都试试看哪个 Agent 的主干能力跟你的工作流更匹配。毕竟 Skill 再强也只是增量主干模型的能力才是底座。6.3 我的几点实战感受最后聊点感性的东西。我自己是从 2024 年底开始重度使用 Claude Code中间经历过很多“这功能是不是已经死了、没人管了”的波动期。但从 Skills 出现以后能明显感觉到一个变化Agent 从“看起来很聪明但容易跑偏”慢慢变成“有章法、有纪律的实习生”。这种变化的关键不全在模型本身而在于你把多少上下文显式地结构化交给它。我给团队做分享时常说一句话每次你觉得“Claude 这都能错”的时候先回头看自己有没有把规范沉淀下来有没有写成一个 Skill。如果你只是每次重新在对话里交代一遍那错一点不奇怪如果你已经把它写成了 Skill它还是犯低级错误那才是值得深挖的问题。Skills 的编写本身不复杂一个周末就能入门但想写出让 Agent 稳定执行的技能需要你对自己工作流有极清晰的认识。这个认识过程恰恰是 Agent 时代工程师最值钱的部分。