agentleFS
Sign inStart free
I-OnlabsI-Onlabs/claude-code-skills/using-git-worktrees/SKILL.md

using-git-worktrees

Skill4 starsChanged 15 days agoMITView on GitHub

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

  • Installs packages

We split this skill into the rules it gives an agent

12 rules. 1 is common, 10 are distinctive, and 1 is very specific to this project.

  • 1

    Common

    Most of the 178 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow this priority order:

    line 18
  2. Very specific:

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

    line 28
  3. Distinctive:

    If preference specified: Use it without asking.

    line 36
  4. Distinctive:

    If no directory exists and no CLAUDE.md preference:

    line 40
  5. Distinctive:

    Add appropriate line to .gitignore

    line 65
  6. Common:

    Run tests to ensure worktree starts clean:

    line 122
  7. Distinctive:

    Fix: Always grep .gitignore before creating project-local worktree

    line 160
  8. Distinctive:

    Fix: Follow priority: existing > CLAUDE.md > ask

    line 164
  9. Distinctive:

    Create worktree without .gitignore verification (project-local)

    line 193
  10. Distinctive:

    Follow directory priority: existing > CLAUDE.md > ask

    line 200
  11. Distinctive:

    Verify .gitignore for project-local

    line 201
  12. Distinctive:

    Verify clean test baseline

    line 203

“Common” is measured: kept by at least 6 in 10 of the 178 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

# 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.

2. Check CLAUDE.md

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

If preference specified: Use it without asking.

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify .gitignore before creating worktree:

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

If NOT in .gitignore:

Per Jesse's rule "Fix broken things immediately":

  1. Add appropriate line to .gitignore
  2. Commit the change
  3. Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.

For Global Directory (~/.config/superpowers/worktrees)

No .gitignore verification needed - outside project entirely.

Creation Steps

1. Detect Project Name

project=$(basename "$(git rev-parse --show-toplevel)")

2. Create Worktree

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Run Project Setup

Auto-detect and run appropriate setup:

# 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

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

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

If tests pass: Report ready.

5. Report Location

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

Quick Reference

SituationAction
.worktrees/ existsUse it (verify .gitignore)
worktrees/ existsUse it (verify .gitignore)
Both existUse .worktrees/
Neither existsCheck CLAUDE.md → Ask user
Directory not in .gitignoreAdd it immediately + commit
Tests fail during baselineReport failures + ask
No package.json/Cargo.tomlSkip dependency install

Common Mistakes

Skipping .gitignore verification

  • Problem: Worktree contents get tracked, pollute git status
  • Fix: Always grep .gitignore before creating project-local worktree

Assuming directory location

  • Problem: Creates inconsistency, violates project conventions
  • Fix: Follow priority: existing > CLAUDE.md > ask

Proceeding with failing tests

  • Problem: Can't distinguish new bugs from pre-existing issues
  • Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

  • Problem: Breaks on projects using different tools
  • Fix: Auto-detect from project files (package.json, etc.)

Example Workflow

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

  • Create worktree without .gitignore verification (project-local)
  • Skip baseline test verification
  • Proceed with failing tests without asking
  • Assume directory location when ambiguous
  • Skip CLAUDE.md check

Always:

  • Follow directory priority: existing > CLAUDE.md > ask
  • Verify .gitignore for project-local
  • Auto-detect and run project setup
  • Verify clean test baseline

Integration

Called by:

  • brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows
  • Any skill needing isolated workspace

Pairs with:

  • finishing-a-development-branch - REQUIRED for cleanup after work complete
  • executing-plans or subagent-driven-development - Work happens in this worktree

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free