setup-git-workflow

star 0

Use when starting a new project and need to set up Git best practices with Conventional Commits, pre-commit hooks, and AI enforcement rules

Rogary By Rogary schedule Updated 3/1/2026
play_arrow Run Skill in Manus View GitHub

name: setup-git-workflow description: Use when starting a new project and need to set up Git best practices with Conventional Commits, pre-commit hooks, and AI enforcement rules allowed-tools: "Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion"

Setup Git Workflow

为项目配置 Git 版本管理最佳实践，包括：

  • Conventional Commits 规范
  • Pre-commit hooks 自动检查
  • 分支策略和命名规范
  • AI 行为约束规则
  • 敏感信息保护

When to Use

  • 开始新项目时
  • 需要规范 Git 工作流
  • 需要多人协作的项目
  • 需要 AI Agent 参与开发
  • 需要强制执行提交规范

What This Skill Provides

Git 配置文件

  • .gitignore - 通用忽略规则（支持多种语言和框架）
  • .gitconfig.agent-template - Agent 专用 Git 配置模板
  • .gitmessage - Conventional Commits 提交消息模板
  • .pre-commit-config.yaml - Pre-commit hooks 配置
  • .secrets.baseline - 敏感信息检测基线

文档

  • GIT_WORKFLOW.md - 完整的 Git 工作流指南
  • AI_ENFORCEMENT_GUIDE.md - AI 行为约束和强制规则

脚本

  • setup-git-config.sh - 自动化配置脚本

Implementation Steps

Step 1: 收集项目信息

使用 AskUserQuestion 询问用户：

  1. 项目类型：

    • 前端（Frontend）
    • 后端（Backend）
    • 全栈（Fullstack）
    • 数据科学（Data Science）
    • 其他

  2. Agent 身份（如果是 AI Agent）：

    • Backend Dev
    • Frontend Dev
    • Tester
    • Code Reviewer
    • Architect
    • Researcher
    • 其他

  3. 是否已有 Git 配置：

    • 是（需要备份现有配置）
    • 否（全新配置）

Step 2: 备份现有配置（如果需要）

如果项目已有 Git 配置，创建备份：

# 备份现有配置文件
for file in .gitignore .gitconfig .gitmessage .pre-commit-config.yaml; do
  if [ -f "$file" ]; then
    cp "$file" "${file}.backup-$(date +%Y%m%d-%H%M%S)"
    echo "✅ 已备份: $file"
  fi
done

Step 3: 复制配置文件

从 Skill 模板目录复制文件到项目根目录：

# 获取 Skill 目录路径（优先使用插件安装路径，兼容旧版 skills 目录）
if [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -d "$CLAUDE_PLUGIN_ROOT/skills/setup-git-workflow" ]; then
  SKILL_DIR="$CLAUDE_PLUGIN_ROOT/skills/setup-git-workflow"
elif [ -d "$HOME/.claude/skills/setup-git-workflow" ]; then
  SKILL_DIR="$HOME/.claude/skills/setup-git-workflow"
else
  echo "❌ 未找到 setup-git-workflow skill 目录"
  exit 1
fi

# 复制模板文件
cp "$SKILL_DIR/templates/.gitignore" .
cp "$SKILL_DIR/templates/.gitconfig.agent-template" .
cp "$SKILL_DIR/templates/.gitmessage" .
cp "$SKILL_DIR/templates/.pre-commit-config.yaml" .
cp "$SKILL_DIR/templates/.secrets.baseline" .

# 复制文档
cp "$SKILL_DIR/docs/GIT_WORKFLOW.md" .
cp "$SKILL_DIR/docs/AI_ENFORCEMENT_GUIDE.md" .

# 复制脚本
cp "$SKILL_DIR/scripts/setup-git-config.sh" .
chmod +x setup-git-config.sh

Step 4: 参数化替换

根据用户提供的信息，替换配置文件中的占位符：

在 .gitconfig.agent-template 中：

  • [ROLE] → Agent 角色名称（如 "Backend Dev"）
  • [role] → Agent ID（如 "backend-dev"）

在 .gitmessage 中：

  • [role] → Agent ID

在 GIT_WORKFLOW.md 中：

  • [PROJECT_NAME] → 项目名称
  • [PROJECT_TYPE] → 项目类型

示例替换命令：

# 替换 Agent 角色
ROLE="Backend Dev"
ROLE_ID="backend-dev"

sed -i.bak "s/\[ROLE\]/$ROLE/g" .gitconfig.agent-template
sed -i.bak "s/\[role\]/$ROLE_ID/g" .gitconfig.agent-template
sed -i.bak "s/\[role\]/$ROLE_ID/g" .gitmessage

# 清理备份文件
rm -f .gitconfig.agent-template.bak .gitmessage.bak

Step 5: 执行配置脚本

运行自动化配置脚本：

./setup-git-config.sh

这个脚本会：

  1. 检查 Git 是否已初始化
  2. 配置 Git 用户信息（如果是 Agent）
  3. 设置提交消息模板
  4. 配置分支策略
  5. 安装 pre-commit hooks

Step 6: 安装 Pre-commit Hooks

# 安装 pre-commit（如果未安装）
if ! command -v pre-commit &> /dev/null; then
  echo "正在安装 pre-commit..."
  pip install pre-commit
