playbooks

home / skills / louloulin / claude-agent-sdk / git-workflow

git-workflow skill

/crates/claude-agent-sdk/examples/.claude/skills/git-workflow

This skill provides expert Git workflow guidance and repository management to optimize collaboration and release processes.

npx playbooks add skill louloulin/claude-agent-sdk --skill git-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
5.1 KB
---
name: git-workflow-assistant
description: "Expert Git workflow guidance and repository management"
version: "1.8.0"
author: "Platform Team <[email protected]>"
tags:
  - git
  - version-control
  - workflow
  - collaboration
dependencies: []
---

# Git Workflow Assistant

You are a Git and workflow expert. Help teams use Git effectively with best practices.

## Git Workflow Models

### 1. Trunk-Based Development
- Main branch is always deployable
- Short-lived feature branches (< 1 day)
- Continuous integration/deployment
- Feature flags for incomplete features

**When to use:**
- Small teams with fast deployment
- Continuous deployment environments
- Projects requiring rapid iteration

### 2. Git Flow
- Long-lived main and develop branches
- Feature branches from develop
- Release branches for stabilization
- Hotfix branches for production fixes

**Branch structure:**
```
main (production)
  ā†‘
develop (integration)
  ā†‘
feature/* (new features)
release/* (release preparation)
hotfix/* (production fixes)
```

**When to use:**
- Projects with scheduled releases
- Teams needing release isolation
- Complex version management

### 3. GitHub Flow
- Single main branch
- Feature branches with pull requests
- Review and discussion required
- Merge after approval

**When to use:**
- Teams using GitHub
- Continuous deployment
- Collaborative development

## Branch Naming Conventions

```
feature/ticket-description
bugfix/ticket-description
hotfix/ticket-description
release/version-number
experiment/feature-name
docs/documentation-update
refactor/code-section
test/test-improvement
```

## Commit Message Format

Follow Conventional Commits:

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `build`: Build system changes
- `ci`: CI/CD changes

**Examples:**
```
feat(auth): add OAuth2 login support

Implement OAuth2 authentication with Google and GitHub
providers. Includes token refresh logic and error handling.

Closes #123

Fixes #456
```

## Pull Request Guidelines

### PR Title
- Use conventional commit format
- Be descriptive but concise
- Include ticket number if applicable

### PR Description
```markdown
## Summary
[Brief description of changes]

## Changes
- [List major changes]

## Testing
- [Describe testing performed]

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No merge conflicts
- [ ] Code reviewed
```

## Common Workflows

### Starting a New Feature
```bash
git checkout main
git pull origin main
git checkout -b feature/my-feature
# Make changes
git add .
git commit -m "feat: add my feature"
git push -u origin feature/my-feature
# Create PR
```

### Handling Merge Conflicts
```bash
git checkout main
git pull origin main
git checkout feature/my-feature
git rebase main
# Resolve conflicts
git add <resolved-files>
git rebase --continue
git push --force-with-lease
```

### Reverting a Commit
```bash
# Find commit to revert
git log --oneline

# Revert (creates new commit)
git revert <commit-hash>

# Or reset (destructive, use with caution)
git reset --hard <commit-hash>
git push --force
```

## Code Review Best Practices

### For Reviewers
- Review PRs promptly
- Be constructive and respectful
- Explain reasoning for suggestions
- Approve or request changes clearly
- Test changes if possible

### For Authors
- Keep PRs focused and small
- Write clear descriptions
- Respond to feedback
- Update based on reviews
- Say when ready for re-review

## Safety Rules

1. **Never force push to main/develop**
2. **Always pull before pushing**
3. **Write meaningful commit messages**
4. **Review your own diffs before committing**
5. **Don't commit sensitive data**
6. **Use .gitignore properly**
7. **Tag important releases**

## Troubleshooting

### Undo Local Changes
```bash
# Undo file changes
git checkout -- <file>

# Undo all local changes
git reset --hard HEAD

# Keep changes but unstage
git reset HEAD
```

### Recover Lost Commits
```bash
# Find lost commit
git reflog

# Recover commit
git checkout <commit-hash>
git branch recovery-branch
```

### Clean Up
```bash
# Remove merged branches
git branch --merged | grep -v "main\|develop" | xargs git branch -d

# Remove untracked files
git clean -fd
```

## Git Configuration

```bash
# User info
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Default branch name
git config --global init.defaultBranch main

# Rebase on pull
git config --global pull.rebase true

# Aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
```

## Best Practices

āœ… **DO:**
- Keep commits atomic and focused
- Write descriptive commit messages
- Review code before merging
- Use branch protection rules
- Maintain clean history
- Test before pushing

āŒ **DON'T:**
- Commit broken code
- Merge without review
- Push sensitive data
- Ignore merge conflicts
- Rewrite public history
- Commit directly to main

Overview

This skill provides expert Git workflow guidance and practical repository management advice for teams using Rust or other languages. It codifies branching models, commit conventions, pull request structure, and safety rules to keep repositories reliable and easy to maintain. Use it to align team practices, reduce merge friction, and improve CI/CD readiness.

How this skill works

The assistant inspects your current workflow goals and recommends an appropriate branching model (trunk-based, Git Flow, or GitHub Flow). It enforces branch naming and Conventional Commit patterns, offers step-by-step commands for common tasks (feature work, rebasing, reverting, recovering commits), and highlights safety rules to avoid destructive actions. It also provides PR templates, review guidance, and Git configuration tips to standardize developer behavior.

When to use it

  • Onboard new team members to a consistent Git workflow
  • Choose a branching model that fits your release cadence and team size
  • Prepare repositories for continuous integration and deployment
  • Resolve recurring merge conflicts and improve review quality
  • Enforce commit and PR standards across projects

Best practices

  • Keep commits small and focused; use Conventional Commits for clarity
  • Protect main/develop with branch protection and require reviews
  • Always pull/rebase before pushing and avoid force-pushing protected branches
  • Use feature flags for incomplete work in trunk-based workflows
  • Tag releases and avoid rewriting public history

Example use cases

  • Small team adopting trunk-based development for daily deploys
  • Product with scheduled releases using Git Flow for isolation
  • Open source project enforcing PR reviews and Conventional Commits
  • Resolving a complex merge conflict via rebase and force-with-lease
  • Recovering a lost commit using git reflog and creating a recovery branch

FAQ

When should I choose trunk-based development versus Git Flow?

Choose trunk-based development for small teams and continuous deployment where short-lived branches and feature flags work well. Use Git Flow when you need release isolation, scheduled releases, or complex version management.

How do I safely revert a bad commit?

Use git revert <commit> to create a reversing commit without rewriting history. Only use git reset --hard and force pushes on branches that are not shared publicly and with team agreement.