Claude Code 是 Anthropic 推出的终端 AI 编程智能体Agent。刚上手的人容易把它当成一个“能在终端里帮忙写代码的聊天机器人”输入一句话看它读文件、改代码、跑命令。实际上决定 Claude Code 能不能稳定处理复杂任务的关键不是聊天能力而是它能否按固定流程执行约定好的工作方式。Skills 技能包就是这个机制的核心一份 Skill 就是一份“工作手册 工具包”包含 Markdown 指令、检查清单、示例脚本和参考资料。安装现成的技能包新手几乎不用写代码自己编写技能包则能把团队的代码规范、测试策略、发布流程固化成一个可复用的模块。下文围绕“Claude Code Skills 技能包”展开先说明 Skills 是什么以及它和 MCP、CLAUDE.md 的边界在哪里然后完成 Claude Code 的安装和技能目录检查给出 7 个适合新手的技能包方向再演示安装、验证、手写、排错的全过程。文中命令在常见终端环境可复现字段设计尽量贴近当前主流版本但落地前请以你本地claude --help和官方文档为准。有人会拿 Codex 和 Claude Code 做对比这不展开横向评测只强调一个判断Skill 体系是 Claude Code 在终端编程智能体里比较有差异化的机制值得单独花时间理解。1. 先理解 SkillsClaude Code 的“工作手册”机制1.1 Claude Code 默认是怎么干活的Claude Code 的本质是一个运行在终端里的智能体循环。启动后它会读取当前目录的文件结构、项目说明和已有上下文然后不断执行“思考—调工具—看结果—再思考”的循环。它可以读取文件、编辑代码、执行终端命令、运行测试并根据输出调整下一步动作。这个模式的好处是灵活。坏处也很明显没有约束时每次执行的路径都依赖模型当时的判断。同一个项目、同一个任务上午和下午跑出来的过程可能差异很大。代码风格不一致、测试覆盖不完整、改完不跑检查、提交信息写得随意这些问题在小项目里还能忍一旦进入多人协作或生产环境就会变成持续踩坑的来源。1.2 Skills 要解决什么问题Skills 解决的问题可以概括为把“你希望智能体怎么干活”这件事显式写下来并让它按需加载。一个 Skill 通常是一个目录目录里有一个核心文件SKILL.md。文件开头有 YAML 格式的元信息里面最重要的两个字段是name和description。模型在工作时会根据用户请求的描述和每个 Skill 的description做匹配一旦判断当前任务适合某个 Skill它就会读取这个 Skill 的完整内容然后按里面的步骤执行。可以把它理解成给实习生发一份 SOP不写 SOP 时实习生靠感觉做事结果时好时坏写了 SOP 后至少每一步该做什么、做到什么程度算完成、出了问题先查哪都有了明确依据。Skills 比普通文档多出来的部分是它可以直接附带脚本、模板和参考资料让智能体在看完步骤之后还能真正执行一些标准化操作。1.3 Skills、MCP、CLAUDE.md 和斜杠命令有什么区别新手最容易混淆的是这四类机制因为它们在官方文档、社区帖子里经常一起出现。简单区分如下机制本质什么时候生效典型用途Skills过程性知识和操作步骤可附带脚本与模板模型的判断与技能 description 匹配时自动加载代码审查、测试生成、文档编写、重构MCP外部工具和数据访问的连接协议需要读写外部资源时调用查数据库、读网页、操作文件系统、调内部服务CLAUDE.md项目级长期记忆和偏好设置每次会话启动时加载技术栈说明、编码规范、常用命令、目录约定Slash 命令用户主动触发的提示词模板用户在会话里输入/xxx时固定格式的提交信息、代码模板、快速提问这里容易踩的一个误区是“装一个 Skill 就等于装了一个 MCP”。两者不是一回事。MCP 解决的是“智能体能不能访问某个外部能力”比如连数据库、查网页Skills 解决的是“智能体拿到外部能力之后按什么流程做事”。实际项目经常把两者搭配使用用 MCP 提供数据访问用 Skill 规定数据访问后怎么分析、怎么产出报告。CLAUDE.md 也常被误当成 Skills 的替代品。CLAUDE.md 更像项目档案每次会话都会加载适合放不常变的约定Skills 是任务型手册按需加载适合放具体任务的执行流程。如果项目里有很多一次性流程说明塞进 CLAUDE.md 会让每次会话的上下文越来越重更好的做法是把它们拆成 Skills。2. 安装 Claude Code 并确认技能包目录2.1 安装前的环境检查Skills 只是 Claude Code 的一个功能模块先保证 Claude Code 本身能正常工作。安装前建议确认以下几项Node.js 环境推荐使用 LTS 版本具体版本要求以官方安装文档为准。npm 可以正常使用如果企业内部有 npm 私有镜像先配置好 registry。git 已安装因为大量现成技能包是通过 git 仓库分发的。终端环境macOS 或 Linux 直接使用系统终端Windows 上建议优先使用 PowerShell 或 WSL2兼容性更稳定。检查命令如下node -v npm -v git --version如果node -v没有输出版本号需要先安装 Node.js。如果 npm 下载慢可以使用企业镜像或国内公共镜像但不要随意设置不受信任的 registry。2.2 安装与登录Claude Code 的常规安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version然后直接启动claude首次启动会进入登录流程通常有两种方式一是在浏览器里登录 Anthropic 账号完成授权二是使用 API Key 方式通过环境变量注入认证信息。如果你准备通过第三方 Anthropic 兼容接口来使用 Claude Code需要在启动前设置对应的环境变量这一部分在第 6.4 节专门说明。2.3 创建并确认 Skills 目录Claude Code 的技能包有两个常见存放位置用户级目录~/.claude/skills/对你机器上的所有项目生效。项目级目录.claude/skills/只对当前项目生效通常放进项目的 git 仓库里做团队共享。先检查用户级目录是否存在ls -la ~/.claude/如果不存在 skills 目录手动创建mkdir -p ~/.claude/skills再看项目目录ls -la .claude/skills/目录结构本身不复杂一个技能包就是一个子目录例如~/.claude/skills/code-review/SKILL.md。后续安装技能包时本质就是把对应目录复制到这个位置。2.4 避开 Windows 环境的一个经典坑热词里经常出现一条错误信息missing hcs services: hns, vmcompute, vfpext。这个报错不是 Claude Code 自身代码的问题而是 Windows 虚拟化服务没有正常开启。hns是 Host Network Servicevmcompute是 Hyper-V Host Compute Servicevfpext是虚拟过滤平台扩展。它们共同属于 Windows 的虚拟化和容器服务体系。当 Claude Code 的运行环境依赖 WSL2、Windows 容器或 Hyper-V 相关能力时这些服务如果没有启动就会看到上述报错。常见的处理路径是以管理员身份打开 PowerShell确认 Windows 功能里是否启用了“虚拟机平台”“Windows 虚拟机监控程序平台”“适用于 Linux 的 Windows 子系统”如果没启用可以用命令启用并重启dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后设置 WSL2 为默认版本wsl --set-default-version 2重启后重新运行 Claude Code。这里要注意启用虚拟化功能会影响系统启动策略生产机器或服务器上不要随意开启建议先在开发机上验证。3. 7 个新手推荐 Skills 技能包网上很多帖子会把技能包包装得很玄标题动不动就是“无敌”“必装”。准确的说法是同一个技能包在不同项目、不同模型版本下的效果差异很大选技能包应该按“你平时最常做的任务”来选而不是按“装的数量”来算。下面 7 个方向是按新手最常见的工作场景挑出来的不绑定某个特定仓库实际安装时可以先搜对应的 GitHub 仓库再看 README 决定是否使用。3.1 代码审查 Skillcode-review代码审查技能包是最适合新手的入门技能。它的作用是让 Claude Code 在你看代码时不要只给一句“代码看起来不错”而是按固定维度输出问题清单。一个合格的 code-review 技能包通常包含审查清单、常见缺陷列表、输出格式模板。审查清单会列出变量命名、异常处理、潜在空指针、资源关闭、安全风险、边界条件等维度输出模板会让智能体按“严重程度 问题位置 修改建议”的格式逐条输出。典型调用方式使用 code-review 技能审查当前分支的改动重点看异常处理和边界条件。新手用这个技能最能直观感受到 Skills 的价值同一份代码有技能包约束时输出的问题明显更结构化。3.2 单元测试生成 Skilltest-writer测试生成技能包解决的是“写了功能不想写测试硬写又不知道覆盖哪些分支”的问题。它通常包含测试策略模板、命名规范、断言规范以及常见测试工具链的调用示例。使用这类技能包时要注意它不能替代测试设计。技能包能让智能体生成“格式正确”的测试但不能保证覆盖了所有关键业务场景。建议在使用后自己检查几条核心业务路径是否真的被覆盖到不要因为测试文件生成得多就放松。典型调用方式使用 test-writer 技能为 src/services/orderService.ts 生成单元测试先列出需要覆盖的场景再写测试代码。3.3 需求拆解与任务规划 Skilltask-plannerClaude Code 在接到大需求时容易一口气开始改代码改到一半发现方向偏了。需求拆解技能包的作用是强制它先拆任务、再动手。技能包里通常包含任务拆解模板要求智能体在开始编码前输出需求理解、涉及文件、依赖关系、执行顺序、验收标准、风险点。还会规定“在用户确认任务清单之前不要修改任何文件”。典型调用方式使用 task-planner 技能帮我拆解“给后台管理页面增加导出功能”这个需求先给计划不写代码。这个技能对新手尤其友好因为很多问题不是代码写不出来而是没想清楚就开始写。3.4 Debug 定位 Skilldebugger调试技能包让 Claude Code 按系统化方式排查问题。它通常规定排查顺序先复现问题、再缩小范围、然后查看关键日志、最后提出假设并验证。好的调试技能包还会要求智能体记录“每次修改前的现场信息”避免改了几轮之后忘了最初的状态。输出格式一般包括问题现象、最小复现步骤、日志关键片段、根因分析、修复建议、回归验证方案。典型调用方式使用 debugger 技能排查接口偶发超时的问题先给排查计划再逐步执行。3.5 Git 工作流 Skillgit-workflowGit 技能包主要解决提交信息不规范、分支操作混乱、提交前没有跑检查的问题。它通常规定一套提交流程先查看变更状态、再按约定格式生成提交信息、提交前执行 lint 或测试、最后推送。技能包里的提交信息模板可以对齐团队规范。比如要求按type(scope): subject格式生成type限制为feat、fix、docs、refactor等常见枚举。典型调用方式使用 git-workflow 技能帮我提交当前改动提交信息按团队规范生成。3.6 文档编写 Skilldoc-writer文档技能包适合生成 README、接口文档、操作手册。它通常包含文档结构模板、示例代码的展示规范、表格使用规范以及“先写使用场景再写参数说明”的章节顺序。这个技能的价值是让文档输出不再是一大段没有结构的文字。使用它生成初稿后建议人工补充真实业务细节因为技能包里的模板再完整也不了解你们项目的真实约定。典型调用方式使用 doc-writer 技能为 utils/date.ts 文件生成 README 文档包含功能介绍、参数说明和示例。3.7 重构与可维护性 Skillrefactor重构技能包用于在保持行为不变的前提下改善代码结构。它通常要求执行三步先梳理现有行为再列出重构目标然后小步修改并持续运行测试。技能包里会强调“不要边重构边改功能”这是重构最常见的错误。它还会要求智能体在重构前后各跑一次测试用测试结果证明行为没有变化。典型调用方式使用 refactor 技能重构这个模块把重复的条件判断提取成公共函数重构前后都要跑测试。3.8 去哪里找现成技能包找技能包最常见的路径是在 GitHub 上搜索。可以直接搜索claude skills、awesome-claude-skills、find skills这类关键词社区已经有大量聚合仓库把技能包按语言、场景分类整理好。除了个人技能包也可以关注比较知名的合集项目。例如社区里常见的 Superpowers 技能合集侧重把复杂工作任务拆成可复用的技能子集前端方向有 Matt Pocock 整理的技能包偏代码质量和工程效率。选用时不要只看仓库星标要实际看 SKILL.md 的内容深度和项目维护时间。这里需要说明网上很多帖子会提供打包好的“技能安装包”实际内容就是一堆以SKILL.md为核心的目录完全可以从公开仓库直接获取。不建议下载加密压缩包或来路不明的脚本容易夹带恶意内容。自己从仓库克隆并检查内容更安全也更容易维护。4. 安装、启用和禁用 Skills 的三种方式4.1 从 GitHub 克隆到用户级目录最通用的安装方式是使用 git 将技能包仓库克隆到~/.claude/skills/。以远程仓库为例git clone https://github.com/your-name/some-skill.git ~/.claude/skills/some-skill仓库地址需要替换成你实际使用的地址。克隆完成后检查目录结构ls -la ~/.claude/skills/some-skill/ cat ~/.claude/skills/some-skill/SKILL.md关键检查点是 SKILL.md 是否存在以及 frontmatter 里是否有完整的name和description。如果技能包目录里只有一堆说明文件但没有 SKILL.md那它可能不是标准技能包结构加载时可能无法被正常识别。4.2 使用技能包自带的安装脚本部分技能包会提供install.sh或Makefile用来简化安装。执行前一定要先看脚本内容cd ~/some-skill cat install.sh确认脚本只是复制文件、创建目录、安装依赖之后再执行./install.sh不要盲目运行来源不明的脚本。安全习惯是任何安装脚本在本地执行之前先逐行确认它访问了哪些路径、执行了哪些命令。4.3 在项目级目录使用和临时禁用项目级技能包放在.claude/skills/下这个目录建议提交到 git 仓库这样团队成员 clone 项目后自动获得统一技能包。目录结构如下你的项目/ ├── .claude/ │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── test-writer/ │ └── SKILL.md临时禁用一个技能包不需要删除直接把对应目录改名即可例如mv .claude/skills/code-review .claude/skills/code-review.disabled改名后目录里的 SKILL.md 仍然存在但文件路径已经变了Claude Code 不会把它当作有效技能加载。这种方式比直接删除更安全方便随时恢复。4.4 验证 Skills 是否被加载验证技能是否生效这里有几个层次文件层面确认 SKILL.md 和相关脚本都在正确目录。会话层面启动 Claude Code 后可以直接问“你现在能使用哪些 skills”不同版本对这一问题的回答方式不同不一定会完整列出。实际执行层面明确要求“使用某个 skill 完成任务”观察输出是否遵循了 SKILL.md 里写的步骤。调试层面在终端启动时加--debug参数观察启动日志里是否出现 skill 加载记录。最可靠的验证方式是第三层如果技能里要求“先列计划再改代码”而实际执行时直接改了代码说明技能没有被正确匹配或内容本身写得不够清晰。4.5 安装后技能不生效时的初步排查安装后不生效优先按下面顺序检查技能目录是否放错了层级skills/技能名/SKILL.md和skills/SKILL.md是两种完全不同的结构。name字段是否唯一多个技能共用同一个 name 会导致冲突。description是否太泛描述越模糊模型越难在正确时机触发它。是否修改了技能内容但会话没有重新加载重开会话再试。5. 手写一个最小 SkillSKILL.md 完全拆解5.1 目录结构长什么样一个最小技能目录可以既简单又完整my-skill/ ├── SKILL.md ├── scripts/ │ └── check.py └── references/ └── guidelines.mdSKILL.md是入口scripts/放可执行脚本references/放补充资料。Claude Code 加载技能后会先读 SKILL.md再按指令决定是否需要读取 references 或执行 scripts。5.2 frontmatter 字段怎么写SKILL.md 开头是 YAML frontmatter用---包裹--- name: code-review description: 当用户要求审查代码、检查 PR、Review 变更时使用。适合在代码改动完成后输出结构化问题清单。 ---两个核心字段的写法要注意字段说明常见错误name技能唯一名称建议小写、连字符连接名称太长或包含空格导致调用不稳定description描述技能的触发场景越具体越好写得太泛例如“帮助用户审查代码”模型不知道什么时候该用有些技能包还会带version、license、metadata等字段版本不同格式有差异。如果看到教程里出现这些字段可以保留但name和description是底线要求。description的设计值得多花时间模型是通过描述来匹配技能的描述里最好包含任务动词、对象和典型场景。5.3 正文指令的写法frontmatter 下面的正文就是给智能体看的操作手册。一个能用的例子# Code Review Skill ## 触发条件 当用户要求审查代码、检查 PR、Review 代码变更时使用本技能。 ## 执行步骤 1. 先查看本次变更的文件列表和 diff不要在没有 diff 的情况下空谈问题。 2. 按下面维度逐项检查 - 命名是否清晰 - 异常处理是否覆盖边界条件 - 资源是否被正确关闭 - 是否存在明显安全风险 - 是否有重复代码可以抽取 3. 按严重程度输出问题清单严重 / 一般 / 建议。 4. 每个问题必须给出文件路径、问题描述、修改建议。 ## 输出格式 问题清单按表格输出包含 - 严重程度 - 文件与行号 - 问题描述 - 修改建议 ## 注意事项 - 不要只输出“看起来不错”这类结论必须给出至少一个可执行建议。 - 空指针、外部输入未校验、硬编码敏感信息等属于严重问题需要单独标注。这段正文的特点是把“怎么做”全部量化了。比如“查看 diff”“按维度检查”“按严重程度输出”“每个问题包含文件路径和修改建议”每一步模型都清楚怎么执行。相比只说“请严格审查代码”这种写法稳定得多。5.4 编写技能包的几条原则写技能包不是写文章不要追求语言丰富要追求指令可执行。几个实用原则先写触发条件让模型知道“什么时候该用我”。步骤用数字编号每一步尽量给出“做什么、做到什么程度、怎么做”。明确输出格式表格、列表、JSON 都可以写清楚最好。把异常分支也写进去例如“如果测试失败先停止重构报告失败原因”。可执行脚本放 scripts不要在 SKILL.md 里贴大段代码。不要堆砌通用套话比如“注意代码质量”“保证系统稳定”这类指令模型无法落地。6. 常见问题排查清单6.1 Skill 没有生效问题现象常见原因检查方式处理建议明确要求使用技能但没有按 Skill 步骤执行技能目录结构错误检查 skills 下是否多了一层目录调整为skills/技能名/SKILL.md技能在别的项目能用当前项目不行项目级技能目录与用户级技能目录冲突查看.claude/skills是否存在同名技能删除或重命名冲突目录修改 SKILL.md 后行为没变化会话缓存未刷新重开会话保持技能文件稳定避免频繁改技能完全不出现frontmatter 缺失或字段错误打开 SKILL.md 检查---包裹格式修复name和description6.2 模型一直不调用 Skill很多时候技能文件没问题但模型就是没有主动触发它。这通常是因为description写得不够具体模型在任务描述和技能描述之间找不到明显关联。建议方式是在会话里直接明确要求“使用某个技能”。不要指望模型每次都自己判断对显式调用是最可控的方式。另一个方向是优化 description把常见的用户说法写进去。例如用户可能说“帮我看看这段代码有没有问题”那 description 里就可以包含“审查代码、看看代码有没有问题、Review 代码”等同义表达但要控制长度不要太长。6.3 不想一直点确认怎么配置更省事热词里“claudecode如何不用一直点确认”对应的其实是 Claude Code 的权限确认机制。它为了安全在执行某些操作时会向用户确认。减少确认的推荐方式不是把所有确认都关掉而是配置白名单。在项目的.claude/settings.json中可以配置允许自动执行的规则例如{ permissions: { allow: [ Read, Bash(npm run lint) ] } }这里只示意结构具体规则名称和写法以当前版本settings文档为准。这样读取文件和运行npm run lint这类低频安全操作可以免确认但高危命令仍然会提示。Claude Code 还提供权限模式参数例如acceptEdits模式可以自动接受编辑类操作bypassPermissions模式会跳过所有权限确认适合 CI 或一次性任务不建议日常开发使用。启动前用claude --help确认当前版本支持的参数名称。6.4 接入 DeepSeek 等第三方 API 时技能包表现不稳定Claude Code 可以通过配置第三方 Anthropic 兼容接口来使用其他模型例如 DeepSeek 提供的兼容接口。配置层面的原理是把请求转发到指定接口由该模型完成推理但 Claude Code 的工具调用框架、Skills 的文件加载和上下文构建机制仍然保留。这意味着技能包在文件层面仍然会加载SKILL.md 的内容仍然会被读入。但不同模型对长指令的遵循程度、工具调用稳定性、多步推理能力差异很大这就导致同一个技能包在官方模型下表现稳定换到第三方模型后可能出现“读了 Skill 却不按步骤执行”的情况。建议第一第三方模型下尽量使用小而专的技能包单个技能只做一件事第二关键业务任务不要完全依赖自动化结论技能输出要经过人工复核第三先把技能在官方模型下验证通过再切换到第三方模型测试兼容性。第三方模型的接口配置方式以官方文档和对应服务商文档为准不同服务商的兼容程度不一样。6.5 会话上下文越来越长回答越来越迟钝怎么办Claude Code 长时间会话里积累的日志、文件内容和对话历史会让上下文越来越长模型反应变慢、执行越来越不稳定。这时候可以使用会话压缩命令/compact它会压缩上下文并继续当前任务。压缩之后部分细节可能丢失所以在压缩前建议先确认结果已经保存到文件里或者让模型先输出摘要。另一个更省事的做法是直接开启新会话把当前任务结果、剩余问题、下一步计划整理成文字再在新会话里继续。围绕 Skills 的使用这也意味着技能包描述要足够清晰因为它在新会话里可能成为唯一的行为依据。7. 最佳实践从新手到生产级使用7.1 区分学习环境和生产环境学习环境里可以大胆安装各种热门技能包试错成本低目的是理解 SKILL.md 的写法、触发机制和输出格式。生产环境必须更谨慎技能包里的每一步都会影响真实代码和业务需要走正式评估流程。生产环境至少要考虑以下几点技能包是否经过代码审查、脚本是否有权限控制、SKILL.md