{"id":"ffc981b6-1867-40ec-8e8b-f9a686d7d145","shortId":"q9FYyF","kind":"skill","title":"using-git-worktrees","tagline":"Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.","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 directory is ignored before creating worktree:**\n\n```bash\n# Check if directory is ignored (respects local, global, and system gitignore)\ngit check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null\n```\n\n**If NOT ignored:**\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 ignored) |\n| `worktrees/` exists | Use it (verify ignored) |\n| Both exist | Use `.worktrees/` |\n| Neither exists | Check CLAUDE.md → Ask user |\n| Directory not ignored | Add to .gitignore + 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 ignore verification\n\n- **Problem:** Worktree contents get tracked, pollute git status\n- **Fix:** Always use `git check-ignore` before creating project-local worktree\n\n### Assuming directory location\n\n- **Problem:** Creates inconsistency, violates project conventions\n- **Fix:** Follow priority: existing > CLAUDE.md > ask\n\n### Proceeding with failing tests\n\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\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 ignored - git check-ignore confirms .worktrees/ is ignored]\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 verifying it's ignored (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 directory is ignored for project-local\n- Auto-detect and run project setup\n- Verify clean test baseline\n\n## Integration\n\n**Called by:**\n- **brainstorming** (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** - REQUIRED for cleanup after work complete\n- **executing-plans** or **subagent-driven-development** - Work happens in this worktree\n\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["using","git","worktrees","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding"],"capabilities":["skill","source-sickn33","skill-using-git-worktrees","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/using-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34404 github stars · SKILL.md body (5,759 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-22T00:51:54.513Z","embedding":null,"createdAt":"2026-04-18T21:46:55.629Z","updatedAt":"2026-04-22T00:51:54.513Z","lastSeenAt":"2026-04-22T00:51:54.513Z","tsv":"'/.config/superpowers/worktrees':154,245,285,287 '/cargo.toml':458 '/dev/null':90,97,119,198,206 '/users/jesse/myproject/.worktrees/auth':595 '0':410,600 '1':77,147,218,255 '2':89,96,109,118,153,197,205,224,269 '3':127,228,306 '4':360,669 '47':590,598 '5':401 'accident':236 'action':418,721 'add':219,299,444,580 'allow':14,35 'altern':98 'alway':476,638 'ambigu':634 'announc':52 'applic':715 'appropri':220,315,376 'approv':674 'ask':126,128,390,439,454,502,629,644,759 'assum':488,630 'auth':605 'auto':311,538,654 'auto-detect':310,537,653 'b':301,582 'baselin':363,451,621,663 'basenam':261 'bash':81,112,179,259,272,317,371 'boundari':767 'brainstorm':667 'branch':18,39,283,289,296,302,689 'break':530 'broken':215 'bug':512 'build':332 'call':665 'cargo':331,380 'cargo.toml':329 'case':276 'cd':304 'chang':227 'check':78,82,110,180,193,201,437,480,563,570,637 'check-ignor':192,200,479,569 'clarif':761 'claude.md':111,117,136,438,501,636,643 'clean':362,370,661 'cleanup':692 'clear':734 'command':377,528 'commit':225,237,447 'common':462 'complet':695 'confirm':572 'content':239,469 'convent':496 'core':43 'creat':7,28,145,177,270,292,483,492,576,610 'creation':232,253 'criteria':770 'critic':234 'd':87,94 'depend':460 'describ':722,738 'design':672 'detect':256,312,539,655 'determin':273 'develop':688,703 'differ':534 'director':116 'directori':46,70,80,103,132,140,167,173,182,244,441,489,631,640,646 'distinguish':510 'download':358 'driven':702 'ensur':367 'entir':252 'environ':750 'environment-specif':749 'esac':291 'etc':544 'exampl':372,545 'execut':697,717 'executing-plan':696 'exist':79,106,133,420,426,432,436,500,516,565,642 'expert':755 'explicit':522 'f':320,328,336,345,353 'fail':387,449,505,626 'failur':389,411,453,520,601 'featur':606 'feature/auth':583 'fi':325,333,343,350,359 'file':542 'finish':686 'finishing-a-development-branch':685 'fix':214,475,497,518,536 'flag':608 'follow':73,498,639,677 'found':100,141 'full':274 'get':470,521 'git':3,5,23,26,61,191,199,262,297,473,478,554,568,578 'gitignor':190,223,247,446 'global':155,187,243 'go':351,356,383 'go.mod':354 'grep':113 'happen':705 'hardcod':526 'hidden':92,152 'ignor':175,184,194,202,209,424,430,443,465,481,567,571,575,616,648 'immedi':217 'implement':414,604,676 'inconsist':493 'input':764 'instal':324,340,349,461,586 'integr':664 'investig':395 'isol':8,29,51,68,561,681 'issu':517 'jess':211 'limit':726 'line':221 'local':151,166,186,486,619,652 'locat':156,277,282,403,490,632 'ls':86,93 'm':56,549 'match':735 'miss':772 'mistak':463 'mod':357 'multipl':17,38 'must':171 'name':258,284,290,303 'need':249,680 'neither':435 'never':609 'new':295,511 'node.js':318 'npm':323,378,585,588 'order':76,85 'output':744 'outsid':250 'overview':25,725 'package.json':321,457,543 'package.json/cargo.toml':456 'pair':683 'pars':265 'pass':398,408,591,597 'path':275,281,286,300,305 'per':210 'permiss':523,765 'phase':668 'pip':339 'plan':698 'poetri':348 'pollut':472 'pre':515 'pre-exist':514 'prefer':91,121,137,160 'prevent':235 'principl':44 'prioriti':75,84,499,641 'problem':467,491,507,529 'proceed':229,393,503,525,624 'process':72 'project':150,165,251,257,260,288,308,375,485,495,532,541,618,651,658 'project-appropri':374 'project-loc':149,164,484,617,650 'pyproject.toml':346 'pytest':382 'python':334 'q':195,203 'quick':415 'r':341 'readi':400,405,412,593,602 'red':607 'refer':416 'reliabl':50 'report':388,399,402,452,519 'repositori':13,34,241 'requir':670,690,763 'requirements.txt':337,342 'respect':185 'rev':264 'rev-pars':263 'review':756 'rule':213 'run':307,314,364,584,587,657 'rust':326 'safeti':48,161,766 'scope':737 'select':47,71 'set':65,558 'setup':309,316,527,659 'share':10,31 'show':267 'show-toplevel':266 'simultan':19,40 'situat':417 'skill':63,556,679,713,729 'skill-using-git-worktrees' 'skip':459,464,620,635 'source-sickn33' 'specif':751 'specifi':122 'start':54,369 'status':474 'step':254 'stop':757 'subag':701 'subagent-driven-develop':700 'substitut':747 'success':769 'switch':21,42 'system':189 'systemat':45 'task':733 'test':365,379,381,384,386,397,407,409,448,506,589,596,599,622,627,662,753 'thing':216 'tool':535 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'toplevel':268 'track':471 'treat':742 'use':2,22,57,60,101,123,373,421,427,433,477,533,550,553,711,727 'user':129,440 'using-git-worktre':1,59,552 'valid':752 'verif':49,162,248,466,623 'verifi':172,361,423,429,566,613,645,660 'violat':494 'whether':391 'win':108 'without':20,41,125,612,628 'work':15,36,694,704 'workflow':546,719 'workspac':9,30,69,562,682 'worktre':4,6,24,27,62,88,95,107,115,139,146,148,168,170,178,196,204,231,238,271,279,280,293,298,368,404,419,425,434,468,487,555,564,573,577,579,592,611,708 'worktrees/auth':581 'would':158","prices":[{"id":"33a2bc6a-68a9-4f0a-b980-4b32441c5c6c","listingId":"ffc981b6-1867-40ec-8e8b-f9a686d7d145","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:46:55.629Z"}],"sources":[{"listingId":"ffc981b6-1867-40ec-8e8b-f9a686d7d145","source":"github","sourceId":"sickn33/antigravity-awesome-skills/using-git-worktrees","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/using-git-worktrees","isPrimary":false,"firstSeenAt":"2026-04-18T21:46:55.629Z","lastSeenAt":"2026-04-22T00:51:54.513Z"}],"details":{"listingId":"ffc981b6-1867-40ec-8e8b-f9a686d7d145","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"using-git-worktrees","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34404,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-21T16:43:40Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"160146e3ff5dc5209d5555c71c3eeae1a9c340a8","skill_md_path":"skills/using-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/using-git-worktrees"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"using-git-worktrees","description":"Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/using-git-worktrees"},"updatedAt":"2026-04-22T00:51:54.513Z"}}