Using Git Worktrees

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

Security Scan

The skill's instructions match its stated purpose (creating git worktrees) but they instruct the agent to modify the repo and run package installs/tests (which execute arbitrary code) and to auto-commit .gitignore changes without an explicit confirmation step — behavior that warrants caution.

Purpose & Capability

The name and description (create isolated git worktrees) align with the instructions: selecting/creating directories, verifying .gitignore, adding worktrees, running project setup and tests. No unrelated env vars, binaries, or install steps are requested. Minor issues: a grep pattern appears to have a typo ('director' vs 'directory') and the SKILL.md prescribes automatic commits to the repo which may be surprising to users.

Instruction Scope

Instructions tell the agent to read repository files (e.g., CLAUDE.md), run git commands, add lines to .gitignore and commit them, and run package managers and test suites (npm, pip, cargo, go). Running installs/tests can execute arbitrary code (postinstall scripts, build/test hooks) and the SKILL.md implies committing .gitignore changes automatically rather than asking for explicit consent; both increase risk beyond a purely read-only helper.

Install Mechanism

Instruction-only skill with no install spec and no code files. Nothing is written to disk by the skill itself beyond commands the agent is instructed to run in the user's repo.

Credentials

The skill requests no environment variables or external credentials, which is proportional. However, it operates on the user's filesystem (home dir and repo), and invokes package managers and build/test commands that may contact the network and run arbitrary project-defined scripts — a normal part of project setup but a potential execution surface.

Persistence & Privilege

The skill does not request permanent presence or elevated platform privileges. It does instruct the agent to modify project state (add/commit to .gitignore, create worktree directories), which is expected for its purpose but should require explicit user consent to avoid unexpected changes.

What to consider before installing

This skill appears to do what it says (create isolated git worktrees), but its runtime instructions give the agent permission to modify your repository and to run dependency installs and tests — actions that can execute arbitrary code from the project (npm postinstall, test hooks, etc.). Before installing or invoking this skill: 1) Require an explicit confirmation step before it writes/commits anything (especially .gitignore changes). 2) Prefer a dry-run mode that shows proposed git commands and file edits. 3) Back up or stash uncommitted work and ensure the repo is on a safe branch. 4) If you want to limit risk, run the skill only interactively (disable autonomous invocation) or in a sandboxed environment/VM. 5) Note the CLAUDE.md grep likely has a typo ('director' vs 'directory') — verify any automatic conventions the skill uses. If you cannot or do not want the agent to run installs/tests or commit changes automatically, treat the skill as too permissive.

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 directory is ignored before creating worktree:

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored:

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

Situation	Action
.worktrees/ exists	Use it (verify ignored)
worktrees/ exists	Use it (verify ignored)
Both exist	Use .worktrees/
Neither exists	Check CLAUDE.md → Ask user
Directory not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes

Skipping ignore verification

• Problem: Worktree contents get tracked, pollute git status
• Fix: Always use git check-ignore 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 ignored - git check-ignore confirms .worktrees/ is ignored]
[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 verifying it's ignored (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 directory is ignored 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
• subagent-driven-development - REQUIRED before executing any tasks
• executing-plans - REQUIRED before executing any tasks
• Any skill needing isolated workspace

Pairs with:

• finishing-a-development-branch - REQUIRED for cleanup after work complete