Skill：把重复流程变成一条命令

小周每次发版前都要在 Claude Code 里粘贴同一段话：「看一下上个 tag 以来的提交，按新功能、修复分类，用中文写成面向用户的更新说明，追加到 CHANGELOG.md 顶部，别把 CI 配置的改动写进去……」这段话已经粘了十几次，每次还会漏掉一两条要求。

把它写进 CLAUDE.md？可这段内容一个月只用两次，却要在每个会话里占着上下文。这正是 Skill 要解决的问题：把反复使用的流程或资料打包起来，需要时用一条 /命令 调出来，不需要时几乎不占空间。

Skill 是什么

一个 Skill 就是一个目录，里面至少有一个 SKILL.md 文件。文件分两部分：开头 --- 之间的 YAML 前置信息（frontmatter），告诉 Claude 这个 Skill 叫什么、什么时候用；后面是 Markdown 正文，写 Claude 执行时要遵循的指令。

调用方式有两种：你在消息开头输入 /skill-name 直接调用，或者 Claude 发现你的请求和 Skill 的描述匹配时自动加载。Claude Code 的 Skill 遵循 Agent Skills 开放标准，同一份 Skill 在其他支持该标准的工具里也能用（部分字段是 Claude Code 独有的扩展）。

放在哪里

同名时，企业级优先于个人级，个人级优先于项目级；插件 Skill 带命名空间，不会冲突。命令名默认取目录名，也可以用前置信息里的 name 指定。

Claude Code 会监听这些目录，会话中新增或修改 SKILL.md 立即生效，不用重启。只有当你新建了一个会话启动时还不存在的顶层 skills 目录，才需要运行 /reload-skills。输入 /skills 可以列出当前所有 Skill，按 t 还能按 token 数排序。

前置信息：常用字段

所有字段都是可选的，但官方强烈建议写 description。字段名必须完全一致，写错了不会报错，只会被悄悄忽略。

正文里还能用几种替换：$ARGUMENTS 是调用时跟在命令后面的全部参数，$0、$1 按位置取单个参数，${CLAUDE_SKILL_DIR} 是 Skill 所在目录，方便引用附带的脚本。以 !`命令` 开头的写法叫动态上下文注入：Claude Code 会先在本机执行这条命令，把输出替换进正文，Claude 看到的就是真实数据而不是命令本身。

按需加载：为什么 Skill 几乎不占地方

这是 Skill 和 CLAUDE.md 最大的区别：

会话开始时，Claude 只看到每个 Skill 的名字和简短描述；正文、参考资料、脚本都留在磁盘上，用到才读。所以一份上千行的 API 规范做成 Skill，平时几乎不花成本。

调用之后，渲染好的 SKILL.md 正文会作为一条消息留在对话里，后续轮次不会重新读文件。上下文被压缩时，每个 Skill 只保留开头的 5000 token，所以最重要的指令要写在 SKILL.md 前面。有副作用的流程，比如部署、发消息、打 tag，务必加 disable-model-invocation: true，你不会希望 Claude 觉得「代码看起来差不多了」就自己去部署。

Skill、CLAUDE.md、斜杠命令各管什么

判断起来很简单：每次都需要知道的写 CLAUDE.md；偶尔需要、或者是一套操作步骤的做成 Skill；必须保证执行、不能靠模型自觉的写成 hook（见第 7 课Hooks 自动化）。官方给的信号也很实用：同一段流程第三次粘贴进聊天，或者 CLAUDE.md 里某一节已经从「事实」长成了「操作步骤」，就该把它挪成 Skill。

手把手：写一个中文发版说明 Skill

目标：输入 /changelog-zh v1.4.0，Claude 读取上一个 tag 之后的提交，按模板生成中文发版说明，追加到 CHANGELOG.md 顶部。

第 1 步：建目录。 这是项目相关的流程，放在项目里，团队都能用：

mkdir -p .claude/skills/changelog-zh

第 2 步：写 SKILL.md。 保存为 .claude/skills/changelog-zh/SKILL.md：

---
name: changelog-zh
description: 根据上一个 tag 之后的 git 提交，生成面向用户的中文发版说明并写入 CHANGELOG.md。用于发版、写更新日志时。
argument-hint: "[版本号，如 v1.4.0]"
disable-model-invocation: true
allowed-tools: Bash(git log *) Bash(git describe *)
---

为版本 $ARGUMENTS 生成中文发版说明。

## 仓库现状
- 最近的 tag：!`git describe --tags --abbrev=0 || echo "（还没有 tag）"`

## 步骤
1. 运行 `git log <最近的 tag>..HEAD --no-merges --pretty=format:"%h %s"` 获取提交；没有 tag 时取最近 50 条。
2. 按 feat → 新功能、fix → 问题修复、perf → 性能优化分类，其余归入「其他改动」。
3. 去掉对用户没有影响的提交：ci、chore、仅改文档或测试的提交。
4. 每条用用户能看懂的话重写，不出现函数名，末尾保留短 hash。
5. 按 [template.md](template.md) 的格式输出，先给我看，确认后再插入 CHANGELOG.md 顶部。

## 规则
- 没有给出版本号时，先问我，不要自己编。
- 不要修改 CHANGELOG.md 里已有的历史内容。

第 3 步：加一个支持文件。 在同一目录新建 template.md：

## 版本号（发布日期 YYYY-MM-DD）

### 新功能
- 一句话说明用户能做什么新事情（abc1234）

### 问题修复
- 一句话说明修好了什么现象（def5678）

### 其他改动
- 性能、依赖升级等（9a8b7c6）

SKILL.md 里用链接指向它，Claude 需要时才去读。官方建议 SKILL.md 控制在 500 行以内，更长的参考资料、示例都拆成支持文件。

这份 Skill 里有几个刻意的设计：

• disable-model-invocation: true：写文件、发版这类有副作用的事，只在你说要做的时候做；
• 动态注入：!`git describe ...` 在 Claude 看到正文之前就执行，它拿到的是真实的 tag。注意注入的命令一旦以非零码退出，整个 Skill 调用会失败，所以加了 || echo 兜底，覆盖仓库还没有 tag 的情况；
• allowed-tools：只在这一轮免确认 git log 和 git describe，你发下一条消息后就失效，不会长期放宽权限；
• 先展示、后写入：生成的说明先给你审，再落盘。

第 4 步：测试。

> /skills
# 列表里应能看到 changelog-zh，没有的话检查目录名和 SKILL.md 第一行是否是 ---
> /changelog-zh v1.4.0
  Bash git log v1.3.2..HEAD --no-merges --pretty=format:"%h %s"
⏺ 共 23 条提交，过滤掉 7 条 ci / chore 提交后，整理如下：
  ## v1.4.0（2026-10-25）
  ### 新功能
  - 订单列表支持按退款状态筛选（a1c93e2）
  ...
⏺ 确认无误的话，我把它插入 CHANGELOG.md 顶部。

第 5 步：迭代。 不满意就直接改 SKILL.md，保存后在同一会话里再调用一次就能看到效果。如果 Skill 本该被自动调用却没触发（没设 disable-model-invocation 的那类），先检查 description 里有没有用户自然会说的关键词；反过来触发太频繁，就把描述写得更具体。

动手：把你自己的重复流程做成 Skill