Agent skill
worktree-aifuun-u-safe
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/worktree-aifuun-u-safe
SKILL.md
Worktree - Git Worktree Management
Manage git worktrees for parallel issue development with interactive selection and cleanup.
Overview
This skill provides comprehensive worktree management for the issue workflow:
What it does:
- List all worktrees with status (active/merged/stale)
- Interactive selection to switch between worktrees
- Clean merged or stale worktrees automatically
- Prune orphaned worktree references
Why it's needed: When working on multiple issues in parallel using worktrees, you need an easy way to see all active work, switch between issues, and clean up completed work. This skill provides a unified interface for all worktree operations.
When to use:
- View all active worktrees and their status
- Quickly switch to a different issue's worktree
- Clean up after merging PRs
- Manage worktree references
Commands
/worktree # Interactive: list + select worktree to switch
/worktree list # List all worktrees with details
/worktree switch <n> # Switch to worktree by number or issue#
/worktree clean # Remove merged/stale worktrees
/worktree prune # Clean up orphaned references
Usage
List Worktrees
Command: /worktree or /worktree list
Output:
π Git Worktrees:
ββββββ¬βββββββββ¬βββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββ
β # β Issue β Branch β Path β Status β
ββββββΌβββββββββΌβββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββΌβββββββββββ€
β 1 β main β main β ~/dev/ai-dev β π Main β
β 2 β #101 β feature/101-remove-taskcreate... β ~/dev/ai-dev-101-remove... β π’ Activeβ
β 3 β #110 β feature/110-compliance... β ~/dev/ai-dev-110-compli... β β
Mergedβ
β 4 β #113 β feature/113-worktree... β ~/dev/ai-dev-113-worktree...β π‘ Currentβ
ββββββ΄βββββββββ΄βββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββ
π‘ Current: #4 (Issue #113)
Status indicators:
- π Main - Main repository worktree
- π’ Active - Issue in progress
- β Merged - PR merged, ready for cleanup
- π‘ Current - You are here
- π΄ Stale - No activity for >30 days
Interactive Switch
Command: /worktree (when run without arguments)
Behavior:
- Show list of all worktrees
- Prompt: "Select worktree to switch (1-4) or 'q' to quit: _"
- User selects number
- Output cd command for easy execution
Example:
Select worktree to switch (1-4) or 'q' to quit: 2
π To switch to worktree #2 (Issue #101), run:
cd ~/dev/ai-dev-101-remove-taskcreate-pattern
Or in a new terminal:
Terminal β New Tab β cd ~/dev/ai-dev-101-remove-taskcreate-pattern
Switch by Number
Command: /worktree switch 2 or /worktree switch #101
Behavior:
- Accept either worktree number (from list) or issue number
- Output cd command for the selected worktree
Clean Merged Worktrees
Command: /worktree clean
Behavior:
- Find all worktrees with status="merged" or "stale"
- Show list and prompt for confirmation
- Remove confirmed worktrees
- Update metadata
Example:
π§Ή Found 2 worktrees ready for cleanup:
#110 - Fix skills compliance (merged 2 days ago)
#108 - Update docs (merged 1 week ago)
Remove these worktrees? [y/N]: y
β
Removed worktree for issue #110
β
Removed worktree for issue #108
πΎ Disk space freed: ~45 MB
Prune References
Command: /worktree prune
Behavior:
- Run
git worktree pruneto clean up orphaned references - Update metadata to remove cleaned entries
Implementation
Script: list_worktrees.py
#!/usr/bin/env python3
"""List all git worktrees with metadata."""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "scripts"))
from worktree_manager import list_worktrees
def format_table(worktrees):
"""Format worktrees as ASCII table."""
# Implementation in scripts/worktree_manager.py
...
if __name__ == "__main__":
worktrees = list_worktrees()
format_table(worktrees)
Script: select_worktree.py
#!/usr/bin/env python3
"""Interactive worktree selection."""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "scripts"))
from worktree_manager import list_worktrees, detect_current_worktree
def prompt_selection(worktrees):
"""Show list and prompt for selection."""
# Display table
print_table(worktrees)
# Prompt
choice = input("\nSelect worktree (1-{}) or 'q' to quit: ".format(len(worktrees)))
if choice.lower() == 'q':
return None
try:
idx = int(choice) - 1
return worktrees[idx]
except (ValueError, IndexError):
print("Invalid selection")
return None
if __name__ == "__main__":
worktrees = list_worktrees()
selected = prompt_selection(worktrees)
if selected:
print(f"\nπ To switch to worktree, run:\n")
print(f" cd {selected['path']}\n")
Script: clean_worktrees.py
#!/usr/bin/env python3
"""Clean up merged/stale worktrees."""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "scripts"))
from worktree_manager import list_worktrees, cleanup_worktree
def find_cleanable(worktrees):
"""Find worktrees that can be cleaned up."""
return [wt for wt in worktrees if wt['status'] in ['merged', 'stale']]
def confirm_cleanup(worktrees):
"""Prompt user to confirm cleanup."""
if not worktrees:
print("No worktrees to clean up")
return []
print(f"π§Ή Found {len(worktrees)} worktrees ready for cleanup:\n")
for wt in worktrees:
print(f" #{wt['issue_number']} - {wt['issue_title']}")
response = input("\nRemove these worktrees? [y/N]: ")
return worktrees if response.lower() == 'y' else []
if __name__ == "__main__":
all_worktrees = list_worktrees()
cleanable = find_cleanable(all_worktrees)
to_remove = confirm_cleanup(cleanable)
for wt in to_remove:
cleanup_worktree(wt['issue_number'])
print(f"β
Removed worktree for issue #{wt['issue_number']}")
Error Handling
No worktrees found:
π No worktrees found
Create one with: /start-issue <number>
Invalid selection:
β Invalid selection
Please enter a number between 1 and 4, or 'q' to quit
Cleanup failed:
β Failed to remove worktree for issue #101
Reasons:
- Directory has uncommitted changes
- Directory is currently in use
Try:
1. Commit or stash changes
2. Close any programs using the directory
3. Run: /worktree clean --force
Examples
Example 1: List and Switch
User says:
"show me all worktrees"
Output:
π Git Worktrees:
[table showing 3 worktrees]
Select worktree to switch (1-3) or 'q' to quit: 2
π To switch to worktree #2 (Issue #101), run:
cd ~/dev/ai-dev-101-remove-taskcreate-pattern
Example 2: Clean Merged Worktrees
User says:
"clean up worktrees"
Output:
π§Ή Found 1 worktree ready for cleanup:
#110 - Fix skills compliance (merged 2 days ago)
Remove these worktrees? [y/N]: y
β
Removed worktree for issue #110
Example 3: Quick Switch
User says:
"switch to issue 101 worktree"
Output:
π To switch to Issue #101 worktree, run:
cd ~/dev/ai-dev-101-remove-taskcreate-pattern
Integration
Created by: /start-issue - Automatically creates worktree metadata
Used by: Developers working on multiple issues in parallel
Cleaned by: /finish-issue - Optionally removes worktree after merge
Workflow:
/start-issue #101 β Creates worktree #1
/start-issue #102 β Creates worktree #2
/worktree β List and switch between #1 and #2
/finish-issue #101 β Removes worktree #1
/worktree clean β Cleanup remaining merged worktrees
Best Practices
- List regularly - Use
/worktreeto see all active work - Clean after merge - Remove worktrees once PR is merged
- Switch via number - Faster than typing full path
- Prune periodically - Clean up orphaned references
Related Skills
- /start-issue - Creates worktrees for new issues
- /finish-issue - Cleans up worktrees after completion
- /status - Shows active work across all worktrees
Version: 1.0.0 Last Updated: 2026-03-10 Changelog:
- v1.0.0 (2026-03-10): Initial release - git worktree management for parallel development Pattern: Tool-Reference (guides Claude through workflow) Compliance: ADR-001 Section 4 β
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?