using-git-worktrees
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."
Worktree Creation
Use scripts/worktree-setup <branch-name> to handle directory selection, safety verification, dependency installation, and baseline testing in one step.
The script auto-detects the worktree directory (.worktrees/ > worktrees/ > CLAUDE.md preference), verifies gitignore, installs deps, and runs baseline tests. If no directory is auto-detected, it exits with a suggestion — the skill then asks the user and re-runs with --dir <path>.
Options: --dir <path> (override directory), --no-install, --no-test
Exit codes: 0 = ready + tests pass, 1 = fatal, 2 = created but tests fail/not found
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 |
Red Flags
Never: Create worktree without verifying ignored (project-local), skip baseline test verification, proceed with failing tests without asking, assume directory location.
Always: Follow directory priority (existing > CLAUDE.md > ask), verify ignored, auto-detect and run project setup, verify clean test baseline.
Integration
Called by: brainstorming (Phase 4), plan-execution Pairs with: finishing-a-development-branch (cleanup after work complete)
For detailed creation steps, setup commands, and example workflow, see references/creation-steps.md.
More from hjewkes/agent-skills
self-improve
Use when a session produced reusable insights, when the user says "learn from this", "remember this", or "improve yourself", or after completing a complex task where patterns were discovered
64md-render
Use when asked to render, preview, or view a markdown file in the browser. Triggers on "render markdown", "preview this", "show me this document", "open in browser".
21code-review
Unified code review system — dispatches the right review agents for the situation. Use when reviewing code for quality, bugs, compliance, or before merging.
17skills-management
Use when creating, finding, installing, reviewing, or managing Claude Code skills — covers skill authoring, discovery, conventions, and lifecycle management
14github-pr
GitHub PR workflow — creating PRs, posting automated review comments, managing PR feedback cycles. Use when code is reviewed and ready for GitHub.
14buildkite
Buildkite CI/CD integration. Use when the user needs to check build status, trigger builds, read build logs, debug failures, manage pipelines, or any Buildkite workflow. Triggers include "buildkite", "build", "pipeline", "CI", "deploy", "build log", "build failed".
14