给Claude Code装上40个Skill后，我才发现之前都白用了

前两天有个读者加我，上来就吐槽。说 Claude Code 用了仨月，感觉就是个「能改代码的聊天框」，写两行还得自己盯着改，没网上吹得那么神。

我让他截个 ~/.claude/skills 目录给我看。

空荡荡，一个文件夹都没有。

我一下就懂了。他手里那个 Claude Code，跟我用的根本不是同一个工具。我本机的 ~/.claude/skills 下面躺了 40 个 skill，从写文章、画图、做视频，到系统化调试、测试驱动开发、子 agent 并行调度，全是它。Claude Code 启动时把每个 skill 的名字和描述预载进系统提示，命中了才读正文，这一套机制跑下来，能力确实不是一个量级。

今天这篇，我把这大半年攒的东西一次性倒给你。Skill 到底是什么，去哪找经过 star 验证的好货，10 分钟写一个能跑的，再到权限、子 agent、动态注入这些高级开关，最后亮一下我自己的技能栈。建议直接收藏，当技能地图用。

Skill 到底是什么，先把心智模型搭对

很多人把 Skill 和 MCP、Hook、Plugin、斜杠命令、CLAUDE.md 搅成一锅粥。我在 055 那篇画过决策图，这里不展开，一句话区分。

MCP 是给 Claude 接手脚和数据，连数据库连外部系统。Hook 是在事件点自动跑脚本，比如提交前自动格式化。Plugin 是打包分发单位，里面能装 skill、命令、MCP。CLAUDE.md 是每次全量进上下文的项目记忆。

那 Skill 是什么。Skill 是教 Claude 一套流程和专长，把你脑子里那些「遇到这种事该这么干」的程序性知识，沉淀成它命中才加载的肌肉记忆。

关键就在「命中才加载」这五个字。官方文档把这套机制叫渐进式披露，分三层，这是全文最重要的心智模型，我画了张图。

第一层，启动时。Claude Code 只把每个 skill 的 name 加 description（外加 when_to_use）预载进系统提示，不读正文。这些字段在技能列表里截断在 1536 字符 code.claude.com/docs/en/skills，2026-08-17。几十个 skill 摊开也就几 KB，不心疼。

第二层，命中时。Claude 判断当前任务该用哪个 skill，这才去读对应的 SKILL.md 正文。这就是为什么 description 写得烂，skill 永远不触发，因为 Claude 在第一层就把它筛掉了。

第三层，按需读。SKILL.md 里如果引用了捆绑的 reference 文档、scripts 脚本，Claude 真用到了才去读那些文件。

为什么这么设计。说白了就一个字，省 token。你要是把所有规则全塞进 CLAUDE.md，每次对话全量进上下文，又长又贵还稀释注意力。Skill 这套分层，等于让 Claude 随身揣着一套书，但只在需要时翻开对应那一本，翻到哪页读哪页。

别再把什么都往 CLAUDE.md 里塞了。 项目背景、约定这类全局记忆放那没问题，可「遇到 X 情况按 Y 流程走」这种程序性知识，就该做成 skill。

去哪找好 Skill，一份带 star 的精选清单

Agent Skills 已经是开放标准了。2025 年 12 月 18 日发布，Claude Code、Claude.ai、Agent SDK、Developer Platform 都支持，标准站点是 agentskills.io Anthropic 工程博客，2025-12-18。换句话说，你写的 skill 不是绑死在一个工具上，这是我愿意 All in 的前提。

官方 skill 市场装起来最简单，在 Claude Code 里敲两行。

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

官方仓库 anthropics/skills 有 169874 stars，里面 17 个官方示范 skill，包括 frontend-design、docx、pdf、pptx、xlsx、mcp-builder、skill-creator、webapp-testing 这些 gh api 实时，2026-08-17。skill-creator 尤其推荐，它本身就是教你写 skill 的，递归套娃，建议第一个装。

第三方生态我筛了一份经过 star 验证的清单，数字全部是 2026-08-17 当天抓的，不是凭印象。

仓库	Stars	干什么	适合谁
anthropics/skills	169874	官方 17 个示范 skill	所有人，起步必装
obra/superpowers	273037	agentic skills 框架，6.0.3，SDD 子 agent 驱动开发	想让 Claude 自主拆解执行任务的
JuliusBrussee/caveman	98659	省 token，号称砍掉 65% token	token 账单肉疼的
alirezarezvani/claude-skills	24552	345 个 skill 合集，30+ agents	想一次性囤一堆挑着用的
virgiliojr94/book-to-skill	22429	把技术书 PDF 转成 skill	有藏书想喂给 Claude 的
op7418/Humanizer-zh	15476	中文去 AI 味	写中文内容嫌 AI 腔的
trailofbits/skills	6625	安全研究，Trail of Bits 官方	做安全审计的
zarazhangrui/codebase-to-course	5405	代码库转互动课程	做内部培训和 onboarding 的

