从零到一：手撸一个让队友追着夸的 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 是什么？踩了什么坑？

评论区见。如果这篇帮到了你，点赞 + 收藏 + 关注，下次更新不迷路。

从零到一：手撸一个让队友追着夸的 Claude Skill