Claude Code Skills 实战：把重复流程打包成技能卡

生命不息，折腾不止。CLAUDE.md 塞不下的操作流程，交给 Skills 按需加载——平时零成本，想用就 / 一声。

一、Skills 到底是啥：一张「用的时候才读」的技能卡

上一篇文章我们把大任务拆给了 Subagents 并行小队。但还有一种尴尬场景 Subagents 救不了：你手里攥着几段「规矩」——比如「提交信息必须走 Conventional Commit 格式」「发布前要跑哪几个检查」——它们不是独立任务，而是散落在主对话里的操作规范。写进 CLAUDE.md？每一条都常驻上下文，白占 token；贴在便签里？每次要干活都得重新贴一遍。

Skills 就是为这个场景生的。

一个 Skill 的物理形态简单到离谱：一个文件夹，里面一个 SKILL.md。上半段 YAML frontmatter 写「我是谁、什么时候用我」，下半段 Markdown 写「真用到我的时候该怎么做」。没有安装器、没有构建步骤、没有注册表——把文件夹放进对的位置，Claude Code 就能用了。

它真正值钱的地方在**渐进式披露（Progressive Disclosure）**这套机制：

第一层：所有 skill 的 name + description 会常驻在系统提示词里。Claude 一开机就知道「你有一张叫 conventional-commit 的卡，用来规范提交信息」这行简介。
第二层：只有当你的需求真对上了，Claude 才把 SKILL.md 的完整正文拉进上下文，照着执行。

也就是说，一百张技能卡平时只花一百行简介的成本，用到哪张才掏哪张的全文。这跟 CLAUDE.md「进了门就全职驻场」是两种完全不同的哲学。

顺便把几个容易混淆的零件对齐一下：

零件	位置	触发方式	适合什么
CLAUDE.md	项目根目录	常驻	项目背景、铁律
Subagents	`.claude/agents/*.md`	主对话派发	独立的大块任务
Skills	`.claude/skills/*/SKILL.md`	自动匹配或 `/名字`	可复用的多步骤流程
Slash Commands	`.claude/commands/*.md`	手动 `/命令`	快捷提示词

一句话分清：Subagents 是「再雇个人」，Skills 是「翻出说明书照着做」。

二、手把手写第一张技能卡：提交信息规范化

先挑个每天都会撞上的场景练手：让 Claude 每次提交都按 Conventional Commit 规范写 commit message。老样子，从项目根目录开始：

1	mkdir -p .claude/skills/conventional-commit

然后在这个目录里建 SKILL.md，内容如下：

---
name: conventional-commit
description: 当用户要求提交代码、写 commit message、或做 git commit 时使用。按 Conventional Commit 规范书写提交信息。
---

写 git commit message 时遵守以下规则：
1. 开头用以下类型之一：feat、fix、chore、docs、refactor、test、perf
2. 冒号加空格后，写一句命令式的简短总结，结尾不加句号
3. 主题不超过 70 个字符
4. 如果改动涉及两个以上文件，加一行 body 说明「为什么改」

示例：
feat: add IndexNow ping to publish workflow

搞定。下次你直接说「把改动提交一下」，Claude 就会自动匹配到这张卡，照着格式写 message，不用你再啰嗦一遍规范。也可以手动触发：/conventional-commit。

说明：官方文档里示例多写成英文 description，因为它是给 Claude 做意图匹配用的；中文完全没问题，Claude 多语言都认。关键是 description 要写得「像一个触发条件」，别写成一堆形容词。

这卡怎么装在哪？ Skills 有三个落点，作用域不同：

1
2
3

~/.claude/skills/<name>/SKILL.md        # 个人级：所有项目都能用
.claude/skills/<name>/SKILL.md          # 项目级：只在这个仓库生效
<plugin>/skills/<name>/SKILL.md         # 插件级：随插件分发

个人级和项目级同名时会冲突，优先级是「企业 > 个人 > 项目」，都能覆盖内置 skill（比如项目里放一个 code-review，会顶掉内置的 /code-review）。

三、frontmatter 逐行拆：怎么写才能被精准触发

frontmatter 是这张卡的「控制面板」，决定它什么时候被激活、能用哪些工具。核心字段如下：

