{"id":"3fbf9a5f-b73b-4ac0-bc8a-6a41fa457c77","shortId":"r5dwVM","kind":"skill","title":"code-git-worktrees","tagline":"Use when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification. Triggers on worktree, git worktree, isolated workspace, or creating a new branch for feature work.","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 AGENTS.md\n\n```bash\ngrep -i \"worktree.*director\" AGENTS.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 AGENTS.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 AGENTS.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 > AGENTS.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 AGENTS.md check\n\n**Always:**\n- Follow directory priority: existing > AGENTS.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- Any skill needing isolated workspace for feature work\n- When user explicitly requests worktree setup\n- Before long-running implementation tasks that could pollute current workspace\n\n**Pairs with:**\n- `stacked-commit` - Use worktrees when managing stacked commits across multiple branches","tags":["code","git","worktrees","atelier","martinffx","agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex"],"capabilities":["skill","source-martinffx","skill-code-git-worktrees","topic-agent-skills","topic-agentic-coding","topic-anthropic","topic-claude-code","topic-claude-skills","topic-code-review","topic-codex","topic-codex-skill","topic-opencode","topic-prompt-engineering","topic-sdd","topic-spec-driven-development"],"categories":["atelier"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/martinffx/atelier/code-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add martinffx/atelier","source_repo":"https://github.com/martinffx/atelier","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 23 github stars · SKILL.md body (5,310 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-05-18T19:05:22.085Z","embedding":null,"createdAt":"2026-05-10T07:03:11.055Z","updatedAt":"2026-05-18T19:05:22.085Z","lastSeenAt":"2026-05-18T19:05:22.085Z","tsv":"'/.config/superpowers/worktrees':174,265,305,307 '/cargo.toml':478 '/dev/null':110,117,139,218,226 '/users/jesse/myproject/.worktrees/auth':615 '0':430,620 '1':97,167,238,275 '2':109,116,129,138,173,217,225,244,289 '3':147,248,326 '4':380 '47':610,618 '5':421 'accident':256 'across':723 'action':438 'add':239,319,464,600 'agents.md':131,137,156,458,521,656,663 'allow':55 'altern':118 'alway':496,658 'ambigu':654 'announc':72 'appropri':240,335,396 'ask':146,148,410,459,474,522,649,664 'assum':508,650 'auth':625 'auto':331,558,674 'auto-detect':330,557,673 'b':321,602 'baselin':383,471,641,683 'basenam':281 'bash':101,132,199,279,292,337,391 'branch':38,59,303,309,316,322,725 'break':550 'broken':235 'bug':532 'build':352 'call':685 'cargo':351,400 'cargo.toml':349 'case':296 'cd':324 'chang':247 'check':98,102,130,200,213,221,457,500,583,590,657 'check-ignor':212,220,499,589 'clean':382,390,681 'code':2 'code-git-worktre':1 'command':397,548 'commit':245,257,467,716,722 'common':482 'confirm':592 'content':259,489 'convent':516 'core':63 'could':708 'creat':16,35,48,165,197,290,312,503,512,596,630 'creation':252,273 'critic':254 'current':14,710 'd':107,114 'depend':480 'detect':276,332,559,675 'determin':293 'differ':554 'director':136 'directori':22,66,90,100,123,152,160,187,193,202,264,461,509,651,660,666 'distinguish':530 'download':378 'ensur':387 'entir':272 'esac':311 'etc':564 'exampl':392,565 'exist':99,126,153,440,446,452,456,520,536,585,662 'explicit':542,697 'f':340,348,356,365,373 'fail':407,469,525,646 'failur':409,431,473,540,621 'featur':8,40,626,693 'feature/auth':603 'fi':345,353,363,370,379 'file':562 'fix':234,495,517,538,556 'flag':628 'follow':93,518,659 'found':120,161 'full':294 'get':490,541 'git':3,18,30,43,46,81,211,219,282,317,493,498,574,588,598 'gitignor':210,243,267,466 'global':175,207,263 'go':371,376,403 'go.mod':374 'grep':133 'hardcod':546 'hidden':112,172 'ignor':195,204,214,222,229,444,450,463,485,501,587,591,595,636,668 'immedi':237 'implement':434,624,705 'inconsist':513 'instal':344,360,369,481,606 'integr':684 'investig':415 'isol':12,17,32,49,71,88,581,690 'issu':537 'jess':231 'line':241 'local':171,186,206,506,639,672 'locat':176,297,302,423,510,652 'long':703 'long-run':702 'ls':106,113 'm':76,569 'manag':720 'mistak':483 'mod':377 'multipl':58,724 'must':191 'name':278,304,310,323 'need':11,269,689 'neither':455 'never':629 'new':37,315,531 'node.js':338 'npm':343,398,605,608 'order':96,105 'outsid':270 'overview':45 'package.json':341,477,563 'package.json/cargo.toml':476 'pair':712 'pars':285 'pass':418,428,611,617 'path':295,301,306,320,325 'per':230 'permiss':543 'pip':359 'poetri':368 'pollut':492,709 'pre':535 'pre-exist':534 'prefer':111,141,157,180 'prevent':255 'principl':64 'prioriti':95,104,519,661 'problem':487,511,527,549 'proceed':249,413,523,545,644 'process':92 'project':170,185,271,277,280,308,328,395,505,515,552,561,638,671,678 'project-appropri':394 'project-loc':169,184,504,637,670 'pyproject.toml':366 'pytest':402 'python':354 'q':215,223 'quick':435 'r':361 'readi':420,425,432,613,622 'red':627 'refer':436 'reliabl':70 'report':408,419,422,472,539 'repositori':54,261 'request':698 'requirements.txt':357,362 'respect':205 'rev':284 'rev-pars':283 'rule':233 'run':327,334,384,604,607,677,704 'rust':346 'safeti':25,68,181 'select':23,67,91 'set':85,578 'setup':329,336,547,679,700 'share':51 'show':287 'show-toplevel':286 'simultan':60 'situat':437 'skill':83,576,688 'skill-code-git-worktrees' 'skip':479,484,640,655 'smart':21 'source-martinffx' 'specifi':142 'stack':715,721 'stacked-commit':714 'start':7,74,389 'status':494 'step':274 'switch':62 'system':209 'systemat':65 'task':706 'test':385,399,401,404,406,417,427,429,468,526,609,616,619,642,647,682 'thing':236 'tool':555 'topic-agent-skills' 'topic-agentic-coding' 'topic-anthropic' 'topic-claude-code' 'topic-claude-skills' 'topic-code-review' 'topic-codex' 'topic-codex-skill' 'topic-opencode' 'topic-prompt-engineering' 'topic-sdd' 'topic-spec-driven-development' 'toplevel':288 'track':491 'trigger':27 'use':5,42,77,80,121,143,393,441,447,453,497,553,570,573,717 'user':149,460,696 'using-git-worktre':79,572 'verif':26,69,182,268,486,643 'verifi':192,381,443,449,586,633,665,680 'violat':514 'whether':411 'win':128 'without':61,145,632,648 'work':9,41,56,694 'workflow':566 'workspac':15,33,50,89,582,691,711 'worktre':4,19,29,31,44,47,82,108,115,127,135,159,166,168,188,190,198,216,224,251,258,291,299,300,313,318,388,424,439,445,454,488,507,575,584,593,597,599,612,631,699,718 'worktrees/auth':601 'would':178","prices":[{"id":"655ca9b5-0324-4d50-983f-c0f16ecd8e07","listingId":"3fbf9a5f-b73b-4ac0-bc8a-6a41fa457c77","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"martinffx","category":"atelier","install_from":"skills.sh"},"createdAt":"2026-05-10T07:03:11.055Z"}],"sources":[{"listingId":"3fbf9a5f-b73b-4ac0-bc8a-6a41fa457c77","source":"github","sourceId":"martinffx/atelier/code-git-worktrees","sourceUrl":"https://github.com/martinffx/atelier/tree/main/skills/code-git-worktrees","isPrimary":false,"firstSeenAt":"2026-05-10T07:03:11.055Z","lastSeenAt":"2026-05-18T19:05:22.085Z"}],"details":{"listingId":"3fbf9a5f-b73b-4ac0-bc8a-6a41fa457c77","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"martinffx","slug":"code-git-worktrees","github":{"repo":"martinffx/atelier","stars":23,"topics":["agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill","opencode","prompt-engineering","sdd","spec-driven-development"],"license":"mit","html_url":"https://github.com/martinffx/atelier","pushed_at":"2026-05-18T06:56:45Z","description":"An atelier for Opencode, Claude Code, and other coding agents: spec-driven workflows, deep thinking, and code quality.","skill_md_sha":"bb090c924603e6e31523659d029a9ac6873b77fc","skill_md_path":"skills/code-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/martinffx/atelier/tree/main/skills/code-git-worktrees"},"layout":"multi","source":"github","category":"atelier","frontmatter":{"name":"code-git-worktrees","description":"Use when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification. Triggers on worktree, git worktree, isolated workspace, or creating a new branch for feature work."},"skills_sh_url":"https://skills.sh/martinffx/atelier/code-git-worktrees"},"updatedAt":"2026-05-18T19:05:22.085Z"}}