{"id":"2166cf6c-2e97-4f85-ba62-6298dbdc7ce1","shortId":"fKNasb","kind":"skill","title":"using-git-worktrees","tagline":"Git worktree–based workspace isolation for parallel or non-disruptive development. Use when work must occur without modifying or interfering with the current working tree.","description":"# Using Git Worktrees\n\n## Overview\n\nGit worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.\n\n**Core principle:** Systematic directory selection + safety verification = reliable isolation.\n\n**Announce at start:** \"I'm using the using-git-worktrees skill to set up an isolated workspace.\"\n\n## Directory Selection Process\n\nFollow this priority order:\n\n### 1. Check Existing Directories\n\n```bash\n# Check in priority order\nls -d .worktrees 2>/dev/null     # Preferred (hidden)\nls -d worktrees 2>/dev/null      # Alternative\n```\n\n**If found:** Use that directory. If both exist, `.worktrees` wins.\n\n### 2. Check CLAUDE.md\n\n```bash\ngrep -i \"worktree.*director\" CLAUDE.md 2>/dev/null\n```\n\n**If preference specified:** Use it without asking.\n\n### 3. Ask User\n\nIf no directory exists and no CLAUDE.md preference:\n\n```\nNo worktree directory found. Where should I create worktrees?\n\n1. .worktrees/ (project-local, hidden)\n2. ~/.config/superpowers/worktrees/<project-name>/ (global location)\n\nWhich would you prefer?\n```\n\n## Safety Verification\n\n### For Project-Local Directories (.worktrees or worktrees)\n\n**MUST verify .gitignore before creating worktree:**\n\n```bash\n# Check if directory pattern in .gitignore\ngrep -q \"^\\.worktrees/$\" .gitignore || grep -q \"^worktrees/$\" .gitignore\n```\n\n**If NOT in .gitignore:**\n\nPer Jesse's rule \"Fix broken things immediately\":\n1. Add appropriate line to .gitignore\n2. Commit the change\n3. Proceed with worktree creation\n\n**Why critical:** Prevents accidentally committing worktree contents to repository.\n\n### For Global Directory (~/.config/superpowers/worktrees)\n\nNo .gitignore verification needed - outside project entirely.\n\n## Creation Steps\n\n### 1. Detect Project Name\n\n```bash\nproject=$(basename \"$(git rev-parse --show-toplevel)\")\n```\n\n### 2. Create Worktree\n\n```bash\n# Determine full path\ncase $LOCATION in\n  .worktrees|worktrees)\n    path=\"$LOCATION/$BRANCH_NAME\"\n    ;;\n  ~/.config/superpowers/worktrees/*)\n    path=\"~/.config/superpowers/worktrees/$project/$BRANCH_NAME\"\n    ;;\nesac\n\n# Create worktree with new branch\ngit worktree add \"$path\" -b \"$BRANCH_NAME\"\ncd \"$path\"\n```\n\n### 3. Run Project Setup\n\nAuto-detect and run appropriate setup:\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n### 4. Verify Clean Baseline\n\nRun tests to ensure worktree starts clean:\n\n```bash\n# Examples - use project-appropriate command\nnpm test\ncargo test\npytest\ngo test ./...\n```\n\n**If tests fail:** Report failures, ask whether to proceed or investigate.\n\n**If tests pass:** Report ready.\n\n### 5. Report Location\n\n```\nWorktree ready at <full-path>\nTests passing (<N> tests, 0 failures)\nReady to implement <feature-name>\n```\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| `.worktrees/` exists | Use it (verify .gitignore) |\n| `worktrees/` exists | Use it (verify .gitignore) |\n| Both exist | Use `.worktrees/` |\n| Neither exists | Check CLAUDE.md → Ask user |\n| Directory not in .gitignore | Add it immediately + commit |\n| Tests fail during baseline | Report failures + ask |\n| No package.json/Cargo.toml | Skip dependency install |\n\n## Common Mistakes\n\n**Skipping .gitignore verification**\n- **Problem:** Worktree contents get tracked, pollute git status\n- **Fix:** Always grep .gitignore before creating project-local worktree\n\n**Assuming directory location**\n- **Problem:** Creates inconsistency, violates project conventions\n- **Fix:** Follow priority: existing > CLAUDE.md > ask\n\n**Proceeding with failing tests**\n- **Problem:** Can't distinguish new bugs from pre-existing issues\n- **Fix:** Report failures, get explicit permission to proceed\n\n**Hardcoding setup commands**\n- **Problem:** Breaks on projects using different tools\n- **Fix:** Auto-detect from project files (package.json, etc.)\n\n## Example Workflow\n\n```\nYou: I'm using the using-git-worktrees skill to set up an isolated workspace.\n\n[Check .worktrees/ - exists]\n[Verify .gitignore - contains .worktrees/]\n[Create worktree: git worktree add .worktrees/auth -b feature/auth]\n[Run npm install]\n[Run npm test - 47 passing]\n\nWorktree ready at /Users/jesse/myproject/.worktrees/auth\nTests passing (47 tests, 0 failures)\nReady to implement auth feature\n```\n\n## Red Flags\n\n**Never:**\n- Create worktree without .gitignore verification (project-local)\n- Skip baseline test verification\n- Proceed with failing tests without asking\n- Assume directory location when ambiguous\n- Skip CLAUDE.md check\n\n**Always:**\n- Follow directory priority: existing > CLAUDE.md > ask\n- Verify .gitignore for project-local\n- Auto-detect and run project setup\n- Verify clean test baseline\n\n## Integration\n\n**Called by:**\n- **brainstorming** Skillc(Phase 4) - REQUIRED when design is approved and implementation follows\n- Any skill needing isolated workspace\n\n**Pairs with:**\n- **finishing-a-development-branch** Skill - REQUIRED for cleanup after work complete\n- **executing-plans** or **subagent-driven-development** Skill - Work happens in this worktree","tags":["using","git","worktrees","agent","skills","library","codingcossack","agent-framework","agent-skills","agent-system","agent-workflow","agentic-workflow"],"capabilities":["skill","source-codingcossack","skill-using-git-worktrees","topic-agent-framework","topic-agent-skills","topic-agent-system","topic-agent-workflow","topic-agentic-workflow","topic-ai-agents","topic-anthropic","topic-claude","topic-claude-code","topic-claude-skills","topic-claude-skills-hub","topic-claude-skills-libary"],"categories":["agent-skills-library"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/CodingCossack/agent-skills-library/using-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add CodingCossack/agent-skills-library","source_repo":"https://github.com/CodingCossack/agent-skills-library","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 17 github stars · SKILL.md body (5,272 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T07:01:19.860Z","embedding":null,"createdAt":"2026-04-18T23:06:41.317Z","updatedAt":"2026-04-23T07:01:19.860Z","lastSeenAt":"2026-04-23T07:01:19.860Z","tsv":"'/.config/superpowers/worktrees':163,240,280,282 '/cargo.toml':454 '/dev/null':99,106,128 '/users/jesse/myproject/.worktrees/auth':582 '0':405,587 '1':86,156,213,250 '2':98,105,118,127,162,219,264 '3':136,223,301 '4':355,653 '47':577,585 '5':396 'accident':231 'action':413 'add':214,294,440,567 'allow':44 'altern':107 'alway':472,623 'ambigu':619 'announc':61 'appropri':215,310,371 'approv':658 'ask':135,137,385,434,450,495,614,629 'assum':481,615 'auth':592 'auto':306,531,637 'auto-detect':305,530,636 'b':296,569 'base':7 'baselin':358,447,606,646 'basenam':256 'bash':90,121,186,254,267,312,366 'brainstorm':650 'branch':48,278,284,291,297,673 'break':523 'broken':210 'bug':505 'build':327 'call':648 'cargo':326,375 'cargo.toml':324 'case':271 'cd':299 'chang':222 'check':87,91,119,187,432,556,622 'claude.md':120,126,145,433,494,621,628 'clean':357,365,644 'cleanup':677 'command':372,521 'commit':220,232,443 'common':458 'complet':680 'contain':561 'content':234,465 'convent':489 'core':52 'creat':37,154,184,265,287,476,485,563,597 'creation':227,248 'critic':229 'current':28 'd':96,103 'depend':456 'design':656 'detect':251,307,532,638 'determin':268 'develop':16,672,688 'differ':527 'director':125 'directori':55,79,89,112,141,149,176,189,239,436,482,616,625 'disrupt':15 'distinguish':503 'download':353 'driven':687 'ensur':362 'entir':247 'esac':286 'etc':537 'exampl':367,538 'execut':682 'executing-plan':681 'exist':88,115,142,415,421,427,431,493,509,558,627 'explicit':515 'f':315,323,331,340,348 'fail':382,445,498,611 'failur':384,406,449,513,588 'featur':593 'feature/auth':570 'fi':320,328,338,345,354 'file':535 'finish':670 'finishing-a-development-branch':669 'fix':209,471,490,511,529 'flag':595 'follow':82,491,624,661 'found':109,150 'full':269 'get':466,514 'git':3,5,32,35,70,257,292,469,547,565 'gitignor':182,192,196,200,204,218,242,419,425,439,461,474,560,600,631 'global':164,238 'go':346,351,378 'go.mod':349 'grep':122,193,197,473 'happen':691 'hardcod':519 'hidden':101,161 'immedi':212,442 'implement':409,591,660 'inconsist':486 'instal':319,335,344,457,573 'integr':647 'interf':25 'investig':390 'isol':9,38,60,77,554,665 'issu':510 'jess':206 'line':216 'local':160,175,479,604,635 'locat':165,272,277,398,483,617 'ls':95,102 'm':65,542 'mistak':459 'mod':352 'modifi':23 'multipl':47 'must':20,180 'name':253,279,285,298 'need':244,664 'neither':430 'never':596 'new':290,504 'node.js':313 'non':14 'non-disrupt':13 'npm':318,373,572,575 'occur':21 'order':85,94 'outsid':245 'overview':34 'package.json':316,453,536 'package.json/cargo.toml':452 'pair':667 'parallel':11 'pars':260 'pass':393,403,578,584 'path':270,276,281,295,300 'pattern':190 'per':205 'permiss':516 'phase':652 'pip':334 'plan':683 'poetri':343 'pollut':468 'pre':508 'pre-exist':507 'prefer':100,130,146,169 'prevent':230 'principl':53 'prioriti':84,93,492,626 'problem':463,484,500,522 'proceed':224,388,496,518,609 'process':81 'project':159,174,246,252,255,283,303,370,478,488,525,534,603,634,641 'project-appropri':369 'project-loc':158,173,477,602,633 'pyproject.toml':341 'pytest':377 'python':329 'q':194,198 'quick':410 'r':336 'readi':395,400,407,580,589 'red':594 'refer':411 'reliabl':59 'report':383,394,397,448,512 'repositori':43,236 'requir':654,675 'requirements.txt':332,337 'rev':259 'rev-pars':258 'rule':208 'run':302,309,359,571,574,640 'rust':321 'safeti':57,170 'select':56,80 'set':74,551 'setup':304,311,520,642 'share':40 'show':262 'show-toplevel':261 'simultan':49 'situat':412 'skill':72,549,663,674,689 'skill-using-git-worktrees' 'skillc':651 'skip':455,460,605,620 'source-codingcossack' 'specifi':131 'start':63,364 'status':470 'step':249 'subag':686 'subagent-driven-develop':685 'switch':51 'systemat':54 'test':360,374,376,379,381,392,402,404,444,499,576,583,586,607,612,645 'thing':211 'tool':528 'topic-agent-framework' 'topic-agent-skills' 'topic-agent-system' 'topic-agent-workflow' 'topic-agentic-workflow' 'topic-ai-agents' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-claude-skills-hub' 'topic-claude-skills-libary' 'toplevel':263 'track':467 'tree':30 'use':2,17,31,66,69,110,132,368,416,422,428,526,543,546 'user':138,435 'using-git-worktre':1,68,545 'verif':58,171,243,462,601,608 'verifi':181,356,418,424,559,630,643 'violat':487 'whether':386 'win':117 'without':22,50,134,599,613 'work':19,29,45,679,690 'workflow':539 'workspac':8,39,78,555,666 'worktre':4,6,33,36,71,97,104,116,124,148,155,157,177,179,185,195,199,226,233,266,274,275,288,293,363,399,414,420,429,464,480,548,557,562,564,566,579,598,694 'worktrees/auth':568 'would':167","prices":[{"id":"a47b17e0-5609-4e22-a6bf-8a2d2875cc87","listingId":"2166cf6c-2e97-4f85-ba62-6298dbdc7ce1","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"CodingCossack","category":"agent-skills-library","install_from":"skills.sh"},"createdAt":"2026-04-18T23:06:41.317Z"}],"sources":[{"listingId":"2166cf6c-2e97-4f85-ba62-6298dbdc7ce1","source":"github","sourceId":"CodingCossack/agent-skills-library/using-git-worktrees","sourceUrl":"https://github.com/CodingCossack/agent-skills-library/tree/main/skills/using-git-worktrees","isPrimary":false,"firstSeenAt":"2026-04-18T23:06:41.317Z","lastSeenAt":"2026-04-23T07:01:19.860Z"}],"details":{"listingId":"2166cf6c-2e97-4f85-ba62-6298dbdc7ce1","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"CodingCossack","slug":"using-git-worktrees","github":{"repo":"CodingCossack/agent-skills-library","stars":17,"topics":["agent-framework","agent-skills","agent-system","agent-workflow","agentic-workflow","ai-agents","anthropic","claude","claude-code","claude-skills","claude-skills-hub","claude-skills-libary","code-review","codex","context-engineering","debugging","developer-workflow"],"license":null,"html_url":"https://github.com/CodingCossack/agent-skills-library","pushed_at":"2026-01-03T20:02:38Z","description":"Coding agent skills library for programming workflows | Claude Skills, Codex Skills | Forked from obra/superpower","skill_md_sha":"9ec7648c60d8e60d5c2332a38849d50e6c3f18e3","skill_md_path":"skills/using-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/CodingCossack/agent-skills-library/tree/main/skills/using-git-worktrees"},"layout":"multi","source":"github","category":"agent-skills-library","frontmatter":{"name":"using-git-worktrees","description":"Git worktree–based workspace isolation for parallel or non-disruptive development. Use when work must occur without modifying or interfering with the current working tree."},"skills_sh_url":"https://skills.sh/CodingCossack/agent-skills-library/using-git-worktrees"},"updatedAt":"2026-04-23T07:01:19.860Z"}}