---
name: summarize-changes            # 必填，显示名（小写字母/数字/连字符）
description: 用户询问当前改了什么、或要求总结未提交变更时使用。拉取工作区实时 diff 做摘要。  # 必填，触发匹配的关键
allowed-tools: "Read, Grep, Bash(git status:*), Bash(git diff:*)"  # 可选，本回合免确认的工具
disallowed-tools: "AskUserQuestion"  # 可选，本回合禁用的工具
model: claude-sonnet-4-20250514    # 可选，限定只能用某模型跑
disable-model-invocation: true     # 可选，禁止 Claude 自动触发，只能你手动 /名字
---

逐条说透：

name：必填。这里有一个新手超容易踩的坑——个人/项目级 skill 的命令名其实来自「目录名」，不是 frontmatter 里的 name。name 只作为列表里的显示标签。目录叫 conventional-commit，命令就是 /conventional-commit。
description：必填，也是「触发命中率」的天花板。好的写法是第三人称 + 动词开头 + 明确触发场景，比如「当用户要求跑测试、检查测试、或验证测试是否通过时使用」。写成一个笼统的「一个万能的编程助手」基本不会自动触发。读出来自检一遍：如果它不是以一个动词开头、以一个具体场景结尾，就重写。
allowed-tools：预授权。逗号或空格分隔，也可以用 YAML 列表。可以精细到具体子命令："Read, Grep, Bash(git log:*)"。授权只在本回合生效，你发下一条消息就清空。注意：这玩意能绕过常规权限确认，所以要跑第三方仓库里带 skill 的代码前，先瞄一眼它的 allowed-tools 都开了啥。
disallowed-tools：反过来，把某些工具从 Claude 的可用池里拿掉，适合那种「后台自动跑、不该反过来问你」的技能。
disable-model-invocation：设成 true 后 Claude 就不能自己判断「该用了」，只能你手动 /名字 触发。适合纯背景资料类的卡。

四、进阶：挂脚本、带参考文件、跑评估

单文件 SKILL.md 能干的活有限，官方推荐的结构是「主卡 + 按需加载的支持文件」：

my-skill/
├── SKILL.md          # 必填：概述 + 导航
├── reference.md      # 详细 API 文档，需要时才加载
├── examples.md       # 用法示例
└── scripts/
    └── helper.py     # 工具脚本，执行而不是加载

这里透出的思路还是渐进式披露的延伸：把长文档拆成 reference、examples，正文里指向它们，Claude 需要时再翻，主卡永远清爽。

再往上一步，skill 能打包脚本去干活。比如一张「生成依赖关系可视化」的卡，正文里写「跑 scripts/gen_graph.py，把输出的 HTML 交给用户」，Claude 负责编排、脚本负责执行，能实现纯提示词做不到的事（画图、出报告、调 API）。

想要「科学地」验证一张卡写得好不好，装官方的评估插件：

1	/plugin install skill-creator@claude-plugins-official

它会在 Claude Code 里自动搭好「写卡 → 跑任务 → 看效果 → 回头改」的对比循环，不用你手动人肉试。

最后提醒一句成本：每个 skill 的 name + description 都会在每个 turn 常驻上下文，卡多了积少成多。跑一下 /skill-doctor，它会告诉你每张卡占了多少、被用过几次，没被用过的可以直接关掉（在 settings.json 的 skillOverrides 里设 off）。

五、踩坑清单：这几个坑我替你趟过了

skill 死活不触发：八成是 frontmatter YAML 写坏了。坏了的话 Claude Code 会带着空 metadata 加载正文，/名字 还能用，但 Claude 没有 description 可匹配，自动触发就废了。加 --debug 跑一次能看到解析报错。
命令名对不上：说了第二遍——命令名来自目录名，不是 frontmatter 的 name。目录 conventional-commit，别指望 /feat-commit 这种。
新建的顶层 skills 目录不生效：如果在会话开始前 .claude/skills/ 这个目录根本不存在，会话里新建的第一个文件它监测不到，重启 Claude Code 就好。已经存在的目录里加/改/删卡片，一般是热加载、不用重启。
description 被截断：skill 很多时，列表为了省 token 会截短 description，可能把触发用的关键词截没了。预算默认是模型上下文的 1%，可以调 skillListingBudgetFraction 设置（比如 0.02）或 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量拉高。
allowed-tools 是双刃剑：它能让后台流程不打断你，但也等于给 skill 开了免确认通道。审第三方 skill 先看这格。