Agent skill

using-git-worktrees

Use when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.

View SKILL.md on GitHub Repository
Stars 7
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/Bbeierle12/Skill-MCP-Claude/tree/main/skills/using-git-worktrees

SKILL.md

Using Git Worktrees

Core Principle

Isolate feature work. Keep main clean.

Git worktrees let you work on multiple branches simultaneously in separate directories.

When to Use

  • Starting a new feature
  • Working on a bugfix while main development continues
  • Need to context-switch without stashing
  • Want clean separation between work streams

Setup Process

Step 1: Check for Existing Worktree Directory

bash
# Check in priority order
ls -d .worktrees 2>/dev/null    # Preferred (hidden)
ls -d worktrees 2>/dev/null     # Alternative

If found: Use that directory. If both exist: .worktrees wins.

Step 2: Check CLAUDE.md for Preferences

bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

Step 3: If No Directory Exists

Ask the user:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Step 4: Verify .gitignore

bash
# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If not present, add it:

bash
echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore

Creating a Worktree

Standard Creation

bash
# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"

From Existing Branch

bash
git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

Post-Creation Setup

Install Dependencies

bash
# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

Run Initial Tests

bash
# Run test suite
npm test  # or appropriate command

# Report status

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

Worktree Management

List Worktrees

bash
git worktree list

Remove Worktree

bash
# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"

Prune Stale Worktrees

bash
git worktree prune

Best Practices

Naming Convention

  • feature/descriptive-name for features
  • bugfix/issue-number-description for bugs
  • hotfix/critical-issue for urgent fixes

Keep Worktrees Focused

  • One feature per worktree
  • Merge and remove when done
  • Don't let worktrees accumulate

Sync Regularly

bash
# In worktree, get latest from main
git fetch origin
git rebase origin/main

Completion Checklist

When feature is complete:

  1. All tests pass
  2. Code reviewed
  3. Merged to main
  4. Worktree removed
  5. Branch deleted (if desired)
bash
# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name

Announcement Template

At start of worktree creation:

"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."

On completion:

"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"

Recommended Agent Skills

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

Bbeierle12/Skill-MCP-Claude

r3f-materials

Three.js materials in R3F, built-in materials (Standard, Physical, Basic, etc.), ShaderMaterial with custom GLSL, uniforms binding and animation, and material properties. Use when choosing materials, creating custom shaders, or binding dynamic uniforms.

7 1
Explore
Bbeierle12/Skill-MCP-Claude

audio-router

Router for audio domain including playback, analysis, and audio-reactive visuals. Use when implementing any audio functionality including music, sound effects, visualizers, or audio-driven animations. Routes to 3 specialized skills.

7 1
Explore
Bbeierle12/Skill-MCP-Claude

case-studies-reference

Game building mechanics case studies and decision frameworks. Use when designing building systems, evaluating trade-offs, or learning from existing games. Reference-only skill with detailed analysis of Fortnite, Rust, Valheim, Minecraft, No Man's Sky, and Satisfactory building systems.

7 1
Explore
Bbeierle12/Skill-MCP-Claude

brainstorming

Use when starting any feature, project, or design work. Guides collaborative design refinement through incremental questioning before any code is written.

7 1
Explore
Bbeierle12/Skill-MCP-Claude

shader-router

Decision framework for GLSL shader projects. Routes to specialized shader skills (fundamentals, noise, SDF, effects) based on task requirements. Use when starting a shader project or needing guidance on which shader techniques to combine.

7 1
Explore
Bbeierle12/Skill-MCP-Claude

audio-playback

Audio playback using Tone.js including players, transport, scheduling, and loading audio. Use when implementing background music, sound effects, audio synchronization, or timed audio events. Essential for any audio-enabled web application.

7 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results