Agent skill

git-worktree-workflow

Manage git worktrees for branch isolation. Use when creating feature branches, working on isolated tasks, creating PRs, and cleaning up after merge.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/beshkenadze/claude-skills-marketplace/tree/main/skills/development/git-worktree-workflow

SKILL.md

Git Worktree Workflow

Overview

Manage git worktrees for branch isolation within a single Claude session. Worktrees allow working on a feature branch in a separate directory while keeping the main repo untouched.

Directory Structure

MainProjectDir/
├── ProjectDirApp/      # Main repo (claude runs here)
│   └── .claude/        # Claude settings & rules
└── ProjectWorkTree/    # Worktree (isolated branch work)
    └── .claude -> ../ProjectDirApp/.claude  # Symlinked

Commands Reference

Create Worktree

bash
# From main repo directory
git worktree add ../WorktreeName -b branch-name

# Symlink Claude settings
ln -s ../CurrentRepoDir/.claude ../WorktreeName/.claude

List Worktrees

bash
git worktree list

Remove Worktree

bash
git worktree remove ../WorktreeName
git branch -d branch-name  # Delete local branch

Workflows

Phase 1: Create Worktree

Step 1: Create worktree with new branch
        git worktree add ../WorktreeName -b feature/my-feature

Step 2: Symlink Claude settings
        ln -s "$(basename $(pwd))"/.claude ../WorktreeName/.claude

Step 3: Verify setup
        git worktree list

Phase 2: Work in Worktree

Step 1: Work on files in ../WorktreeName/
        Use full paths: ../WorktreeName/src/file.ts

Step 2: Commit changes
        cd ../WorktreeName && git add . && git commit -m "message"

Step 3: Push branch
        cd ../WorktreeName && git push -u origin feature/my-feature

Phase 3: Create PR

Step 1: Create pull request
        cd ../WorktreeName && gh pr create --base main --head feature/my-feature

Step 2: Return PR URL to user
        Wait for approval

Phase 4: After Merge - Cleanup

Step 1: Return to main repo
        cd back to original repo

Step 2: Pull latest main
        git pull origin main

Step 3: Remove worktree
        git worktree remove ../WorktreeName

Step 4: Delete local branch
        git branch -d feature/my-feature

Step 5: Verify cleanup
        git worktree list

Guidelines

Do

  • Symlink .claude/ directory - never copy
  • Use relative paths for symlinks (../RepoName/.claude)
  • Cleanup after PR merge (remove worktree + delete branch)
  • Work in worktree using full paths from main repo
  • Return to main repo before cleanup operations

Don't

  • Copy .claude/ directory (breaks updates)
  • Use absolute paths for symlinks
  • Leave worktrees after merge (clutters disk)
  • Delete worktree before pushing changes

Examples

Example: Feature Development

bash
# Create
git worktree add ../myapp-auth -b feature/oauth2
ln -s ../myapp/.claude ../myapp-auth/.claude

# Work (edit files in ../myapp-auth/)
cd ../myapp-auth
git add . && git commit -m "feat: add OAuth2 support"
git push -u origin feature/oauth2

# PR
gh pr create --base main --head feature/oauth2 --title "Add OAuth2" --body "..."

# After merge - Cleanup
cd ../myapp
git pull origin main
git worktree remove ../myapp-auth
git branch -d feature/oauth2

Example: Bugfix

bash
# Create
git worktree add ../myapp-fix -b bugfix/login-issue
ln -s ../myapp/.claude ../myapp-fix/.claude

# Work & PR
cd ../myapp-fix
# ... fix bug, commit, push, create PR ...

# Cleanup after merge
cd ../myapp
git worktree remove ../myapp-fix
git branch -d bugfix/login-issue

Error Handling

Worktree already exists

bash
# Check existing worktrees
git worktree list

# Remove if stale
git worktree remove ../WorktreeName --force

Branch already exists

bash
# Use existing branch instead of -b
git worktree add ../WorktreeName existing-branch

Unmerged changes in worktree

bash
# Force remove (loses uncommitted changes)
git worktree remove ../WorktreeName --force

Installation

Symlink the helper script (do not copy):

bash
ln -s /path/to/skills/development/git-worktree-workflow/scripts/worktree.sh .claude/scripts/worktree.sh

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

beshkenadze/claude-skills-marketplace

skill-with-scripts

A template for skills that include executable code for deterministic operations.

1 0
Explore
beshkenadze/claude-skills-marketplace

your-skill-name

Brief description of what this Skill does and when to use it. This field is critical for Claude to discover when to invoke your skill.

1 0
Explore
beshkenadze/claude-skills-marketplace

jis-accessibility

Use when auditing websites for Japanese accessibility compliance, checking JIS X 8341-3 conformance, or advising on Japan's Act for Eliminating Discrimination against Persons with Disabilities.

1 0
Explore
beshkenadze/claude-skills-marketplace

meeting-notes

Structure meeting transcripts into organized notes with action items, decisions, and key points. Use when processing meeting recordings or creating meeting summaries.

1 0
Explore
beshkenadze/claude-skills-marketplace

global-accessibility

Use when determining which accessibility law applies to an organization, comparing requirements across jurisdictions (US, EU, Canada, Japan), or planning multi-country accessibility compliance strategy.

1 0
Explore
beshkenadze/claude-skills-marketplace

aoda-compliance

Use when auditing websites or apps for Canadian accessibility law compliance, checking AODA (Ontario) or Accessible Canada Act (federal) requirements, or advising on CAN/ASC-EN 301 549 obligations.

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results