前言
上一篇我们了解了 Skills 的概念。这一篇，我们来真枪实弹地从零到一创建一个生产可用的 Skill。
目标：创建一个 /commit-msg 命令，自动分析 Git 变更并生成符合 Conventional Commits 规范的提交信息。
一、环境准备
确保你已安装 Claude Code：
# 安装（需要 Node.js 18+）
npm install -g @anthropic-ai/claude-code
# 验证
claude --version
# 启动（在你的项目目录下）
cd my-project
claude
二、理解 SKILL.md 的每个字段
在动手之前，先把 SKILL.md 的配置项吃透：
---
name: skill-name # 斜杠命令名称，/skill-name 触发
description: "..." # 自动触发的语义描述（最关键！）
allowed-tools: [Read, Bash] # 允许使用的工具列表
user-invocable: true # true = 出现在 /help 列表中
disable-model-invocation: false # true = 禁止自动触发
---
description 字段写法技巧
这是整个 Skill 最重要的字段，决定了自动触发的准确度：
不好的写法：
description: 生成提交信息
好的写法：
description: 分析 Git 暂存区变更，生成符合 Conventional Commits 规范的提交信息。当用户提到"提交信息"、"commit message"、"git commit"、"帮我写提交"时触发。限制在 200 字符以内。
规律：描述你的工具做什么 + 用户可能怎么说 + 限制条件。
allowed-tools 可选工具清单
| 工具 | 功能 |
|---|---|
Read | 读取文件内容 |
Write | 写入文件 |
Edit | 编辑文件 |
Bash | 执行 Shell 命令 |
Grep | 在文件中搜索内容 |
Glob | 文件模式匹配查找 |
WebFetch | 获取网页内容 |
WebSearch | 网络搜索 |
安全原则：只授权 Skill 真正需要的工具，不要图省事全部开放。
三、手把手：创建 commit-msg Skill
步骤 1：创建目录结构
# 在项目根目录下
mkdir -p .claude/skills/commit-msg
步骤 2：编写 SKILL.md
创建 .claude/skills/commit-msg/SKILL.md：
---
name: commit-msg
description: 分析 Git 暂存区的变更内容，自动生成符合 Conventional Commits 规范的提交信息。当用户说"帮我写提交信息"、"生成 commit message"、"git commit 怎么写"时触发。
allowed-tools: [Bash, Read]
user-invocable: true
---
## 任务说明
你的任务是分析当前 Git 暂存区的变更，生成一条专业、准确的提交信息。
## 执行步骤
1. 运行 `git diff --staged` 获取暂存区变更详情
2. 运行 `git diff --staged --stat` 获取变更文件列表
3. 分析变更的性质和影响范围
4. 生成符合 Conventional Commits 规范的提交信息
## Conventional Commits 规范
格式：`<type>(<scope>): <description>`
### 类型（type）说明
| 类型 | 适用场景 |
|------|---------|
| feat | 新功能 |
| fix | Bug 修复 |
| docs | 文档变更 |
| style | 代码格式（不影响逻辑） |
| refactor | 重构（不是新功能，也不是修复） |
| perf | 性能优化 |
| test | 添加/修改测试 |
| chore | 构建配置、依赖更新等杂项 |
| ci | CI/CD 配置修改 |
### 规范要求
- 标题行（type + scope + description）不超过 72 字符
- 使用英文，动词用祈使句（Add, Fix, Update，而非 Added）
- scope 使用小写，表示影响范围（如 auth, api, ui, db）
- 如有重大变更，正文中注明 `BREAKING CHANGE: <说明>`
## 输出格式
直接输出可用的提交信息，格式如下：
<提交标题>
<如有必要，输出 1-3 句正文说明变更原因和影响>
同时提供 2-3 个备选方案，供用户选择。
步骤 3：验证结构
ls .claude/skills/commit-msg/
# 输出：SKILL.md
步骤 4：在 Claude Code 中测试
先暂存一些变更：
git add src/auth/login.ts
然后在 Claude Code 中：
/commit-msg
或者直接说：
帮我写一下这次的提交信息
Claude 会自动运行 git diff --staged，分析变更，输出类似：
主要方案：
feat(auth): add JWT token refresh mechanism
Add automatic token refresh logic to prevent session expiration.
Implements sliding window expiration with 7-day maximum lifetime.
备选方案：
- feat(auth): implement token refresh for better UX
- feat(auth): add auto-renewal for expired JWT tokens
四、常见问题排查
问题 1：斜杠命令不出现在 /help 列表中
原因：会话启动后修改了 SKILL.md，Skills 在会话开始时快照，不会热更新。
解决：退出 Claude Code，重新进入。
exit # 或 Ctrl+C
claude # 重新启动
问题 2：自动触发失效，每次都要手动 /skill-name
原因：description 描述不够精准，没有覆盖用户实际的表述方式。
解决：在 description 中加入更多触发短语：
description: 生成 Git 提交信息。触发词：提交信息、commit message、git commit、帮我提交、写 commit、conventional commits。
问题 3：YAML 前置配置报错
原因：YAML 格式错误，常见于引号未闭合、缩进不一致。
调试方法：
# 在线验证 YAML（复制内容到 yaml-lint.com）
# 或本地安装验证工具
npm install -g js-yaml
node -e "require('js-yaml').load(require('fs').readFileSync('.claude/skills/commit-msg/SKILL.md', 'utf8').split('---')[1])"
问题 4：Bash 工具被拒绝执行
原因：权限设置问题，git 命令未被允许。
解决：在 .claude/settings.json 中配置：
{
"permissions": {
"allow": [
"Bash(git diff*)",
"Bash(git log*)",
"Bash(git status*)"
]
}
}
五、进阶：为 Skill 添加支撑文件
当 Skill 变复杂时，可以添加支撑文件：
.claude/skills/commit-msg/
├── SKILL.md # 核心指令
├── examples/ # 示例文件
│ ├── good-commits.md # 好的提交信息示例
│ └── bad-commits.md # 反例
└── templates/ # 模板
└── breaking-change.md # Breaking Change 模板
在 SKILL.md 中引用：
## 参考示例
参见 `examples/good-commits.md` 中的优质提交信息示例。
当涉及 Breaking Change 时，使用 `templates/breaking-change.md` 的格式。
六、将 Skill 分享给团队
把 .claude/skills/ 目录提交到 Git：
git add .claude/skills/
git commit -m "chore: add Claude Code skills for team workflow"
git push
团队成员拉取代码后，Claude Code 会自动读取并加载这些 Skills，无需任何额外配置。
七、从社区安装现成 Skill
不想从零写？直接用社区的：
# 安装提交信息生成 Skill
npx skills add community/commit-helper
# 安装代码审查 Skill
npx skills add anthropics/code-reviewer
# 查看已安装的 Skills
npx skills list
八、本篇小结
我们完成了：
- ✅ 理解 SKILL.md 每个字段的含义
- ✅ 创建完整的 commit-msg Skill
- ✅ 掌握常见问题的排查方法
- ✅ 了解多文件 Skill 结构
- ✅ 学会团队共享和社区 Skill 安装
下一篇我们将深入 CLAUDE.md 与配置体系，掌握 settings.json 的权限管理和环境变量配置。
