Branch Cleanup Skill | Agent Skills

Branch Cleanup

Delete merged branches (local and optionally remote) with explicit user confirmation, and flag stale unmerged branches for manual review.

Auto-Invoke Triggers

This skill activates when:

Keywords: "cleanup branches", "delete merged branches", "prune old branches", "remove stale branches", "branch cleanup", "remove dead branches"
Command: /cleanup-branches

Arguments

--base <branch> — Base branch for merge check (default: main)
--threshold <months> — Inactivity threshold for stale detection (default: 3)
--remote — Include remote branch deletion
--dry-run — Show what would be deleted without acting

Safety Model

Merged branches: Deletable after explicit user confirmation
Unmerged branches: Never auto-deleted — reported with manual commands only
Dry-run: Available via --dry-run flag to preview actions
Confirmation: Before each destructive step, list branches and ask the user

Workflow

Execute each step below using the Bash tool.

Step 1: Validate Git Repository

git rev-parse --is-inside-work-tree 2>/dev/null || echo "NOT_A_GIT_REPO"

If not a git repo, stop and inform the user.

Step 2: Parse Arguments

Parse $ARGUMENTS for:

--base BRANCH → set BASE_BRANCH=BRANCH (default: main)
--threshold N → set THRESHOLD_MONTHS=N (default: 3)
--remote → set INCLUDE_REMOTE=true (default: false)
--dry-run → set DRY_RUN=true (default: false)

Verify the base branch exists:

git rev-parse --verify "$BASE_BRANCH" 2>/dev/null || echo "BASE_BRANCH_NOT_FOUND"

If the base branch doesn't exist, try master as fallback. If neither exists, stop and inform the user.

Step 3: Fetch Latest Remote State

if ! git fetch --prune 2>/dev/null; then
  echo "Warning: Could not reach remote. Remote branch data may be stale."
fi

Step 4: Display Branch Status Summary

current_branch=$(git branch --show-current)
total_local=$(git branch | wc -l | tr -d ' ')
total_remote=$(git branch -r | grep -v HEAD | wc -l | tr -d ' ')
remote=$(git config --get "branch.$BASE_BRANCH.remote" 2>/dev/null || echo "origin")
merged_local=$(git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | wc -l | tr -d ' ')
merged_remote=$(git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | wc -l | tr -d ' ')

echo "=== BRANCH STATUS ==="
echo "Current branch: $current_branch"
echo "Base branch: $BASE_BRANCH"
echo "Local branches: $total_local ($merged_local merged into $BASE_BRANCH)"
echo "Remote branches: $total_remote ($merged_remote merged into $BASE_BRANCH)"

Present this summary to the user.

Step 5: Local Merged Branch Cleanup

List local branches merged into base (excluding base and current branch):

git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | while IFS= read -r branch; do
  branch="${branch## }"
  last_commit=$(git log -1 --format='%ci' "$branch" 2>/dev/null | cut -d' ' -f1)
  echo "  $branch  (last commit: ${last_commit:-unknown})"
done

Count:

merged_count=$(git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | wc -l | tr -d ' ')
if [ "$merged_count" -eq 0 ]; then
  echo "  (none)"
fi
echo "Found $merged_count local merged branch(es)"

If merged branches exist and not --dry-run:

Ask the user for confirmation using natural conversation: "These N branches are merged into BASE_BRANCH. Delete them?"

If confirmed, delete each branch:

git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | while IFS= read -r branch; do
  branch="${branch## }"
  git branch -d "$branch"
done

If --dry-run: Display what would be deleted but skip the deletion.

Step 6: Remote Merged Branch Cleanup (if --remote)

Only execute if --remote flag was provided.

List remote branches merged into base:

git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | while IFS= read -r branch; do
  branch="${branch## }"
  short_name="${branch#$remote/}"
  last_commit=$(git log -1 --format='%ci' "$branch" 2>/dev/null | cut -d' ' -f1)
  echo "  $short_name  (last commit: ${last_commit:-unknown})"
done

Count:

remote_merged=$(git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | wc -l | tr -d ' ')
if [ "$remote_merged" -eq 0 ]; then
  echo "  (none)"
fi
echo "Found $remote_merged remote merged branch(es)"

If remote merged branches exist and not --dry-run:

Ask the user for confirmation: "These N remote branches are merged. Delete them from $remote?"

If confirmed, delete each remote branch:

git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | while IFS= read -r branch; do
  branch="${branch## }"
  short_name="${branch#$remote/}"
  git push "$remote" --delete "$short_name"
done

If --dry-run: Display what would be deleted but skip the deletion.

Step 7: Stale Unmerged Branch Report

List inactive unmerged branches (past threshold) with ahead/behind counts. Never delete these — only display them.

Calculate threshold:

if [[ "$OSTYPE" == "darwin"* ]]; then
  threshold=$(date -v-${THRESHOLD_MONTHS}m +%s)
else
  threshold=$(date -d "${THRESHOLD_MONTHS} months ago" +%s)
fi

Scan for stale unmerged branches:

echo "=== STALE UNMERGED BRANCHES (manual review required) ==="
git for-each-ref --sort=committerdate --format='%(refname:short) %(committerdate:unix) %(committerdate:relative)' refs/heads/ | while IFS= read -r line; do
  branch=$(echo "$line" | awk '{print $1}')
  timestamp=$(echo "$line" | awk '{print $2}')
  relative=$(echo "$line" | cut -d' ' -f3-)

  [ "$branch" = "$BASE_BRANCH" ] && continue

  if [[ "$timestamp" =~ ^[0-9]+$ ]] && [ "$timestamp" -lt "$threshold" ]; then
    merged=$(git branch --merged "$BASE_BRANCH" | grep -w "$branch" | wc -l | tr -d ' ')
    if [ "$merged" -eq 0 ]; then
      counts=$(git rev-list --left-right --count "$BASE_BRANCH"..."$branch" 2>/dev/null)
      behind=$(echo "$counts" | awk '{print $1}')
      ahead=$(echo "$counts" | awk '{print $2}')
      echo "  $branch ($relative) [ahead $ahead, behind $behind]"
    fi
  fi
done

After listing, suggest manual deletion commands (but never execute them):

To delete these branches manually:
  Local:   git branch -D <branch>
  Remote:  git push origin --delete <branch>

Step 8: Summary Report

Present a summary of all actions taken:

=== CLEANUP SUMMARY ===
Local merged branches deleted: N
Remote merged branches deleted: N (or "skipped — use --remote")
Stale unmerged branches flagged: N (manual review)

Important Caveats

Squash merges: Branches merged via squash-and-merge on GitHub will NOT appear as "merged" in git branch --merged. They show as unmerged even though their changes are in the base branch. Check stale unmerged branches carefully.
Current branch: The current branch is never deleted, even if merged.
Protected branches: main, master, and the base branch are always excluded from deletion.
Remote permissions: Deleting remote branches requires push access to the remote.

Progressive Disclosure

For more details, see:

WORKFLOW.md — Detailed 5-phase methodology
EXAMPLES.md — Usage scenarios with sample output
TROUBLESHOOTING.md — Common issues and solutions

Version

1.0.0

Agent Skills: Branch Cleanup

Install this agent skill to your local

Skill Files