Programming · Automation
using-git-worktrees
/using-git-worktrees
Use this whenever you need to create an isolated workspace.
For whom
- Author
- microsoft ↗
- Repository
- fluidframework ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
Deprecation
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Licence
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use this whenever you need to create an isolated workspace.
Original author description
Use this whenever you need to create an isolated workspace.
How it works
SKILL.md has no level-two headings · 182 lines, 797 words
SKILL.md preview
--- name: using-git-worktrees description: Use this whenever you need to create an isolated workspace. --- <required> *CRITICAL* Add the following steps to your Todo list using TodoWrite: 1. 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`. 2. Verify .gitignore before creating a worktree using the Bash tool: ```bash # 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. 3. 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` 4. Auto-detect and run project setup. ```bash # 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. 5. Run tests to ensure the worktree is clean. ```bash # 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. 6. Report Location ``` New working directory: <full-path> Tests passing (<N> tests, 0 failures) All commands and tools will now refer to: <full-path> ``` 7. 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: 1. Never use cd .. from within a worktree - It will eventually take you outside the worktree boundary 2. Always use absolute paths for commands - Use npm run lint from within the worktree, not cd .. && npm run lint 3. 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> 4. Verify your location frequently: ```bash pwd # Should show .worktrees/branch-name in path git branch # Should show * on your feature branch, not main ``` 5. 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 | # Common Mistakes **Skipping .gitignore verification** - **Problem:** Worktree contents get tracked, pollute git status - **Fix:** Always grep .gitignore before creating project-local worktree **Assuming directory location** - **Problem:** Creates inconsistency, violates project conventions - **Fix:** Follow priority: existing > CLAUDE.md > ask **Missing project installation** - **Problem:** Tests and lint will fail, breaking the project - **Fix:** Always install the project when creating a new worktree **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 .gitignore - contains .worktrees/] [Create worktree: git worktree add .worktrees/auth -b feature/auth] [Run npm install] [Run npm test - 47 passing] Worktree ready at myproject/.worktrees/auth Tests passing (47 tests, 0 failures) Ready to implement auth feature ``` # Red Flags **Never:** - Create worktree without .gitignore verification (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 .gitignore for project-local - Auto-detect and run project setup - Verify clean test baseline
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · microsoft/fluidframework | 96 | MIT |
| jjuraszek/pi-gauntlet | 100 | MIT |
| event4u-app/agent-config | 100 | MIT |
| yusixian/anjian | 100 | MIT |
| GanyuanRan/Aegis | 100 | MIT |
| sitien173/refract | 100 | MIT |
| innei/ryugi | 100 | MIT |
| rootcastleco/rei-skills | 100 | MIT |
| davila7/claude-code-templates | 100 | MIT |
Database snapshot: 13.11.2026 · package version 9cbe8beedccc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100git-worktrees
Isolated workspace creation for parallel development work. Use when starting feature work that needs isolation from the current workspace. Creates git worktrees with proper setup and safety verification. - 100use-git-worktree
This skill should be used when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification - 95dev_manage_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. Triggers: worktree, git worktree, isolated workspace, feature branch… - 100git-worktree
Manage Git worktrees for parallel development. Use when creating isolated workspaces for parallel feature work, running multiple Claude sessions simultaneously, or managing concurrent development tasks. - 100git-worktree
Use when work needs an isolated git worktree, such as parallel feature branches, reviewing a PR without disturbing the current checkout, or cleaning up old worktrees. - 100loom-using-git-worktrees
Create an isolated git branch/worktree before coding begins. Verifies baseline tests pass. Use when: starting implementation work that should be isolated from the current branch or workspace.