Git Worktree Skill for Claude Code

Claude Code skills let you wire repeatable workflows directly into the agent. A git worktree skill teaches Claude when to create a worktree, how to name it, where to put it, and how to clean it up — without you having to remind it. This page covers installation, customization, and the team patterns that emerged in 2026.

Quick orient: skill vs flag

The --worktree flag is the one-shot CLI option. A skill is a persistent, project-aware policy: it tells Claude when to use a worktree, how to name it, and when not to. Skills run inside any session — including web, IDE, and SDK — and survive across runs.

What a Git Worktree Skill Actually Contains

Skills are stored under ~/.claude/skills/<skill-name>/ or your project's .claude/skills/ directory. A worktree skill has three files that matter:

Skill directory layout

.claude/skills/git-worktree/
├── SKILL.md           # the trigger and instructions
├── conventions.md     # team naming + path policy
└── cleanup.md         # rules for removing stale worktrees

The SKILL.md file has a frontmatter block — a name and description that tell Claude when to invoke the skill. The description is what gets matched against the user's request, so write it like a search query, not a marketing pitch.

Install a Starter Skill in 60 Seconds

The fastest way to bootstrap is to drop a single SKILL.md into your project:

Minimal starter skill

mkdir -p .claude/skills/git-worktree
cat > .claude/skills/git-worktree/SKILL.md <<'EOF'
---
name: git-worktree
description: |
  Use this skill when the user asks to start parallel work on a
  feature, fix, or experiment. Spawn a new git worktree under
  ../wt/ following the team convention. Trigger on phrases:
  "in a worktree", "new branch in parallel", "isolated session",
  "side experiment".
---

# Git Worktree Skill

When this skill activates:

1. Read the current branch and the user's intent.
2. Pick a short kebab-case slug from the intent (max 4 words).
3. Run: git worktree add ../wt/\${slug} -b \${slug}
4. cd into the new worktree and confirm with: git worktree list
5. On session end, prompt the user before removing.
EOF

Restart your Claude Code session (or run /skills reload) and the skill is live. Phrase your next request like “start this in a worktree” and Claude will pick the skill up.

Customize for Your Team

The default skill above is intentionally bare. Real teams add three policies on top:

Policy 1: directory layout

Most teams pick one of two layouts: ../wt/<slug> (siblings of the main repo) or ~/wt/<project>/<slug> (centralized). The skill should mention one explicitly so Claude doesn't guess. See the best practices guide for tradeoffs.

Policy 2: branch naming prefix

If your team uses feature/, fix/, hotfix/ prefixes, hard-code the picker into the skill. Otherwise Claude will guess based on the request and sometimes guess wrong.

Policy 3: cleanup behavior

By default the skill should prompt before deleting. Once you trust it, you can flip a flag to auto-remove when the worktree has no uncommitted changes. Don't auto-remove worktrees with dirty state — that path leads to dirty worktree errors and lost work.

The AGENTS.md Companion File

Skills work best when paired with an AGENTS.md at the repo root that documents the team's worktree conventions for humans too. Claude reads it on every session and applies it as a baseline policy.

AGENTS.md worktree section

# AGENTS.md (excerpt)

## Worktrees

- Always work in a worktree for parallel tasks
- Place new worktrees under ../wt/
- Use the slug pattern <type>-<short-title> (e.g. fix-auth-redirect)
- Never delete a worktree with uncommitted changes
- On session end, list all worktrees and prompt before removing

See https://gitworktree.org/ai-tools/claude-code for more.

What a Real Skill-Driven Session Looks Like

You say: “Try fixing the auth redirect bug in parallel — don't touch my current branch.”
The skill activates on the phrase “in parallel”.
Claude picks the slug fix-auth-redirect, runs git worktree add ../wt/fix-auth-redirect -b fix-auth-redirect, and switches into it.
It investigates the bug, runs the tests, makes the fix.
On exit, it shows the diff and asks “Remove worktree? (it has no uncommitted changes)”.

Without a skill, every one of those steps requires explicit instruction. With the skill, the only thing you said was the first sentence.

Skill vs Flag vs Plain Git

Aspect	Plain Git	--worktree flag	Skill
Triggered by	You typing	CLI flag	Natural language
Knows team conventions	No	No	Yes
Cleanup prompt	No	Yes (default)	Configurable
Survives across sessions	Manual	Per invocation	Persistent

FAQ

Do skills replace the --worktree flag?

No. The flag is a CLI shortcut for one-shot use. A skill is for repeated, opinionated use. Most teams have both — the flag for quick experiments, the skill for default behavior.

Can I scope a skill to one project?

Yes. Put it in the project's .claude/skills/ instead of the user-level ~/.claude/skills/. The project-level skill overrides the user-level one when both match.

Will the skill auto-delete my work?

Only if you explicitly opt in. The recommended pattern is to prompt before deletion and refuse to delete worktrees with uncommitted changes. Read git worktree remove for the underlying command behavior.

Does this work with Codex or Cursor?

The skill abstraction is Claude Code-specific. For Codex and Cursor you can get similar behavior with their respective custom-instruction systems, but the file format and trigger model differ.

Where do I see what skills are active?

Run /skills list inside Claude Code. Project and user skills both show, with their match descriptions.