using-git-worktrees

Overview of using-git-worktrees skill

What the using-git-worktrees skill does

The using-git-worktrees skill helps an agent create a separate Git worktree for new work instead of reusing your current checkout. Its real job is not just “run git worktree add,” but choose a sensible directory, verify that local worktree folders are safely ignored, and avoid contaminating the main workspace.

Who should install it

This skill is best for people who regularly:

• start feature work while keeping current changes untouched
• review or implement multiple branches in parallel
• want safer AI-driven coding workflows with less branch-switching risk
• need a repeatable way to create isolated workspaces across projects

If you often ask an assistant to “start this in a separate branch” or “work without touching my current tree,” using-git-worktrees is a strong fit.

The job to be done

Users care about one outcome: start implementation in an isolated workspace with minimal setup mistakes. The using-git-worktrees skill is useful because it adds a decision process before creation:

• prefer an existing project worktree directory if present
• honor documented repo preference from CLAUDE.md if available
• ask when no safe default exists
• verify ignore behavior before creating project-local worktrees

That makes it more reliable than a generic prompt that jumps straight to shell commands.

What makes it different from a normal prompt

A normal prompt might know Git worktrees conceptually, but still miss repo-specific setup details. This skill gives the agent a defined order of operations and safety checks, especially around directory placement and .gitignore handling. That is the main differentiator for using-git-worktrees for Git Workflows: lower setup guesswork, not more Git theory.

When this skill is a poor fit

Skip using-git-worktrees if:

• you always work in a single branch and single directory
• your environment forbids extra working directories
• you only need a quick branch switch, not isolated execution
• your team already has a hardcoded wrapper script that fully replaces this decision logic

In those cases, a plain shell command or internal workflow may be faster.

How to Use using-git-worktrees skill

Install context for using-git-worktrees

Install from the obra/superpowers skill collection:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

After installation, use it when you are about to begin work that should not reuse the current checkout.

How users actually invoke the skill

The repository explicitly signals that the agent should announce usage at the start. In practice, your request should make the isolation requirement obvious, for example:

• “Use using-git-worktrees and set up an isolated workspace for this feature.”
• “Before implementing, create a worktree for branch feature/auth-refresh.”
• “Use the using-git-worktrees skill so my current changes stay untouched.”

This increases the chance the agent follows the skill instead of improvising.

What input the skill needs

For good results, provide:

• the target branch name
• whether this is a new branch or an existing branch
• whether you prefer project-local or global worktree storage
• any repo-specific constraints such as “must stay under project root”

Minimal useful input:

• branch/task name
• permission to create a worktree

Better input:

• branch name
• desired directory policy
• whether uncommitted work exists in the current checkout
• what should happen after setup, such as “then start implementation”

The built-in directory selection logic

The using-git-worktrees skill is most valuable in its directory-selection workflow. It follows this priority:

1. use .worktrees if it already exists
2. otherwise use worktrees if it exists
3. otherwise inspect CLAUDE.md for a documented preference
4. otherwise ask the user to choose between:
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

This matters because worktree sprawl becomes a real maintenance problem if each session invents a new location.

Safety checks before project-local creation

A key adoption detail: if the worktree will live inside the repository, the skill requires verification that the directory is ignored before creating it. That protects against accidentally tracking worktree folders or cluttering status output.

This is a meaningful advantage over ad hoc usage. If your team expects project-local worktrees, make sure .worktrees/ or worktrees/ is ignored by Git before relying on the workflow.

Strong prompt patterns for using-git-worktrees usage

Weak prompt:

• “Start working on OAuth cleanup.”

Stronger prompt:

• “Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.”

Why this is better:

• names the skill
• gives a branch target
• states directory preference
• tells the agent what comes next

Suggested workflow after creation

A practical sequence for using-git-worktrees usage:

1. ask the agent to use the skill
2. confirm the worktree location and branch name
3. have the agent move work into the new workspace
4. only then start edits, tests, or implementation planning

This sequence is especially useful when your current checkout already has uncommitted changes.

Files to read first in the repository

There is only one meaningful source file here: SKILL.md.

Read it for:

• the exact directory priority order
• the user prompt expected when no preference exists
• the ignore verification requirement
• the activation phrasing that tells the agent to announce skill use

This skill is lightweight, so the main adoption question is whether that logic matches your team’s Git workflow.

Practical constraints to know before relying on it

The skill is intentionally narrow. It does not appear to provide:

• wrapper scripts
• automation helpers
• branch naming enforcement
• cleanup routines for stale worktrees
• platform-specific fallbacks

So using-git-worktrees install gives you decision guidance, not a full worktree management system. If you need lifecycle automation, pair it with your own shell tooling.

using-git-worktrees skill FAQ

Is using-git-worktrees good for beginners?

Yes, if the beginner already understands basic branches and wants a safer “don’t touch my current workspace” workflow. It is not a Git tutorial; it is a structured setup skill. A complete beginner may still need help understanding what a worktree is and why it differs from cloning.

What problem does this solve better than ordinary prompts?

Ordinary prompts often skip the messy part: where the worktree should live and whether a project-local directory is safely ignored. The using-git-worktrees guide encoded in the skill reduces those setup mistakes and makes agent behavior more consistent.

Do I need project-local worktrees to use it?

No. The skill can steer toward a global location when no local directory exists and no repo preference is documented. That makes it usable even if you do not want extra folders inside the repository.

Can I use using-git-worktrees for existing branches?

Yes. The workflow is still useful when checking out an existing branch into a separate workspace. The main value is isolation, not only branch creation.

When should I not use using-git-worktrees?

Do not use it when:

• you are only making a tiny edit in your current branch
• your team prohibits unmanaged worktree locations
• you already have deterministic internal tooling that handles location and ignore rules
• your repo has unusual Git constraints the skill does not know about

Does this replace Git knowledge?

No. The using-git-worktrees skill improves invocation and setup discipline, but you still need basic Git judgment for branch naming, rebasing, cleanup, and merge strategy.

How to Improve using-git-worktrees skill

Give explicit branch and directory intent

The biggest quality upgrade is to tell the agent both the branch target and the preferred directory policy. Example:

“Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.”

This removes the most common source of ambiguity.

Document preferences in CLAUDE.md

Because the skill checks CLAUDE.md, you can improve future results by documenting:

• preferred worktree directory
• whether project-local worktrees are allowed
• naming conventions for branches or folders

That turns repeated user clarification into repo-level policy.

Preconfigure ignore rules for local directories

If your team wants .worktrees/ or worktrees/ inside the project, add the ignore rule ahead of time. This makes the using-git-worktrees for Git Workflows path smoother because the safety verification passes cleanly instead of forcing discussion mid-task.

Watch for common failure modes

The main failure modes are predictable:

• the agent creates a worktree in an unapproved location
• local worktree folders are not ignored
• the branch name is inferred badly from a vague feature request
• implementation starts in the original checkout before isolation is complete

Most of these come from incomplete prompts, not from the skill itself.

Ask for confirmation before coding starts

A simple improvement prompt:

• “Use using-git-worktrees, then report the final path and branch before making edits.”

This catches mistakes early and is especially useful in repositories with multiple nested folders or unusual policies.

Iterate after the first run

If the first output is acceptable but not ideal, refine the working pattern rather than rewriting everything:

• lock in your preferred directory location
• add a CLAUDE.md note
• standardize branch naming in prompts
• explicitly require confirmation before edits

That makes the using-git-worktrees usage more predictable over time and reduces repeated setup friction.