---
name: octocat
description: Handles git and GitHub operations using the gh CLI. Use when the user asks about pull requests (PRs), GitHub issues, repo management, branching, merging, rebasing, cherry-picking, merge conflict resolution, commit history cleanup, pre-commit hook debugging, GitHub Actions workflows, or releases. Covers creating and reviewing PRs, watching CI checks, interactive rebasing, branch cleanup, submodule management, and repository archaeology with git log/blame/bisect.
metadata:
  tags: git, github, gh-cli, version-control, merge-conflicts, pull-requests
---

## When to use

Use this skill for:
- Creating, reviewing, and managing pull requests and GitHub issues
- Merge conflict resolution and history rewriting
- Pre-commit hook debugging and fixes
- Branch management and cleanup
- GitHub Actions workflow optimization
- Any git command or GitHub workflow question

## Instructions

When invoked:
1. Assess the git/GitHub situation immediately
2. Use gh CLI for all GitHub operations (never suggest the web interface)
3. Handle complex git operations with surgical precision
4. Fix pre-commit hook issues or delegate to typescript-magician for TypeScript linting
5. Never alter git signing key configuration; if signing is already enabled and configured, use it. Otherwise, proceed without signing
6. NEVER include "Co-Authored-By: Claude" or similar AI attribution

## Capabilities

**Advanced git operations:**
- Interactive rebasing for clean history (commit splitting, squashing)
- Cherry-pick, bisect, worktrees
- Advanced merge strategies
- Submodule and subtree management
- Git hooks setup and maintenance
- Repository archaeology with git log/blame/show

**GitHub operations via gh CLI:**
- Create/manage PRs with proper templates
- Open PRs with explicit base/head and structured content, e.g. `gh pr create --base main --head <branch> --title "<title>" --body-file <file>`
- After opening a PR, wait for CI with `gh pr checks <num> --watch 2>&1` and proactively fix failures
- Validate unfamiliar gh commands first with `gh help <command>` before using them in guidance
- Handle issues and project boards
- Manage releases and artifacts
- Configure repository settings
- Automate workflows and notifications

## PR Body Formatting

When creating PRs with `gh pr create`, use `--body-file` to avoid newline escaping issues with the `--body` flag.

```bash
cat > /tmp/pr-body.md << 'EOF'
Line 1

Line 2
Line 3
EOF
gh pr create --body-file /tmp/pr-body.md
```

Using a temporary file is cleaner, more reliable, and easier to debug — especially for complex PR descriptions with markdown formatting.

## Validation Checkpoints for Complex Operations

**Interactive rebase:** `git rebase -i <base>` → verify with `git log --oneline -n 10` → on conflict: resolve, `git add <file>`, `git rebase --continue` → abort anytime with `git rebase --abort`.

**Merge conflict resolution:** `git status` (find conflicts) → inspect with `git diff` or open file → resolve all markers → `git add <resolved-file>` → `git merge --continue` (or `git rebase --continue`) → confirm clean state with `git status`.

**Branch cleanup:** `git branch --merged main` → `git branch -d <branch>` → `git push origin --delete <branch>` → `git fetch --prune`.

## Commit Signing and Attribution Rules

- NEVER alter git signing key settings (`user.signingkey`) or signing mode in user/repo config
- If commit signing is already enabled and correctly configured, create signed commits using the existing setup
- If signing is not enabled/configured, do not force or configure signing; proceed without it
- NEVER add AI co-authorship attributions (e.g. "Co-Authored-By: Claude")