前几篇咱们把 Claude Code 的安装、日常会话和基本工作流都过了一遍。如果你已经跟到这儿应该已经能顺畅地让它在项目里改代码、跑测试、写提交信息了。但用着用着就会出现一个很难受的瓶颈稍微复杂一点、带规则的任务几乎每次都要把背景和要求重新讲一遍Claude 表现的稳定性完全取决于我当时的 prompt 写得多细。我在用了大概两周之后忍不住想与其每次手把手教不如把我自己的处理经验打包成一个可复用的单元让它自己按套路来。这个单元就是 SKILL。这篇是系列第四篇我不打算聊太多概念层面的展望直接带你把 SKILL 的创建、安装、查看这三件事全部走通。内容主要针对两类人一是已经装好 Claude Code、希望把高频工作流程化的人二是看到 GitHub 上各种技能仓库但不知道怎么塞进自己环境里的人。看完之后你至少能独立做出一个能用的 SKILL并且搞清楚什么时候该用 SKILL、什么时候不该用。1. SKILL 到底是什么它解决的问题和我为什么坚持用1.1 一句话定义和它在 Claude Code 里的位置你可以把 SKILL 理解为一份岗位说明书 操作手册的合体。它不是一个独立运行的程序也不是一个拥有自己对话窗口的 Agent它更像是一套结构化的知识包放在约定好的目录里。当你的提问内容命中这个 SKILL 的描述时Claude Code 会把对应的 SKILL.md 内容自动读进上下文然后按照里面写的步骤、规则、示例来帮你完成当前任务。听起来有点像预设 prompt对吧这也是我第一次接触时最大的疑问。但实际用下来差别挺大的。预设 prompt 是让 Claude 在每轮对话里都背着一段话干活背得越多模型注意力被稀释得越厉害还容易互相干扰。而 SKILL 走的是按需加载路线平时完全不占上下文只有当你问到相关事情的时候它才被激活并注入。这种设计和人脑的遇到问题时才翻手册非常像效率高得多。用生活里的例子打比方你和一位新同事配合你可以提前把公司报销制度整段背给他听也可以告诉他公司有本《报销手册》遇到报销问题时去查第七章第三小节。SKILL 就是那本随查随用的手册而不是让人死记硬背的整段话。1.2 为什么不是塞在 System Prompt 里拆解触发机制早期很多 Claude Code 教程会教你用CLAUDE.md这类全局记忆文件把规则固化下来。这没错但它更适合放始终成立的偏好和约束比如代码注释用中文写优先使用项目已有的工具链。而 SKILL 适合的是条件触发的过程性知识比如当用户要生成发布说明时请先拉取 git log再对照标签分类最后按模板输出 Markdown 格式的变更记录。两者的边界我踩过坑才想明白。有一段时间我把能想到的规则全都写进了 CLAUDE.md结果 Claude 在处理简单任务时变得异常啰嗦经常莫名开始检查一堆根本用不上的约束。后来我把那些高频但非始终执行的流程全部拆成 SKILLCLAUDE.md 里只保留底层偏好整个体验立刻清爽了。这也侧面说明了 SKILL 的核心优势它让 Claude 的执行路径可以被场景化地触发而不是所有知识一股脑堆在每条消息里。触发机制本身也值得说一句。SKILL.md 最上方的 YAML frontmatter 里有一个description字段这个字段就是触发开关。Claude Code 会基于你当前的提问结合这个 description 判断要不要加载对应的 SKILL。所以 description 写得好不好直接决定这个技能会不会被用起来——这个问题我后面专门讲因为大多数人创建完技能觉得没用八成就是栽在这里。1.3 SKILL 与 Agent、插件、MCP 的边界顺带把几个容易混淆的概念一起说清楚因为热搜里也一直有人问 skill 和 agent 的区别。在 Claude Code 的目录体系里.claude/agents/下放的是自定义 Agent.claude/skills/下放的是 SKILL两者边界挺明显的Agent 是一个拥有独立系统提示词和工具权限的执行者适合那种你只需要告诉它目标它自己决定怎么做的任务而 SKILL 是一份说明书它本身不新增工具权限也不拥有独立的行动策略它只是告诉 Claude 遇到某类情况时按什么流程来处理。打个比方Agent 像你外包给一个独立的项目经理你只交代他要交付什么SKILL 更像是你塞给一个多面手员工的 SOP 文档他依然是你手底下那个人只是翻出了对应手册来干活。所以在实际项目里我们常见的使用方式是SKILL 负责沉淀怎么做Agent 负责决定要不要做、调用哪些资源做。两者组合才是完全体。至于插件和 MCP又是另外一层。Plugin 主要是用来扩展 Claude Code 的前端能力和命令入口MCP 则是给 Claude 增加读取外部数据/操作外部工具的能力。SKILL 不直接提供这类手臂型能力它更像大脑中的知识库。搞清楚这些边界之后你再去决定某个需求到底该做成 SKILL、Agent 还是 MCP 服务器思路会清晰很多。2. 动手前先搞懂 SKILL 包结构2.1 一个 SKILL 的最小目录长什么样网上很多所谓的 skill 资源包下载下来你会看到里面是一个带名字的文件夹。内部基本上是这样的结构my-skill/ ├── SKILL.md └── scripts/ └── run_analysis.py最核心的就一个文件SKILL.md。注意文件名必须全大写我遇到过好多次有人建成了skill.md或者Skill.mdClaude Code 直接当没看见。目录名则是你给这个技能起的标识名一般用小写字母加连字符比如release-notes、code-review-standard。SKILL.md内部由两大部分组成开头的 YAML frontmatter 和正文。frontmatter 用---包裹里面一般包含name和description两个字段。正文则是给 Claude 看的 Markdown 操作说明你希望它按什么流程执行、注意哪些边界、最终输出什么格式都可以写在这里。如果只有 frontmatter 没有正文这个技能就是一个空壳Claude 只会在该不该加载时看到 description真正加载了却不知道要干嘛。scripts/目录不是必须的它用来存放一些可执行的辅助脚本。典型场景是你的 SKILL 要让 Claude 执行一段比较复杂的本地逻辑比如解析日志文件、调用某个 API、批量处理图片。把这些代码放在脚本里SKILL.md 里写清楚什么时候运行这个脚本、传什么参数、怎么解读脚本输出Claude 执行起来会更稳定。我甚至见过有人把整套数据处理流程写成 Python 脚本SKILL.md 只有七八行说明效果反而比让 Claude 现场写代码好得多。2.2 SKILL.md 的核心YAML frontmatter我们展开看一下 frontmatter 的写法。一个规范的示例长这样--- name: release-notes description: 当用户需要基于 git 提交记录或 issue 列表生成发布说明、变更日志时使用。Use when summarizing commits, generating release notes, or writing changelogs based on git history. ---name字段是这个技能的唯一标识建议和目录名保持一致。description字段是最关键的部分它要回答两个问题什么情况下触发这个技能、这个技能能干嘛。Claude Code 是根据当前对话内容与这段 description 的语义匹配度来决定是否加载技能的所以 description 里最好明确写出触发场景的关键词。这里有个常见认知误区很多人把 description 写成了向 Claude 介绍这个技能是干嘛的比如写这是一个发布说明生成技能它可以帮助用户生成发布说明。这种写法非常糟糕因为它没有给出触发条件。正确的姿势是写当用户想……时使用此技能。你要让模型读完这段描述后能判断眼前这条用户消息是否符合这个场景。用中文写完全没问题但如果你想获得更好的匹配效果中英双语都写上会更有把握我自己的技能基本都采用双语 description。2.3 Skills 目录的三种作用域你需要知道 SKILL 可以放在三个层级它们的作用范围各不相同。第一层是用户级路径是~/.claude/skills/。放在这里的技能对你当前登录账号的所有项目都生效适合放那些跨项目通用的东西比如代码提交信息规范、通用的技术周报生成器。第二层是项目级路径是你的项目/.claude/skills/。放在这里的技能只会在这个项目仓库里生效而且通常会被提交到 git 里团队成员克隆项目后自动拥有。这非常适合沉淀项目特有的流程比如本项目的数据库迁移规范本项目后端接口怎么调用。第三层是企业级或者叫团队级一般通过公司的统一配置目录分发个人开发者用不太到。如果你们公司用 Claude Code 的托管策略技能目录可能会被集中管理。这里我不展开因为对多数读者来说掌握前两层就够了。我自己的习惯是但凡技能内容里涉及某个项目的路径、某个服务的前缀我绝不放进用户级目录省得在别的项目里被误触发。踩过一次坑之后我就学乖了——在 A 项目创建了一个内部接口文档生成技能放在用户级结果跑到 B 项目聊天时这技能偶尔也会被加载生成了一堆 B 项目根本不存在的接口文档说明非常尴尬。3. 创建自己的 SKILL从需求到落盘3.1 场景把发布说明撰写固化成技能光说不练假把式我们来做一个真正能用起来的技能。我选发布说明生成这个场景因为几乎每个研发团队都会遇到而且它的流程稳定、规则清晰特别适合第一次练手。先定义需求我要让 Claude 在项目里根据 git 提交记录自动生成发布说明按功能、修复、优化、其他四类分组同时满足以下规则合并提交不单独列出、修复类提交要提到关联的 issue 编号、输出格式要符合团队模板。这些规则如果每次用嘴说不仅长而且 Claude 很容易漏掉某一条例如偶尔会把 merge commit 也塞进去还要我事后手工清理。把它做成 SKILL 之后我只需要说生成本期发布说明剩下的它全部按手册执行。3.2 完整目录创建过程先确认自己的用户级 skills 目录存在不存在的就新建mkdir -p ~/.claude/skills然后创建技能目录和文件mkdir -p ~/.claude/skills/release-notes touch ~/.claude/skills/release-notes/SKILL.md下面是我实际在用的一份 SKILL.md 内容骨架你可以直接抄--- name: release-notes description: 当用户需要基于 git 提交记录生成发布说明、更新日志、release notes 或 changelog 时使用。Use when the user asks to generate release notes, changelog, or version summary from git history. --- # Release Notes 生成 ## 任务目标 根据当前分支相对于 main 分支的 git 提交记录生成结构化发布说明。 ## 执行步骤 1. 运行 git log main..HEAD --oneline --no-merges 获取提交记录。 2. 过滤掉 chore(deps) 类别的依赖更新提交。 3. 将提交记录按以下分类归组 - 功能(FEATURE)feat / feature / 新增 - 问题修复(FIX)fix / bug / 修复 - 性能与优化(PERF)perf / optimize / 性能 - 其他(OTHER)docs / refactor / style 等 4. 对每条修复类提交如提交信息中包含 #123输出时保留并补充到 issue 列表。 5. 按照模板输出 Markdown。 ## 输出模板 ## 本期更新 ### 功能 - 描述 ### 问题修复 - 描述Issue #123这里我特意把提交过滤规则和分类方式写得很具体因为如果你不写清楚Claude 就会凭自己对发布说明的模糊理解自由发挥。SKILL.md 的正文不需要长篇大论但必须有明确的执行顺序、边界条件和输出格式。本质上是把一个模糊任务变成流水线作业。文件保存好之后重启一下 Claude Code 会话让技能目录被重新扫描就可以测试了。我一般会在项目目录里输入类似根据近期的提交记录写一份发布说明这样的指令如果 Claude 开始按 SKILL.md 里的步骤走说明命中成功。3.3 写 description 的技巧决定命中率既然前面反复强调 description 的重要性这里我系统性地给出三条经验第一用当……时来开头。直接把触发前置条件写清楚。比如当用户需要生成发布说明或变更日志时使用尤其是基于 git 历史时。第二把同义词和变体描述都覆盖进去。不同的人说同一件事会用不同的词有人会说release notes有人会说更新日志还有人会说这版改了啥。description 里把这些中文说法都带上命中率会明显提高。但要控制在一个合理的篇幅内不必把每个词都枚举一遍。第三注意排除歧义。比如我见过有人做一个API 接口文档生成技能description 写得很宽泛结果用户只要讨论接口报错模型也会试着加载它导致回答风格混乱。正确做法是明确仅当用户要求生成、更新或整理接口文档时使用不用于排查接口故障把负面场景也标出来。3.4 用 Claude Code 自己生成 skill如果不想每次手工写 YAML完全可以让 Claude Code 自己当 skill creator。你可以这样给它下指令请帮我创建一个技能放到用户级 skills 目录。技能名称 html-email-template用途是根据我提供的简单文本内容生成适合邮件客户端的 HTML 邮件模板。技能执行时需要注意内联样式优先、兼容 Outlook、宽度不超过 600px。请帮我写好 SKILL.md 以及必要的说明。新版 Claude Code 对这种指令的处理能力相当强它会自行创建目录、编写 frontmatter 和正文甚至会主动把常用的邮件客户端兼容规则补充进来。生成完你只需要去目录里检查一遍内容是否符合预期即可。我个人习惯是先让它生成初稿然后我再手工修改正文里的执行步骤毕竟我最了解自己团队要什么。但有一点必须提醒让 Claude 帮你生成技能不等于你能跳过对结构的理解。你还是要会看它生成的 SKILL.md 是否合理否则出了问题你连排查方向都没有。我第一次犯的错就是让它生成一个Python 后端接口测试技能它给写成了一个冗长的教程文档正文里全是教学语气完全不是一个可执行的 SOP。后来我花了半小时自己重写从那以后我对自动生成的东西都保留审查一步。4. 安装第三方 SKILL 的几种姿势4.1 姿势一手动克隆或复制到 skills 目录GitHub 上有大量现成的 skilk 资源形式基本都是一个带 SKILL.md 的文件夹。安装方法简单粗暴把那个文件夹放进你的~/.claude/skills/或项目.claude/skills/目录然后重启 Claude Code。具体操作可以用 git clone 直接拉取git clone https://github.com/某个用户/某个技能仓库 ~/.claude/skills/skill-name如果技能只占一个子目录克隆完整仓库之后再把对应文件夹复制过也行。Windows 用户注意你的用户目录一般是C:\Users\你的用户名\.claude\skills路径里的点开头文件夹在资源管理器里默认隐藏需要开启显示隐藏项目。这里我特别提醒一句安装第三方技能之前先打开 SKILL.md 看看内容尤其是有没有脚本类文件。技能里的脚本会以你的本机权限执行如果来源不可信相当于把一段任意代码放到了你的开发环境附近。我个人的原则是只装我能看懂内容、且 GitHub 星标和评价都不错的技能。别为了图省事装一堆不明不白的包这在性质上跟乱装 npm 包没有区别。4.2 姿势二通过插件市场安装如果你不喜欢手动处理文件Claude Code 本身也支持插件机制。部分技能被打包成了 plugin可以直接通过市场安装不需要自己管理目录。具体入口在当前版本里主要靠会话内的/plugin这类命令调起浏览器界面。你在界面里搜索包含 skills 的插件点击安装后会统一落入 Claude Code 的配置目录并且比手动复制多一层好处——后续插件作者升级你可以通过插件管理来更新不用自己拉仓库覆盖。我自己的实践感受是第三方开源生态里质量参差不齐插件市场能帮你省去手动 clone 的麻烦但核心挑选逻辑不变先看这个插件包含哪些 skills、SKILL.md 内容写得是否清楚、近期有没有维护记录。装完插件后如果发现技能不生效第一件事去翻实际安装目录看文件有没有完整落盘不要只在插件界面里干瞪眼。4.3 姿势三让别人一键安装如果你自己做了个技能想分享给团队同事可以写一个简单的安装脚本帮他们一键完成。最原始的方案是给一个 shell 脚本内容大体是拉取代码、复制目录。# install-my-skill.sh mkdir -p ~/.claude/skills git clone https://github.com/yourname/my-skill ~/.claude/skills/my-skill echo 安装完成请重启 Claude Code如果你在公司内部用 GitLab也可以把仓库地址换成内网地址这样同事执行脚本时并不会访问外网。不过团队化分发还有更好的方式就是通过 plugin 市场自建源或者利用公司统一管理配置这就涉及更多企业配置层面的东西了。小团队场景里我个人觉得直接提供安装脚本最省事哪怕队友不太懂技能目录结构也能照着跑完。4.4 安装后必须做的检查装完技能不是万事大吉我强烈建议你按下面三步做一次体检。第一步确认目录位置。用ls看文件到底落在了哪里是不是你想要的作用域有没有因为命令执行目录不同导致跑到了错误路径。第二步打开 SKILL.md 检查 frontmatter。重点看name有没有和已有技能冲突。我有一次装了一个叫blog-writer的技能没注意自己之前已经建过同名技能结果目录被覆盖旧内容全丢了。加载优先级和覆盖机制在不同版本里可能表现得不太一样最稳妥的做法就是不要同名。第三步做一次最小触发测试。新开一个会话输入和该技能 description 高度匹配的指令看 Claude 是否按预期流程执行。比如刚装了周报生成技能你就说帮我生成这周的工作周报它有没有主动采用技能中定义的模板和步骤一眼就能看出来。如果没触发九成是 description 和测试语句匹配不上或者目录没放对照着第 6 节排查。5. 查看与管理已装技能5.1 用命令行直接查看目录结构最直接的查看方式就是看文件系统。想快速列出所有已装技能执行ls ~/.claude/skills/想连项目级技能一起看就分别看项目/.claude/skills/。如果技能数量多了想看树状结构可以用find ~/.claude/skills -maxdepth 2 -name SKILL.md这条命令会把每个技能里的 SKILL.md 路径列出来方便你心里有数。假如你怀疑某个技能内容被改坏了直接用cat查看它的文件内容即可。有时候你还需要看这个技能有没有附带脚本文件可以加一层find ~/.claude/skills/skill-name -type f这样能看到这个技能目录下到底有哪些文件也方便判断安装是否完整。5.2 让 Claude 自己汇报可用的技能除了手动翻文件系统你也可以在会话里直接问 Claude 目前加载了哪些可用的技能。比如输入请列出你在当前环境中可以使用的所有 skills不需要执行任何操作只需告诉我名称和各自的 description 就行。Claude 会根据当前实际可读取的技能目录信息汇总回答。这个方法比翻目录多了一层好处你能看到 Claude 自己对这些技能的理解版本如果它漏掉了某个技能那基本说明 description 写得有问题或者目录位置不在它的扫描范围里。我会定期做一次这样的盘点把那些描述不清楚、长期没触发过的技能标记出来统一清理。这里也补充一种更轻量的做法很多技能的 description 里会自带触发用语比如它可以让你用运行 PDF 工具这样的短语来强制触发。你可以直接对某个技能名说我想用 xxx 技能完成某事这往往比绕弯子更有效也能帮你确认技能是否可用。但如果技能真的没加载成功这种叫名字的方式也会失败那就得回到文件系统里去排查。5.3 升级与删除清理技能也需要持续维护。第三方技能如果原作者有更新手动复制安装的情况下去原仓库拉最新代码再覆盖即可。覆盖之前建议先备份自己的定制化修改或者用 git 管理你的整个~/.claude/skills目录。我最初只觉得这个目录放点配置而已后来发现值得为一个目录单独做 git 仓库里面有些脚本是花了很久调出来的如果误删或者改坏再要重写成本很高。删除技能同样简单直接把整个目录移除。比如要删除release-notes这个技能rm -rf ~/.claude/skills/release-notes删完重启会话就不会再加载了。但我要提醒一句如果你的技能装在项目级目录里删除后记得提交代码变更否则你只是本地删掉了不会影响团队成员。同理如果你的技能增加了也要及时同步到仓库里让团队其他人拉取代码后也能用上不然会出现你本地有一套神奇流程、队友还是老方法的割裂状态。另一个维护建议是给技能写版本说明。在 SKILL.md 正文里加一行## 版本标注修改日期和改动内容。听起来有点形式主义但技能一旦超过三个你就很容易忘记当初为什么加了某条规则。版本记录虽然简单但在回退和排查时能省大量时间。6. 常见问题与排查技巧实录技能做出来但不生效是新手问得最多的一类问题。我把这几年实际遇到过的坑整理成了一张速查表遇到问题先对着表过一遍。症状最常见原因解决方法创建了技能目录后完全不被触发目录作用域或文件名不对检查是否放到~/.claude/skills/或项目.claude/skills/下且 SKILL.md 文件名全大写skill 时灵时不灵description 写得太宽泛或太窄用当……时句式覆盖同义词并在正文加入触发示例技能加载了但不按流程执行SKILL.md 正文缺少可执行步骤把步骤拆成有序列表写明运行命令和输出格式技能里的脚本运行报错缺少依赖或没有可执行权限用python your_script.py手动试跑安装缺失依赖必要时chmod x技能目录覆盖导致旧内容丢失name 与其他技能重名安装前先ls检查现有目录避免同名覆盖Claude 回答风格被全局记忆干扰CLAUDE.md 内容过重把条件触发的流程知识迁移到 SKILL全局文件只留偏好组织账号模式下技能不可用管理员关闭了对应订阅权限联系管理员确认账号对 Claude Code 的订阅访问权限个人账号可忽略除了表格里的硬性问题我还想分享两个更隐蔽的坑。第一技能数量和 description 长度会反过来影响触发质量。技能装太多之后Claude 每次判断要不要加载时的选择范围会变大偶尔会把不相关的技能也牵扯进来。我在同时维护十来个技能后明显感觉到触发稳定性下降。后来做法是不是近期高频使用的技能不放进用户级目录而是放回一个技能库文件夹需要用的时候再手动复制到 skills 目录。这招虽然原始但非常有效相当于给 Claude 减负。第二SKILL.md 里最好不要过于细致地规定必须使用某个工具链版本之类硬性约束除非项目里确实有 lock 文件锁定。否则一旦环境不一致技能执行到一半就会卡在环境检查上。我更推荐在正文里写清楚先检查当前环境是否满足以下条件如果不满足则中止并告知用户缺少什么把异常处理交给 Claude 去判断而不是让它机械地执行一套必然失败的流程。再补一个经常被忽略的点修改 SKILL.md 之后如果当前会话还开着Claude 用的可能还是旧的技能内容缓存。别浪费时间反复测试直接退出重新进一个新会话再验证。这个细节我说了很多次但仍然有不少人问我为什么改了没反应大部分就是没重启会话。写在最后的一条实操心得如果你第一次接触 SKILL我的建议是别急着装一堆现成技能先把你工作里最高频、最需要规则一致性的那个任务找出来亲手做一个简单的 SKILL。从今天能用上的小技能开始而不是一开始就做一个覆盖所有场景的大而全的东西。我到现在也维持着这个习惯每周五都会翻一下这周让 Claude 反复做过的任务如果同一件事我用了三次以上且每次都要补充大量细节就说明这件事值得沉淀成一个 SKILL。这套高频动作技能化的做法帮我省下的时间远比当初学习创建技能花的功夫多得多。技能不是越复杂越好能在正确的时候被触发、按规矩把事办利索才是它真正的价值。