obra/superpowers 我单独说一句。它是现在最火的 agentic 框架，273037 stars 比官方仓库还高，里面 brainstorming、dispatching-parallel-agents、subagent-driven-development、systematic-debugging、test-driven-development 这一套，是把「先想清楚再动手」的工程纪律硬编码进了 Claude 的工作流。我自己一直在用，后面讲我的技能栈会细说。

安全提醒必须放这。官方工程博客明确说，只装可信来源的 skill，装第三方之前先审计它的捆绑文件、代码依赖、有没有外联网络。一个 skill 能让 Claude 跑 Bash，你等于给了它 shell 权限，别什么野鸡仓库都往里装。

另外你可能没注意，Claude Code 自带了一批 bundled skills，不用装就能用，比如 /doctor 排查环境、/code-review 审当前 diff、/batch 批量处理、/loop 循环跑、/verify 验证改动。官方文档列了 9 个，除了 /doctor 关不掉，其余的能用 disableBundledSkills 配置关。我的建议是先把这批自带的用熟，再考虑装第三方。

10 分钟写第一个能跑的 Skill

讲再多不如亲手写一个。我挑个后端工程师天天用得上的，review-diff，自动审查当前 git diff，总结改动还标风险。零依赖，复制就能跑。

先建目录。skill 放个人级目录 ~/.claude/skills/ 下，所有项目通用，放项目级 .claude/skills/ 就只对当前项目生效。

mkdir -p ~/.claude/skills/review-diff

在这个目录里建 SKILL.md，内容如下。

---
name: review-diff
description: 审查当前 git diff，总结改动逻辑并标出潜在风险，包括空指针、SQL 注入、吞错误、并发问题。当用户说「review 一下改动」「看看这次 diff 有没有问题」「帮我 code review」「审一下这次提交」时使用。
---

# review-diff

你是一个资深代码审查员。按下面步骤工作，不要跳过。

## 步骤

1. 先运行 `git diff --stat` 看改了哪些文件，心里有个数。
2. 再运行 `git diff` 拿完整改动。
3. 按文件输出审查结果，每个文件给三段，改动摘要、风险点、建议。
4. 风险点按严重程度从高到低排，没有风险就直说「没看出明显问题」，别硬凑。

## 重点盯这些

- 空指针和数组、切片越界
- error 返回值被吞掉没处理
- SQL 字符串拼接和未转义的用户输入
- 并发下的共享可变状态
- 该补但漏写的单测

## 输出格式

用中文，简洁。不要复述整段代码，只引用关键行加行号。结尾给一句总体评价。

存盘，不用重启 Claude Code。它监视着 ~/.claude/skills 和项目 .claude/skills 的文件变更，当场生效，这是官方文档明确写的 code.claude.com/docs/en/skills。

怎么测。两种触发方式都试一下。

第一种，自然语言触发。你在项目里改完代码，直接对 Claude 说「帮我 review 一下这次的改动」，它就会读 review-diff 的正文，按里面定义的步骤跑 git diff，然后按文件给你输出风险点。这靠的就是 description 里那句「当用户说......时使用」命中的。

第二种，手动触发。输入 /review-diff，强制调用，不走自动判断。适合你明确知道要用它的时候。

写完别急着扔下。官方工程博客给的迭代方法我觉得特别在理，像带新人一样带你的 skill，观察它真实怎么用。你跑几次就会发现，有时候它漏看了某类风险，有时候步骤跳了，这些都是信号。把它跑对的成功路径、踩过的常见错误，直接回写进 SKILL.md，让它自我沉淀。我那个 review-diff 现在的版本，已经是我跟它来回磨了五六版的结果，比第一版靠谱太多。

就这么简单。一个 skill 的本质就是一个文件夹加一个带 frontmatter 的 markdown，没有魔法。你现在就可以照着这个套路，把你团队 code review 的 checklist、排障的 SOP、发布前的检查清单，一个个沉淀进去。

让 Skill 听话的高级开关

能跑只是第一步，想让 skill 在该触发时触发、不该碰的别碰、还能调子 agent 免授权跑脚本，得靠 frontmatter 里的几个字段。Claude Code 支持的字段有二十多个，我挑最有用的讲。

description 是触发开关，不是说明书

这点我见太多人栽跟头。description 随便写两句「一个有用的代码审查工具」，结果 Claude 永远不自动调它，或者在不该用的时候乱触发。

记住，description 是给 Claude 看的触发器，不是给人看的介绍。要把「做什么」加「什么时候用」写具体，把最关键的用例放前面，因为它在 1536 字符处截断。我上面那个 review-diff 的 description 就是范例，「做什么」一句讲清，「什么时候用」列了四个真实说法。

