用 Git 管理 Skills 版本
High Contrast
Dark Mode
Light Mode
Sepia
Forest
3 min read516 words

用 Git 管理 Skills 版本

Skills 作为代码库的一部分存在于 Git 中，这意味着它们天然享有代码版本管理的所有能力：提交历史、分支管理、PR 审查、标签版本、回滚。理解如何充分利用这些能力，是 Skills 工程化的关键。

将 .claude/ 加入版本控制

默认情况下，.claude/ 目录可能被全局 .gitignore 忽略。确认它被正确追踪：

# 检查是否被忽略
git check-ignore -v .claude/skills/review-pr.md
# 如果被忽略，在 .gitignore 中添加排除规则
echo '!.claude/' >> .gitignore
echo '!.claude/**' >> .gitignore
# 验证
git add .claude/skills/review-pr.md
git status  # 应该显示为新文件

重要：确认 .env 文件不在 .claude/ 目录下。settings.json 中不应包含真实的密钥。

Skills 的 Git 工作流

个人开发 Skills 的流程

# 1. 为新 Skill 创建功能分支
git checkout -b skill/add-changelog-generator
# 2. 创建 Skill 文件
vi .claude/skills/docs/changelog.md
# 3. 本地测试
# 在 Claude Code 中运行并验证行为
# 4. 提交
git add .claude/skills/docs/changelog.md
git add .claude/skills/README.md  # 更新索引
git commit -m "skill(docs): add /changelog Skill for automated CHANGELOG generation
The Skill reads git log since the last tag and groups commits by:
- feat: → New Features
- fix:  → Bug Fixes
- docs: → Documentation
- other → Other Changes
Tested with: feature branch, hotfix branch, empty range
No --env param needed (reads local git history only)"
# 5. 推送并创建 PR
git push origin skill/add-changelog-generator

Skills PR 的描述模板

## Skill 变更说明
**变更类型**：[ ] 新增 Skill  [ ] 修改 Skill  [ ] 删除 Skill
**涉及的 Skill**：`/changelog`
**变更描述**：
添加 `/changelog` Skill，自动读取 git log 并按 conventional commits 格式生成 CHANGELOG。
**测试结果**：
- [x] 正常场景（有提交记录的标准分支）✅
- [x] 空内容场景（无新提交）✅ 输出"无变更"提示
- [x] 缺失参数（无 --version）✅ 使用 "Unreleased" 默认值
- [x] 权限测试：只调用了 Bash 和 Read，未调用 Write ✅
**需要审查的重点**：
- 步骤 3 中对 commit message 类型的分类逻辑是否合理？
**README.md 更新**：已在索引表中添加
**CHANGELOG.md 更新**：已记录

语义化版本管理 Skills

对于重要的团队 Skills，可以用 Git 标签追踪版本：

# 给 Skills 库打版本标签
git tag -a skills-v1.0 -m "Skills 库 v1.0：包含代码审查、文档生成和部署检查基础套件"
git push origin skills-v1.0
# 在 CHANGELOG.md 中记录
# Skills CHANGELOG
# ## v1.0 (2026-03-22)
# 初始版本，包含：/review-pr, /gen-pr-desc, /pre-deploy, /standup

Skills 的 diff 和审查

Git diff 能清楚地展示 Skills 的变更：

# 查看 Skill 的修改历史
git log --oneline .claude/skills/review-pr.md
# 查看具体变更
git diff HEAD~1 HEAD .claude/skills/review-pr.md

一个 Skill diff 的示例：

--- a/.claude/skills/code-review/review-pr.md
+++ b/.claude/skills/code-review/review-pr.md
@@ -12,6 +12,8 @@ allowed-tools: Bash, Read, Grep
| `--branch` | string | 否 | 当前 Git 分支 | 要审查的分支名 |
| `--focus` | enum | 否 | `all` | 审查重点：security/performance/style/all |
+| `--depth` | enum | 否 | `quick` | 分析深度：quick（只看修改文件）/full（含依赖分析）|
+| `--since` | string | 否 | — | 只分析此日期之后的提交，如 "2024-01-01" |
@@ -35,6 +37,12 @@ allowed-tools: Bash, Read, Grep
2. 获取修改文件列表...
+3. 如果 `--depth` 为 `full`，额外分析：
+   - 修改文件的直接导入依赖（import/require 语句）
+   - 检查这些依赖文件是否也有相关的问题

这让 PR 审查者能清楚看到 Skill 逻辑的哪个部分发生了变化。

处理 Skills 的合并冲突

当团队多人修改同一个 Skill 文件时，可能发生合并冲突。Skill 是 Markdown 文件，合并冲突的处理方式和普通文本一样：

## 执行步骤
<<<<<<< HEAD
3. 运行 npm test 检查测试
=======
3. 运行 npm test -- --coverage 检查测试覆盖率
>>>>>>> feature/add-coverage-check

处理原则： 1. 理解两个分支修改的意图 2. 选择更完整/更正确的版本，或者合并两者 3. 解决冲突后，在本地重新测试该 Skill

.gitattributes 配置

帮助 Git 更好地处理 Skill 文件：

# .gitattributes
# Skill 文件当作普通文本处理
.claude/skills/**/*.md text eol=lf
# diff 时使用 markdown 的 diff 算法
.claude/skills/**/*.md diff=markdown
# 标记为可能被合并的文本文件
.claude/settings.json merge=ours

回滚 Skills

如果某个 Skill 的更新破坏了团队的工作流，可以快速回滚：

# 查看特定 Skill 的历史
git log --oneline .claude/skills/ops/pre-deploy.md
# 回滚到特定版本
git checkout abc1234 -- .claude/skills/ops/pre-deploy.md
git commit -m "skill(ops/pre-deploy): revert to v1.1 (abc1234)
v1.2 introduced a regression in staging environment checks.
Reverting to stable v1.1 while investigating the issue."

本节记录清单

下一节：Skills 的团队分发机制——Git 管理了版本，但如何把 Skills 分发给团队的其他项目？子模块、独立仓库还是 npm 包？