How do I install the Troubleshoot Worktree skill?

Run npx skillmds@latest add tomevault-io/troubleshoot-worktree in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Troubleshoot Worktree skill do?

Troubleshoot git worktree, branch, and refname issues Use when this capability is needed. It is listed under Coding & Dev Tools on SkillMD.

Is Troubleshoot Worktree safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Troubleshoot Worktree?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Troubleshoot Worktree free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Troubleshoot Worktree?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Troubleshoot Worktree by tomevault-io

Name: Troubleshoot Worktree
Author: tomevault-io

File contents

Git Worktree Troubleshooting

Diagnose and fix worktree, branch, and reference issues.

Quick Diagnostics

Always run first:

git worktree list
git branch -a
git status
pwd

Worktree Discovery

Never assume paths - always discover:

git worktree list
# Main: line with [main] - first column is path
# Branch: line with [<branch>] - first column is path

Critical: Ambiguous Refname

Warning: warning: refname 'origin/main' is ambiguous

Means TWO things named origin/main:

refs/heads/origin/main - LOCAL branch (bad)
refs/remotes/origin/main - remote tracking (good)

Diagnose: git show-ref origin/main

Fix: git branch -D origin/main then verify only 1 line remains with git show-ref origin/main.

Common Errors

Main Worktree Not Found

git worktree add ~/git/<repo>/main main

Branch Worktree Not Found

git fetch origin --force <branch>
git worktree add ~/git/<repo>/<branch> <branch>

Branch Not Found

git fetch origin --force
git branch -a | grep -i "<branch>"

Uncommitted Changes

git add . && git commit -m "WIP"          # Commit
git stash push -m "before operation"      # Stash (temporary)
git checkout -- .                         # Discard (DESTRUCTIVE)

Embedded Git Repository

git rm --cached <folder>
echo "<folder>/" >> .gitignore

Recovery: Reset to Clean State

MAIN_PATH=$(git worktree list | grep '\[main\]' | awk '{print $1}')
BRANCH_PATH=$(git worktree list | grep '\[<branch>\]' | awk '{print $1}')

cd "$BRANCH_PATH" && git fetch origin --force && git reset --hard origin/<branch>
cd "$MAIN_PATH" && git fetch origin --force && git reset --hard origin/main

Recovery: Fresh Worktree

git worktree remove "<path>" --force
git fetch origin --force
git worktree add "<new-path>" "<branch>"

Related Skills

troubleshoot-rebase (git-workflows) — Diagnose and recover from git rebase failures
troubleshoot-precommit (git-workflows) — Troubleshoot pre-commit hook failures
refresh-repo (git-workflows) — Full repo sync including worktree cleanup

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: troubleshoot-worktreedescription: Troubleshoot git worktree, branch, and refname issues Use when this capability is needed.---# Git Worktree TroubleshootingDiagnose and fix worktree, branch, and reference issues.## Quick DiagnosticsAlways run first:```bashgit worktree listgit branch -agit statuspwd```## Worktree Discovery**Never assume paths** - always discover:```bashgit worktree list# Main: line with [main] - first column is path# Branch: line with [<branch>] - first column is path```## Critical: Ambiguous Refname**Warning**: `warning: refname 'origin/main' is ambiguous`Means TWO things named `origin/main`:- `refs/heads/origin/main` - LOCAL branch (bad)- `refs/remotes/origin/main` - remote tracking (good)**Diagnose**: `git show-ref origin/main`**Fix**: `git branch -D origin/main` then verify only 1 line remains with `git show-ref origin/main`.## Common Errors### Main Worktree Not Found```bashgit worktree add ~/git/<repo>/main main```### Branch Worktree Not Found```bashgit fetch origin --force <branch>git worktree add ~/git/<repo>/<branch> <branch>```### Branch Not Found```bashgit fetch origin --forcegit branch -a | grep -i "<branch>"```### Uncommitted Changes```bashgit add . && git commit -m "WIP" # Commitgit stash push -m "before operation" # Stash (temporary)git checkout -- . # Discard (DESTRUCTIVE)```### Embedded Git Repository```bashgit rm --cached <folder>echo "<folder>/" >> .gitignore```## Recovery: Reset to Clean State```bashMAIN_PATH=$(git worktree list | grep '\[main\]' | awk '{print $1}')BRANCH_PATH=$(git worktree list | grep '\[<branch>\]' | awk '{print $1}')cd "$BRANCH_PATH" && git fetch origin --force && git reset --hard origin/<branch>cd "$MAIN_PATH" && git fetch origin --force && git reset --hard origin/main```## Recovery: Fresh Worktree```bashgit worktree remove "<path>" --forcegit fetch origin --forcegit worktree add "<new-path>" "<branch>"```## Related Skills- **troubleshoot-rebase** (git-workflows) — Diagnose and recover from git rebase failures- **troubleshoot-precommit** (git-workflows) — Troubleshoot pre-commit hook failures- **refresh-repo** (git-workflows) — Full repo sync including worktree cleanup---> Converted and distributed by [TomeVault](https://tomevault.io/claim/jacobpevans) — claim your Tome and manage your conversions.

Frequently asked questions

Troubleshoot Worktree