两个调用控制开关的 2x2

disable-model-invocation 和 user-invocable 这俩布尔值组合起来，决定了 skill 谁能触发。我画了张矩阵图。

两个都不写，默认双方都能触发，Claude 自动判断加用户手动 /name 都行，适合 review-diff 这种通用工具。

disable-model-invocation: true，只允许用户手动触发，Claude 不会自己调。这个一定要给有副作用的 skill 开，比如部署、提交代码、删资源。我见过有人写了个自动部署 skill 没开这个，结果 Claude 判断「代码看起来 ready 了」就自己触发了部署，吓得他连夜回滚。

user-invocable: false，反过来，只允许 Claude 自动触发，对用户隐藏，斜杠菜单里看不到。适合那种后台知识型 skill，比如某个内部框架的编码规范，你不希望用户手动 / 出来，但 Claude 写代码时会自动参考。

两个一起设 true 就没意义了，谁都触发不了，别这么干。

allowed-tools 免授权跑脚本

默认情况下，skill 里让 Claude 跑 Bash，它会弹授权框问你。如果是个你信任的、固定路径的脚本，可以用 allowed-tools 预先放行。

---
name: db-migrate
description: 运行数据库迁移脚本。用户说「跑迁移」「migrate」时使用。
allowed-tools:
  - Bash(${CLAUDE_SKILL_DIR}/scripts/migrate.sh *)
---

${CLAUDE_SKILL_DIR} 是内置变量，指向当前 skill 的目录。这样配置后，Claude 跑这个目录下的 migrate.sh 加任意参数都不弹框，但跑别的 Bash 命令照样要授权。最小权限原则，别一上来放行所有 Bash。

类似的内置变量还有 ${CLAUDE_PROJECT_DIR}、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}，传参用 $ARGUMENTS 或 $1、$2。

子 agent 隔离执行和动态注入

context: fork 让 skill 在一个隔离子 agent 里跑，不污染主对话上下文，跑完把结果带回来。适合那种「读一大堆文件然后给个结论」的任务，比如全仓库搜某个反模式。agent 字段可以指定子 agent 类型，background 默认 true 让它后台跑，需要 v2.1.218 以上 code.claude.com/docs/en/skills，我本机 2.1.233 是支持的。

还有个很骚的操作，动态上下文注入。在 SKILL.md 正文里用反引号前导感叹号，Claude Code 会先执行命令，把输出内联进 skill 正文。

当前工作区相对于 main 的改动如下。

!`git diff --stat main`

请基于以上改动给出审查意见。

每次触发这个 skill，git diff --stat main 的实时输出就被嵌进来了，skill 正文永远是活的。我用它把当前分支名、最近提交、环境信息都自动喂给 Claude，不用每次手动贴。

