$ ~/registry/skill/microsoft-agency-plugins-nori-skills-using-git-worktrees

SKILL

using-git-worktrees

Name: using-git-worktrees
Author: microsoft

Create isolated Git workspaces for parallel development and safer task switching.

Stars

★ 4,934

Source

GitHub

Updated

2026-07-14

// securityLow risk

Prompt only, no code
Open source
Community-trusted· 4.9k

Running security audit…

Credentials
Network egress
Code execution
Data access
Supply chain

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "using-git-worktrees" skill from askskill:
1. Download https://raw.githubusercontent.com/microsoft/FluidFramework/main/.agency/plugins/nori/skills/using-git-worktrees/SKILL.md
2. Save it as ~/.claude/skills/using-git-worktrees/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Develop a new feature in parallel

Prompt

I need to build a new feature without affecting my current branch. Show me how to use git worktree to create an isolated workspace, including the full commands.

Expected

Step-by-step commands to create a new worktree, switch branches, and start development.

Isolate an urgent bug fix

Prompt

I am in the middle of major changes, but I need to fix a production bug urgently. Use a git worktree workflow to create a separate directory for a hotfix and explain how to clean it up afterward.

Expected

Instructions for creating a hotfix worktree, committing changes, merging them, and removing the directory.

Review multiple branches at once

Prompt

I want to open the main branch and a review branch at the same time for comparison. Explain how to manage two separate working directories with git worktree and avoid branch conflicts.

Expected

Guidance for creating separate directories for multiple branches, with safe usage tips.

// docs

<required> *CRITICAL* Add the following steps to your Todo list using TodoWrite:

Find the worktrees directory.

Check existing directories using the Bash tool: ls -d .worktrees 2>/dev/null
If not found, ask me for permission to create a .worktrees directory
If given permission, create .worktrees.

Verify .gitignore before creating a worktree using the Bash tool:

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

If not found, add the appropriate line to the .gitignore immediately.

Create the worktree

Come up with a good branch name based on the request.
Create the worktree with the Bash tool: `git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd into the newly created path with the Bash tool: cd $path

Auto-detect and run project 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

If there is no obvious project setup, you MUST ask me.

Run tests to ensure the worktree is 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.

Report Location

New working directory: <full-path>
Tests passing (<N> tests, 0 failures)
All commands and tools will now refer to: <full-path>

Understand that you are now in a new working directory. Your Bash tool instructions from here on out should refer to the worktree directory, NOT your original directory. This is ABSOLUTELY CRITICAL.

</required>

Maintaining Working Directory in Worktree

CRITICAL: Once you create and enter a worktree, you must stay within it for the entire session.

Rules:

Never use cd .. from within a worktree - It will eventually take you outside the worktree boundary
Always use absolute paths for commands - Use npm run lint from within the worktree, not cd .. && npm run lint
If you need to run root-level commands, use the full worktree path: <bad-example> cd .. && npm run lint </bad-example> <good-example> npm run lint # (from worktree root) </good-example>

<good-example> cd /home/$USER/code/project/.worktrees/branch-name && npm run lint </good-example>

Verify your location frequently:

pwd  # Should show .worktrees/branch-name in path
git branch  # Should show * on your feature branch, not main

If you accidentally exit the worktree:

Immediately recognize it (check if you're on main branch)
Navigate back: cd /full/path/to/.worktrees/your-branch
Verify: git branch should show your branch, not main

Red Flags:

Running git status and seeing "On branch main" when you should be on a feature branch
Running pwd and NOT seeing .worktrees/ in the path
Any cd .. command while in a worktree

Quick Reference

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`.worktree/s does not exist	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install