fi

# 安装 hooks
pre-commit install
pre-commit install --hook-type commit-msg

# 运行一次检查
pre-commit run --all-files

Step 7: 更新 CLAUDE.md（如果存在）

如果项目已有 CLAUDE.md，添加 Git 工作流规则：

if [ -f "CLAUDE.md" ]; then
  echo "" >> CLAUDE.md
  echo "# Git 版本管理规则" >> CLAUDE.md
  echo "" >> CLAUDE.md
  echo "详见 GIT_WORKFLOW.md 和 AI_ENFORCEMENT_GUIDE.md" >> CLAUDE.md
else
  # 创建新的 CLAUDE.md
  cat > CLAUDE.md << 'EOF'
# 项目配置

## Git 版本管理规则

详见 GIT_WORKFLOW.md 和 AI_ENFORCEMENT_GUIDE.md

EOF
fi

Step 8: 创建初始提交（可选）

如果这是新项目，创建初始提交：

git add .gitignore .gitconfig.agent-template .gitmessage .pre-commit-config.yaml .secrets.baseline
git add GIT_WORKFLOW.md AI_ENFORCEMENT_GUIDE.md CLAUDE.md setup-git-config.sh
git commit -m "chore(setup): configure Git workflow and best practices [agent: setup]

- Add Conventional Commits template
- Configure pre-commit hooks
- Add Git workflow documentation
- Set up AI enforcement rules"

Step 9: 验证配置

运行验证检查：

# 检查 Git 配置
echo "=== Git 配置 ==="
git config --local --list | grep -E "(user|commit|branch)"

# 检查 pre-commit hooks
echo ""
echo "=== Pre-commit Hooks ==="
pre-commit run --all-files

# 测试提交消息模板
echo ""
echo "=== 提交消息模板 ==="
git config --get commit.template

Step 10: 输出完成报告

向用户展示配置完成的摘要：

✅ Git 工作流配置完成！

## 已安装的配置

### 文件
- .gitignore - 通用忽略规则
- .gitconfig.agent-template - Agent Git 配置
- .gitmessage - 提交消息模板
- .pre-commit-config.yaml - Pre-commit hooks
- .secrets.baseline - 敏感信息检测基线

### 文档
- GIT_WORKFLOW.md - Git 工作流指南
- AI_ENFORCEMENT_GUIDE.md - AI 行为约束规则

### 脚本
- setup-git-config.sh - 配置脚本

## 下一步

1. 阅读 GIT_WORKFLOW.md 了解工作流程
2. 如果是 AI Agent，运行 `./setup-git-config.sh` 配置身份
3. 开始开发时，遵循分支命名规范：`agent/<agent-id>/<type>-<description>`
4. 提交时使用 Conventional Commits 格式

## 快速开始

```bash
# 配置 Agent 身份（如果需要）
./setup-git-config.sh

# 创建新分支
git checkout -b agent/backend-dev/feat-new-feature

# 提交代码
git add <files>
git commit  # 会自动打开模板

# 推送分支
git push -u origin HEAD

需要帮助？

  • 查看 GIT_WORKFLOW.md 了解完整工作流
  • 查看 AI_ENFORCEMENT_GUIDE.md 了解 AI 约束规则
  • 使用 /commit skill 自动生成规范的提交消息

## Error Handling

### 常见问题

1. **Pre-commit 安装失败**
   - 检查 Python 是否已安装
   - 尝试使用 `pip3 install pre-commit`
   - 或使用 `brew install pre-commit`（macOS）

2. **Git 配置冲突**
   - 检查是否有现有的 `.git/config`
   - 使用 `--local` 标志确保只修改项目配置
   - 备份现有配置后再应用

3. **权限问题**
   - 确保 `setup-git-config.sh` 有执行权限
   - 使用 `chmod +x setup-git-config.sh`

4. **文件已存在**
   - 询问用户是否覆盖
   - 创建备份（.backup-YYYYMMDD-HHMMSS）
   - 提供合并选项

## Customization

用户可以根据需要自定义：

1. **修改 .gitignore**
   - 添加项目特定的忽略规则
   - 保留通用规则

2. **调整 pre-commit hooks**
   - 在 `.pre-commit-config.yaml` 中启用/禁用 hooks
   - 添加项目特定的检查

3. **自定义提交模板**
   - 编辑 `.gitmessage`
   - 添加项目特定的提示

## Integration with Other Skills

这个 Skill 可以与以下 Skills 配合使用：

- `/setup-agent-teams` - 配置多代理协作
- `/commit` - 自动生成规范的提交消息
- `/commit-push-pr` - 一键提交、推送和创建 PR
- `/review-pr` - 审查 PR 是否符合规范

## Notes

- 这个 Skill 不会修改全局 Git 配置，只修改项目级配置
- 所有配置文件都可以在安装后自定义
- Pre-commit hooks 可以根据需要启用/禁用
- 建议在团队中共享这些配置（提交到版本控制）
Install via CLI
npx skills add https://github.com/Rogary/git-workflow-plugin-marketplace --skill setup-git-workflow
Repository Details
star Stars 0
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
Rogary
Rogary Explore all skills →