从零到一：手撸一个让队友追着夸的 Claude Skill
📖 前置阅读：《Claude Skills 入门指南》
前言：一个让我每天节省10分钟的小发明
我们团队有个规定：commit message 必须按规范来。格式是<type>(<scope>): <subject>，类型只能是 feat/fix/docs 那一套。
理想很丰满。
现实是——总有人写"修了个bug"、“update”、甚至"111"（对，就是三个1）。每次Code Review我都要花时间纠正这些"灵魂commit"，暴躁（peace🤒）。
后来我花了20分钟，给 Claude 写了一个 Skill。
现在？我只要说一句"帮我写个commit message"，它就能自动分析 git diff，输出规范的提交信息。每天省下来的吐槽时间，起码能多喝两杯咖啡。
今天，我就手把手带你复刻这个 Skill。
完成后你会获得：
- 一个真正能用的 Git Commit 助手
- 创建任何 Skill 的通用方法论
- 在团队里装一波的资本
预计时间：读 15 分钟，做 20 分钟。
Let’s go.
一、先搞清楚东西往哪放
创建 Skill 之前，你得知道它应该住在哪儿。
Claude Skills 有三种"户籍"：
| 类型 | 住址 | 谁能用 |
|---|---|---|
| 个人 Skill | ~/.claude/skills/ | 你自己，在所有项目里 |
| 项目 Skill | .claude/skills/ | 项目里的所有人（可以git共享） |
| 插件 Skill | 通过市场安装 | 看插件作者心情 |
今天我们做一个个人 Skill——这样不管你在哪个项目，都能用。就像你的编辑器配置一样，跟着你走。
二、Skill 长什么样？
一个 Skill 其实就是一个文件夹。
完整版长这样：
我的牛逼技能/ ├── SKILL.md # 灵魂文件，必须有 ├── reference.md # 参考资料（可选） ├── examples.md # 示例（可选） ├── scripts/ # 脚本（可选） │ └── helper.py # 比如统计用的Python脚本 └── templates/ # 模板（可选） └── template.txt极简版？一个文件就够：
我的技能/ └── SKILL.md # 就这一个我们从极简版开始。能用三行解决的问题，绝不写三十行。
三、SKILL.md 怎么写？模板来了
这是整个Skill的灵魂。它由两部分组成：
头部：元数据（Frontmatter）
---name:git-commit-helperdescription:分析git diff，生成规范的commit message---就这两个字段，告诉 Claude：“嘿，我叫xxx，我能干xxx”。
注意：
name：小写+连字符，别用空格description：写清楚能干啥、什么时候用。这玩意儿决定了 Claude 会不会"认出"需要用你的 Skill
正文：具体指令
# Git Commit Helper ## 什么时候用我 当用户让你帮忙写 commit message 的时候 ## 怎么做 1. 先跑 `git diff --staged` 看看改了啥 2. 分析改动类型（功能还是bug修复？） 3. 按规范格式输出 commit message ## 格式要求 ...就像写一份给新员工的SOP——你怎么教实习生，就怎么写这个文件。
四、实战！创建 Git Commit 助手
第一步：建文件夹
打开终端：
# 创建目录mkdir-p ~/.claude/skills/git-commit-helper# 进去cd~/.claude/skills/git-commit-helper第二步：创建 SKILL.md
用你喜欢的编辑器：
# VS Code 用户code SKILL.md# Vim 党vimSKILL.md# 或者简单粗暴nanoSKILL.md第三步：把这段复制进去
--- name: git-commit-helper description: 分析git diff，自动生成符合 Conventional Commits 规范的 commit message。当用户需要写commit、提交代码、或让你看看改了什么的时候使用。 --- # Git Commit 助手 我是一个帮你写 commit message 的技能，确保每次提交都规范、专业、有意义。 ## 什么时候用我 - 用户让你帮忙写 commit message - 用户想看看暂存了什么改动 - 用户准备提交代码但不知道怎么描述 ## 工作流程 ### 1. 先看看改了啥 运行 `git diff --staged` 查看暂存的改动。 如果啥都没暂存？告诉用户："大哥，你得先 `git add` 啊"。 ### 2. 分析改动 看 diff 的时候注意： - 改了哪些文件 - 是加功能、修bug、还是重构 - 影响范围多大 ### 3. 生成 commit message 格式必须是： <type>(<scope>): <subject> <body> <footer> #### 类型对照表 | type | 什么时候用 | |------|-----------| | feat | 新功能 | | fix | 修bug | | docs | 只改了文档 | | style | 格式调整（空格、分号这种） | | refactor | 重构代码（不改功能也不修bug） | | perf | 性能优化 | | test | 加测试 | | chore | 杂活（依赖更新、构建脚本等） | #### 写 subject 的规则 - 用祈使句（"Add feature" 不是 "Added feature"） - 不超过50字符 - 首字母大写 - 结尾不加句号 ## 示例 ### 例子1：加了个功能 feat(auth): Add password reset functionality 实现了密码重置流程，用户可以通过邮箱验证来重置密码。 Closes #42 ### 例子2：修了个bug fix(api): Handle null response from external service 外部服务有时候返回空数据，之前会报 TypeError。 现在加了空值检查，优雅处理这种情况。 ### 例子3：改了文档 docs(readme): Update installation instructions 新增了 Docker 安装方式，明确了 Node.js 版本要求。 ## 特殊情况处理 - 没有暂存的改动*：提醒用户先 `git add` - 改动太多太杂：建议拆成多个commit - 不知道改了啥：问用户"这次改动主要是想做什么" ## 小贴士 1. 一个 commit 只做一件事 2. commit message 是写给未来的自己看的 3. 如果关联了 Issue，记得在 footer 里加 `Closes #xxx`第四步：验证一下
# 看看文件在不在ls~/.claude/skills/git-commit-helper/# 看看内容对不对head-10 ~/.claude/skills/git-commit-helper/SKILL.md应该能看到我们刚写的内容。
第五步：测试！
打开 Claude Code，随便找个有 Git 的项目：
# 随便改个文件echo"// test">>test.js# 暂存gitaddtest.js# 然后问 Claude对 Claude 说：“帮我看看暂存的改动，写个 commit message”
如果一切正常，它应该会：
- 自动识别到你的 Skill
- 跑
git diff --staged - 输出一个漂亮规范的 commit message
🎉 恭喜，你的第一个 Skill 活了！
五、进阶：给 Skill 装个"外挂"
基础版能用了，但有时候你想更"牛逼"一点——比如自动统计改动行数、列出改了哪些文件。
这时候可以加个脚本。
创建脚本目录
mkdir-p ~/.claude/skills/git-commit-helper/scripts写一个分析脚本
创建~/.claude/skills/git-commit-helper/scripts/analyze_diff.py：
#!/usr/bin/env python3""" 分析 git diff 的统计信息 用法: python analyze_diff.py """importsubprocessimportsysimportreimportjsondefget_staged_diff():"""获取暂存区的 diff 统计"""result=subprocess.run(['git','diff','--staged','--stat'],capture_output=True,text=True)returnresult.stdout,result.returncodedefparse_stats(diff_output):"""解析 diff 输出"""lines=diff_output.strip().split('\n')ifnotlinesorlines[0]=='':return{'has_changes':False,'message':'没有暂存的改动。先用 git add 加点东西？'}# 解析最后一行的汇总summary=lines[-1]iflineselse''files=0insertions=0deletions=0files_match=re.search(r'(\d+) files? changed',summary)ins_match=re.search(r'(\d+) insertions?',summary)del_match=re.search(r'(\d+) deletions?',summary)iffiles_match:files=int(files_match.group(1))ifins_match:insertions=int(ins_match.group(1))ifdel_match:deletions=int(del_match.group(1))# 解析改动的文件列表changed_files=[]forlineinlines[:-1]:if'|'inline:filename=line.split('|')[0].strip()changed_files.append(filename)return{'has_changes':True,'files_count':files,'insertions':insertions,'deletions':deletions,'files':changed_files}defmain():diff_output,code=get_staged_diff()ifcode!=0:print(json.dumps({'error':'不在 Git 仓库里，或者 git 命令有问题'}))sys.exit(1)stats=parse_stats(diff_output)ifnotstats['has_changes']:print(f"⚠️{stats['message']}")returnprint(f"📊 改动统计:")print(f" 📁 文件数:{stats['files_count']}")print(f" ➕ 新增行: +{stats['insertions']}")print(f" ➖ 删除行: -{stats['deletions']}")print(f"\n📑 改动的文件:")forfinstats['files']:print(f" •{f}")if__name__=='__main__':main()添加执行权限
chmod+x ~/.claude/skills/git-commit-helper/scripts/analyze_diff.py在 SKILL.md 里告诉 Claude 这个脚本
在 SKILL.md 的"工作流程"部分加上：
### 0. 快速预览（可选） 想快速看看改动情况？跑这个脚本： ```bash python ~/.claude/skills/git-commit-helper/scripts/analyze_diff.py它会告诉你改了多少文件、加了多少行、删了多少行。
--- ## 六、分享给队友（或全世界） 好东西不能自己藏着。 ### 方法1：放到项目里（团队共享） ```bash # 复制到项目的 .claude/skills 目录 cp -r ~/.claude/skills/git-commit-helper /你的项目/.claude/skills/ # commit 进去 cd /你的项目 git add .claude/skills/git-commit-helper git commit -m "chore: add git-commit-helper skill for the team" git push队友拉代码后，Claude 会自动识别项目里的 Skill。
方法2：发到 GitHub
- 创建一个公开仓库
- 把你的 Skill 推上去
- 提交到这些 Awesome List：
- ComposioHQ/awesome-claude-skills
- VoltAgent/awesome-claude-skills
说不定哪天就有人给你发感谢邮件🤑。
七、踩坑指南：我帮你踩过的坑
坑1：Claude 不用我的 Skill
症状：你明明创建了，但 Claude 根本不理它。
排查：
# 文件在不在？ls~/.claude/skills/git-commit-helper/SKILL.md# YAML 格式对不对？head-5 ~/.claude/skills/git-commit-helper/SKILL.md常见问题：
---分隔符打成了--或----name里有大写字母或空格description太模糊，Claude 没法判断什么时候用
坑2：提示 “Skill has errors”
症状：Claude 说 Skill 有错误。
多半是 YAML 语法问题：
- 冒号后面忘了加空格
- 缩进用了Tab（应该用空格）
- 特殊字符没转义
坑3：脚本跑不起来
排查：
# 有执行权限吗？ls-la ~/.claude/skills/git-commit-helper/scripts/# 直接跑一下试试python3 ~/.claude/skills/git-commit-helper/scripts/analyze_diff.py八、收工！
恭喜你，现在你拥有了：
✅ 一个真正能用的 Git Commit 助手
✅ 创建任何 Skill 的方法论
✅ 可能在团队里变成"这人挺会玩"的口碑
回顾一下我们做了什么
| 步骤 | 内容 |
|---|---|
| 选址 | 确定 Skill 放在哪个目录 |
| 建房 | 创建文件夹和 SKILL.md |
| 装修 | 写清楚元数据和指令 |
| 验收 | 测试 Skill 是否工作 |
| 升级 | 可选地加上脚本 |
| 分享 | 通过Git或社区共享 |
下一步
想继续升级？推荐阅读：
- 《Claude Skills 高级玩法》——学习多文件组织、权限控制、性能优化
- 《2025 必装的 20 个 Claude Skills》——看看大佬们都在用什么
小作业
试着创建一个自己的 Skill：
- 会议纪要格式化器——把杂乱的会议记录整理成规范格式
- API 文档生成器——给代码生成接口文档
- Code Review 检查清单——审代码时的标准化检查流程
互动
💬你的第一个 Skill 是什么？踩了什么坑？
评论区见。如果这篇帮到了你，点赞 + 收藏 + 关注，下次更新不迷路。