# Git Skills for AI Agents

A collection of Claude Code skills focused on modern Git best practices and workflows. These skills help AI agents generate cleaner commits, collaborate effectively, and work safely with Git.

## Skills Overview

### 1. Modern Git Commands

**Location:** `skills/modern-git/`

**Purpose:** Teaches AI agents to use modern, intuitive Git commands introduced in Git 2.23+ instead of legacy multi-purpose commands.

**Key Principles:**

- Use `git switch` for branch operations (NOT `git checkout`)
- Use `git restore` for file operations (NOT `git checkout --`)
- Use `git push --force-with-lease` (NOT `git push --force`)
- Be explicit about intent to prevent mistakes

**Quick Example:**

```bash
# ✗ Legacy (unclear, error-prone)
git checkout main
git checkout -b feature
git checkout -- src/app.js

# ✓ Modern (clear, safe)
git switch main
git switch -c feature
git restore src/app.js
```

**Documentation:**

- [SKILL.md](skills/modern-git/SKILL.md) - Quick reference and common workflows
- [Command Comparison](skills/modern-git/references/command-comparison.md) - Detailed side-by-side comparisons
- [Migration Guide](skills/modern-git/references/migration-guide.md) - Complex scenarios and patterns

---

### 2. Git Commit Best Practices

**Location:** `skills/git-commits/`

**Purpose:** Teaches AI agents to create high-quality commits with clear messages, proper granularity, and effective use of the staging area.

**Key Principles:**

- **Atomic Commits** - One logical change per commit
- **Conventional Commits** - Standardized message format (feat, fix, docs, etc.)
- **Clear Messages** - Explain why, not just what
- **Smart Staging** - Use `git add -p` for partial staging

**Quick Example:**

```bash
# ✓ Good: Atomic commits with clear messages
git add src/auth.js src/api.js
git commit -m "feat(auth): add JWT token refresh mechanism

Implements automatic token refresh 5 minutes before expiration.
Prevents user session interruption during active usage.

Closes #234"

# ✗ Bad: Everything in one vague commit
git add .
git commit -m "update auth stuff"
```

**Documentation:**

- [SKILL.md](skills/git-commits/SKILL.md) - Complete guide to commit best practices
- [Conventional Commits](skills/git-commits/references/conventional-commits.md) - Deep dive into commit message format

---

### 3. Git Collaboration Workflows

**Location:** `skills/git-collaboration/`

**Purpose:** Teaches AI agents to collaborate effectively in team environments using Git, including PR workflows, merge strategies, and conflict resolution.

**Key Principles:**

- **Feature Branch Workflow** - Standard collaboration pattern
- **Small, Focused PRs** - Easier to review and merge
- **Rebase for Clean History** - Linear, readable commit history
- **Review-Friendly** - Structure changes for easy review

**Quick Example:**

```bash
# ✓ Standard feature workflow
git switch main
git pull
git switch -c feature/add-notifications

# Work and commit
git add src/notifications.js
git commit -m "feat(notifications): add email notification service"

# Stay up to date
git fetch origin
git rebase origin/main

# Create PR
git push -u origin feature/add-notifications
gh pr create --title "Add notification system"

# After merge, cleanup
git switch main
git pull
git branch -d feature/add-notifications
```

**Documentation:**

- [SKILL.md](skills/git-collaboration/SKILL.md) - PR workflows and collaboration patterns

---

### 4. Git Safety and Recovery

**Location:** `skills/git-recovery/`

**Purpose:** Teaches AI agents to work safely with Git and recover from common mistakes without losing work.

**Key Principles:**

- **Git Rarely Deletes** - Almost everything is recoverable via reflog
- **Understand Before Destroying** - Know what `--hard`, `--force` do
- **Backup Before Risky Operations** - Use stash, branches, or tags
- **Revert, Don't Reset** - For shared branches

**Quick Example:**

