## 概述 本教程带你从零构建一个**提交信息生成 Skill（commit-message generator）**——它会读取你暂存的代码变更，自动产出符合 Conventional Commits 规范的提交信息草稿。借此案例，你将完整掌握 Claude Code Skill 的核心机制：`SKILL.md` 的 YAML frontmatter、渐进式披露（progressive disclosure）、脚本封装与触发调试。适合已能基本使用 Claude Code、想封装第一条自定义能力的中级读者。 ## 前置条件 - 已安装 Claude Code（`claude --version` 可正常输出） - 已安装 Git 且本地有一个可提交的代码仓库 - 了解 Conventional Commits 规范的基本概念（`feat: / fix: / docs:` 等） - 一台 macOS / Linux / WSL 终端（Windows 原生 CMD 部分脚本语法需调整） --- ## 第一步：搞清楚 Skill 到底是什么 很多人把 Skill、Slash 命令、MCP、CLAUDE.md 混为一谈。先花一分钟厘清边界，后面才不会选错工具： | 能力载体 | 本质 | 加载时机 | 适合场景 | |---------|------|---------|---------| | **CLAUDE.md** | 静态上下文/规则 | 每次会话全量注入 | 团队规范、编码风格、常驻约束 | | **Slash 命令** | 一段提示词的快捷方式 | 用户主动输入 `/xxx` | 固定流程的提示词复用 | | **MCP 服务器** | 外部工具/数据源协议 | 显式连接后可调用 | 接入数据库、API、第三方系统 | | **Skill** | 文件系统能力包 | Claude 按语义**自动判断**是否加载 | 可复用的、有步骤的专业工作流 | 关键差异：**CLAUDE.md 是"总在场"的背景，而 Skill 是"按需登场"的专家**。Skill 的精髓在于 *progressive disclosure*——平时只把一段 `description` 摆在货架上，Claude 判断"现在需要这位专家"时，才把整本"操作手册"加载进上下文。这正是它比把所有规则塞进 CLAUDE.md 更省 Token、更精准的原因。 > 一句话记忆：CLAUDE.md 是公司的《员工手册》，Skill 是你随叫随到的「外包专家」，Slash 命令是你按下的「快捷按钮」，MCP 是接进系统的「外接设备」。 ## 第二步：为什么拿"提交信息生成"练手 选择第一个实战 Skill 有三个标准：**高频、自包含、可验证**。提交信息生成完美命中： - **高频**：每个开发者每天写无数次 commit，痛点真实 - **自包含**：只需 `git diff`，不依赖任何外部 API，离线可跑 - **可验证**：产出物（commit message）有明确规范（Conventional Commits），对错一眼可判 更重要的是，它能完整覆盖一个 Skill 的所有要素：需要脚本提取 diff、需要参考资料记录 type 列表、需要正文指导 Claude 如何组织语言、需要 frontmatter 让 Claude 在合适时机自动触发——麻雀虽小，五脏俱全。 ## 第三步：创建项目骨架 Skill 可以放在两个位置： - **用户级**：`~/.claude/skills//SKILL.md`——所有项目可用 - **项目级**：`.claude/skills//SKILL.md`——仅当前仓库可用 我们做的是一个通用工具，放用户级最合适。先建目录： ```bash mkdir -p ~/.claude/skills/commit-message/scripts mkdir -p ~/.claude/skills/commit-message/references ``` 最终目录结构如下： ``` ~/.claude/skills/commit-message/ ├── SKILL.md # 入口文件（必需） ├── scripts/ │ └── staged-diff.sh # 提取暂存区差异的脚本 └── references/ └── conventional-commits.md # 规范速查（按需加载） ``` > **常见问题**：目录名必须和 frontmatter 里的 `name` 字段一致，且只能是**小写字母、数字、连字符**（kebab-case），最长 64 字符。写成 `commit_message` 或 `CommitMessage` 都会导致加载失败。 ## 第四步：编写 SKILL.md 的 frontmatter `SKILL.md` 顶部是一段 YAML frontmatter，用 `---` 包裹。其中只有两个字段是必填且决定生死的：`name` 和 `description`。 ```yaml --- name: commit-message description: 生成符合 Conventional Commits 规范的 Git 提交信息。当用户准备提交代码、 询问"该怎么写 commit message"、"帮我写提交信息"、暂存了变更想总结改动， 或者在提交前想确保信息规范时使用。读取暂存区的 git diff，产出可直接复制的 提交信息草稿，包含 type、scope、subject 与可选的 body。 --- ``` 这里有一个反直觉但至关重要的设计：**`description` 的写法直接决定 Skill 能否被触发**。Claude 不会看到你的正文，它只看这段描述来决定"要不要请这位专家出场"。所以好的 `description` 必须同时回答两个问题： 1. **这个 Skill 干什么**（What） 2. **什么情况下该用它**（When） 写 `description` 的三条经验法则： - **列出触发短语**：把用户可能说的话写进去——"帮我写提交信息"、"该怎么 commit"、"总结一下这次改动" - **描述能力边界**：明确它能做什么、不能做什么，避免误触发 - **控制在 1024 字符内**：超长会被截断，关键信息放前面 > **常见问题**：把 `description` 写成 `"一个关于提交的工具"` 这种废话——Claude 永远不知道何时该调用它。务必具体到"什么场景 + 产出什么"。 ## 第五步：编写正文指令（渐进式披露的灵魂） frontmatter 之下就是 Markdown 正文。**正文要精简**——官方建议控制在 500 行以内。原则是：让 Claude 一眼读懂工作流，细节丢给脚本和参考资料。 ```markdown # 提交信息生成 ## 何时使用 用户准备 `git commit`、询问如何写提交信息、或希望总结暂存的改动时。 ## 工作流程 1. 运行 `scripts/staged-diff.sh` 获取当前暂存区的变更摘要 2. 如果暂存区为空，提示用户先 `git add`，不要自行 add 3. 分析变更，判断本次提交的主导 type（参考 `references/conventional-commits.md`） 4. 产出提交信息，格式：`(): ` 5. 把信息展示给用户，**只生成草稿，绝不自动执行 commit** ## 输出规范 - subject 用祈使句、现在时，首字母小写，结尾不加句号，不超过 50 字符 - 当改动跨多个不相关模块时，建议拆分为多条提交信息而非一条大杂烩 - body 只在有非显而易见的背景时才写，每行不超过 72 字符 ## 重要约束 - **只读 git diff，只生成建议**：任何 `git commit`、`git push` 都必须由用户确认后手动执行 - 不要为了凑 type 而强行归类；实在无法判断就用 `chore` ``` 注意最后那条"重要约束"——这与"不要自动 commit"的工程纪律完全一致。Skill 的正文里要明确写死这类护栏，避免 Claude 自作主张。 > **常见问题**：把所有 Conventional Commits 的细则全塞进正文——会让 SKILL.md 臃肿、每次加载都烧 Token。正确做法是把完整规范放进 `references/`，正文里只留"按需查阅"的指引。这就是渐进式披露。 ## 第六步：封装脚本（bundled vs separated） Skill 里的脚本分两种风格，要按复杂度选择： - **内联脚本（bundled）**：直接在 SKILL.md 里用反引号或 ` ```bash ` 代码块写命令。适合 1~3 行的简单逻辑。 - **分离脚本（separated）**：独立成文件放在 `scripts/`，正文里用路径引用。适合多步骤、可复用、需要单独测试的逻辑。 提取暂存区差异是典型的"分离脚本"场景——它有健壮性处理（空暂存区、二进制文件），值得独立成文件。新建 `scripts/staged-diff.sh`： ```bash #!/usr/bin/env bash # 提取暂存区的变更摘要，供提交信息生成使用 set -euo pipefail # 确认处于 git 仓库 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo "ERROR: 当前目录不是 git 仓库" >&2 exit 1 fi # 获取暂存区变更的文件名清单（带状态码） staged_files=$(git diff --cached --name-status) if [ -z "$staged_files" ]; then echo "NOTICE: 暂存区为空，请先 git add 需要提交的文件。" exit 0 fi echo "===== 暂存文件清单 =====" echo "$staged_files" echo "" echo "===== 变更统计 =====" git diff --cached --stat echo "" echo "===== 实际差异（截断超长内容）=====" git diff --cached | head -200 ``` 赋可执行权限（**这一步常被遗漏**，会导致 Skill 调用时脚本报权限错误）： ```bash chmod +x ~/.claude/skills/commit-message/scripts/staged-diff.sh ``` 单独测试脚本，确认能跑： ```bash cd ~/your-project git add some-file.py bash ~/.claude/skills/commit-message/scripts/staged-diff.sh ``` **预期结果**：依次输出文件清单、变更统计、实际差异内容三段。若暂存区为空，则输出提示并正常退出。 ## 第七步：准备按需加载的参考资料 `references/conventional-commits.md` 是 Skill 的"工具书"，平时不加载，只有 Claude 需要判定 type 时才翻开。内容保持速查风格： ```markdown # Conventional Commits 速查 ## type 取值 - feat: 新功能（用户可感知） - fix: Bug 修复 - docs: 仅文档变更 - style: 代码格式（不影响逻辑：空格、分号等） - refactor: 既非新增功能也非修 Bug 的重构 - perf: 提升性能的改动 - test: 增加/修改测试 - build: 构建系统或外部依赖（webpack、npm 等） - ci: CI 配置文件与脚本 - chore: 杂项（不修改 src 或测试的其他改动） - revert: 回退某次提交 ## 格式 (): <空行> <空行>