git-skills

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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](https://github.com/daleseo/git-skills/blob/HEAD/skills/modern-git/SKILL.md) - Quick reference and common workflows
- [Command Comparison](https://github.com/daleseo/git-skills/blob/HEAD/skills/modern-git/references/command-comparison.md) - Detailed side-by-side comparisons
- [Migration Guide](https://github.com/daleseo/git-skills/blob/HEAD/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](https://github.com/daleseo/git-skills/blob/HEAD/skills/git-commits/SKILL.md) - Complete guide to commit best practices
- [Conventional Commits](https://github.com/daleseo/git-skills/blob/HEAD/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](https://github.com/daleseo/git-skills/blob/HEAD/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](https://github.com/daleseo/git-skills/blob/HEAD/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](https://github.com/daleseo/git-skills/tree/HEAD/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 🤖✨

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:

# ✗ 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 - Quick reference and common workflows
Command Comparison - Detailed side-by-side comparisons
Migration Guide - 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:

# ✓ 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 - Complete guide to commit best practices
Conventional Commits - 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:

# ✓ 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 - 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:

# ✗ 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 - Recovery techniques and safety practices

Installation

Via Skills CLI

npx skills add yourusername/git-skills

Local Usage

Clone this repository:

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

Use with Claude Code:

# 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

Or reference from CLAUDE.md:

# ~/.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:

Follow the skill structure:

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

Skill frontmatter format:

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

Include in documentation:
- Clear examples with ✓/✗ markers
- Decision trees for common scenarios
- Real-world workflows
- Common mistakes section
- Quick reference summary
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 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 🤖✨