```bash
# ✗ Mistake: Deleted important branch
git branch -D feature/important-work

# ✓ Recovery: Use reflog
git reflog | grep "important-work"
git switch -c feature/important-work abc123

# ✓ Prevention: Backup before risky operations
git switch -c backup-before-rebase
# Do risky operation
git branch -d backup-before-rebase  # Delete if successful
```

**Documentation:**

- [SKILL.md](skills/git-recovery/SKILL.md) - Recovery techniques and safety practices

---

## Installation

### Via Skills CLI

```bash
npx skills add yourusername/git-skills
```

### Local Usage

1. **Clone this repository:**

```bash
git clone https://github.com/yourusername/git-skills.git
cd git-skills
```

2. **Use with Claude Code:**

```bash
# Use single skill
claude --skill ./skills/modern-git

# Use multiple skills
claude --skill ./skills/modern-git \
       --skill ./skills/git-commits

# Use all skills
claude --skill ./skills/modern-git \
       --skill ./skills/git-commits \
       --skill ./skills/git-collaboration \
       --skill ./skills/git-recovery
```

3. **Or reference from CLAUDE.md:**

```markdown
# ~/.claude/CLAUDE.md (global) or ./.claude/CLAUDE.md (project-level)
Load skills from: /path/to/git-skills/skills/*
```

## Quick Comparison

| Skill                       | Focus                 | Use When                      |
| --------------------------- | --------------------- | ----------------------------- |
| **Modern Git Commands**     | Command modernization | Using basic Git operations    |
| **Commit Best Practices**   | Commit quality        | Creating commits and messages |
| **Collaboration Workflows** | Team workflows        | Working with PRs and teams    |
| **Safety and Recovery**     | Mistake recovery      | Fixing Git mistakes           |

## Skill Features

All skills include:

- ✅ Clear decision trees for choosing the right approach
- ✅ Side-by-side comparisons (good vs bad examples)
- ✅ Real-world workflows
- ✅ Common mistakes and how to avoid them
- ✅ Quick reference tables
- ✅ Integration guidance for AI code generation

## Contributing

Contributions are welcome! When adding new skills:

1. **Follow the skill structure:**

   ```
   skills/skill-name/
   ├── SKILL.md           # Main skill documentation with frontmatter
   └── references/        # Detailed reference materials (optional)
       └── *.md
   ```

2. **Skill frontmatter format:**

   ```yaml
   ---
   name: skill-name
   description: Brief description of what this skill teaches
   ---
   ```

3. **Include in documentation:**
   - Clear examples with ✓/✗ markers
   - Decision trees for common scenarios
   - Real-world workflows
   - Common mistakes section
   - Quick reference summary

4. **Focus on practicality:**
   - Everyday scenarios over edge cases
   - Clear "when to use" guidance
   - Explain the "why" behind recommendations

## Philosophy

These skills focus on **simple but easily overlooked best practices** rather than advanced techniques:

- 🎯 **Practical over theoretical** - Real workflows, not academic examples
- 🛡️ **Safe defaults** - Prevent common mistakes before they happen
- 📖 **Clear intent** - Code reviewers understand what was intended
- 🤝 **Team-friendly** - Collaboration patterns that scale
- 🔧 **Modern tools** - Leverage Git's improvements (2.23+)

## Why These Skills?

AI agents often default to:

- ❌ Legacy Git commands from older training data
- ❌ Vague commit messages like "update" or "fix"
- ❌ Large, unfocused commits mixing multiple changes
- ❌ Unsafe operations like `git push --force`

These skills teach agents to:

- ✅ Use modern, purposeful commands
- ✅ Write meaningful commit messages
- ✅ Create atomic, reviewable commits
- ✅ Work safely and recover from mistakes

## License

MIT License - See [LICENSE](LICENSE) for details

## Acknowledgments

Inspired by:
- The Git community's efforts to improve usability
- Conventional Commits specification
- GitHub Flow and GitFlow workflows
- Best practices from open source projects

---

**Made for Claude Code** - Teaching AI agents to be better Git citizens 🤖✨