最后是 paths 字段，填 glob 模式，比如 **/*.go。配上之后，只有你在操作 Go 文件时这个 skill 才会自动加载，进一步省 token 也避免误触发。

有个坑得提醒。如果你打算把 skill 上传到 claude.ai 或者走 Skills API 打包，跨平台标准只认 6 个字段，name、description、license、compatibility、metadata、allowed-tools。你在 Claude Code 里用得好好的 argument-hint、when_to_use、context、agent 这些扩展字段，打包时会硬报错 Unexpected key(s)。本地用随便造，要分发就收敛到这 6 个。

码哥自己的技能栈，实拍不是编的

讲了这么多方法论，亮一下我自己的。我本机 ~/.claude/skills 下 40 个 skill，分四拨。

第一拨是 superpowers 6.0.3 套件，12 个。我用得最重的是 subagent-driven-development 和 dispatching-parallel-agents。写复杂功能时，它先帮我把任务拆成独立子任务，每个子任务丢给一个 fork 子 agent 并行干，干完回收结果。举个真事，上周我给一个老服务加三个独立接口，它直接派了三个子 agent 各写各的，互不干扰，我这边主对话只负责 review 和合并，换以前得串行折腾一下午。还有 systematic-debugging，强制我在改 bug 前先复现、再定位根因、最后才动手，不许瞎试。这套东西本质是把资深工程师的工程纪律，变成了 Claude 不会偷懒跳过的流程。

第二拨是我自研的内容生产链，it-article-producer、paid-column-writer、video-producer、tech-hv-research。你现在看的这篇文章，就是 it-article-producer 这个 skill 从选题到出稿全流程跑出来的，它定义了支柱配比、研究深度、写作风格、四层自检。没有这些 skill，我每周的更新量至少砍掉一半。说实话，这是我感受到「杠杆」最强的地方，我把自己大半年摸索的写作 SOP 沉淀进去，Claude 就能按我的标准稳定产出，而不是每次重新教一遍。

第三拨是图表和前端，fireworks-tech-graph 画技术架构图、excalidraw-diagram 画手绘风流程图、frontend-slides 做 HTML 幻灯片。这篇文章里的两张配图就是走的这个链路。以前画张图得开各种工具拖半天，现在一句话描述，SVG 直接出。

第四拨是官方和通用，docx、pdf、pptx、xlsx 处理文档，mcp-builder 写 MCP server，skill-creator 帮我迭代新 skill。这拨随用随取，不展开。

这 40 个 skill 不是一天装的，是这大半年遇到一个重复痛点就沉淀一个。这才是 Skill 的正确用法，不是囤货，是把你自己踩过的坑、走过的流程，一个个变成 Claude 的肌肉记忆。

六条避坑清单

最后收个口，把我踩过和见过的坑列成清单，你照着躲。

第一，description 别含糊。它是触发器，写得笼统要么不触发要么乱触发。做什么加什么时候用，具体说法列出来，关键用例放前 1536 字符。

第二，Skill 不替代 MCP。官方工程博客说得很明白，两者互补。MCP 接工具和数据，给 Claude 手脚。Skill 教流程和专长，给 Claude 脑子。未来 Skill 会教 agent 怎么编排 MCP 工具，不是谁干掉谁。

第三，别把所有规则塞 CLAUDE.md。全局背景放那，程序性的、按需用的东西做成 skill，否则每次对话全量加载，又贵又稀释注意力。

第四，有副作用的 skill 一定开 disable-model-invocation: true。部署、提交、删库这类操作，只允许手动 /name 触发，别给 Claude 自作主张的机会。

第五，要跨平台分发就收敛字段。claude.ai 和 Skills API 只认 6 个标准字段，多写硬报错。本地用可以玩花活，上传前记得裁。

第六，注意作用域优先级。企业级大于个人级 ~/.claude/skills/ 大于项目级 .claude/skills/。plugin skill 用 plugin:skill 命名空间不冲突。你要是发现 skill 行为不对，先排查是不是同名被高优先级的覆盖了，我在这上面浪费过半小时。

常见问题

Q1，Skill 和 MCP 先学哪个？

先学 Skill。MCP 是写代码接外部系统，有一定门槛。Skill 就是写 markdown，今天看完就能上手。等你 skill 写顺了，发现需要连数据库、调内部接口了，再上 MCP，那时候 skill 还能反过来教 Claude 怎么用你的 MCP 工具。

Q2，个人 skill 还是项目 skill 怎么选？

跨项目通用的放个人级 ~/.claude/skills/，比如我的 review-diff、画图类。跟具体项目绑定的放项目级 .claude/skills/，比如某个仓库的发布流程、编码规范，可以提交进 git 跟团队共享。注意优先级，企业大于个人大于项目，同名会覆盖。

Q3，skill 装多了会不会拖慢、费 token？

不会。启动只加载每个 skill 的 name 和 description，几十上百个也就几 KB。只有命中的 skill 才读正文，而且正文里的捆绑文件还是按需读。真正费 token 的是你把所有规则全塞进 CLAUDE.md 每次全量加载。放心装，别装来路不明的就行。

Q4，不会写代码能做 skill 吗？

能。skill 的本体是 markdown，写的是流程和规范，不一定要带脚本。比如「我们团队 code review 要检查这 10 项」就是一个纯文本 skill，Claude 照着做。等你进阶了，再用 allowed-tools 绑定脚本做自动化。

Q5，团队怎么共享 skill？

两种。轻量的直接把 skill 目录提交到项目的 .claude/skills/，大家 pull 下来就有。正规的用 plugin 打包，走 /plugin marketplace add 分发，还能带上 MCP 配置和子 agent，适合公司级统一推广。

写在最后

我用 Claude Code 这大半年，最大的体会不是模型有多强，而是谁能把自己的经验沉淀成 skill，谁的杠杆就比别人大一个数量级。

模型是大家共用的脑子，但 skill 是你私有的肌肉记忆。你踩过的坑、你团队的规范、你反复走的流程，这些才是真正的护城河。裸用 Claude Code 就像雇了个聪明但啥都不懂的新人，每次都得从头教。装好 skill，你雇的是一个带全套 SOP 上岗的熟手。

这件事越早开始越划算。今天就照着上面那个 review-diff，写你自己的第一个 skill，从你最烦的那件重复劳动下手。

下篇我打算拆 MCP 和 Skill 怎么配合，把内部系统真正接进 Claude Code，让它不光会改代码，还能查日志、提单子、发部署。感兴趣的话点个关注，再顺手给公众号加个星标，这样更新不会被淹没。你身边要是有人天天跟 Claude Code 死磕还只会用聊天框，这篇可以直接甩给他。