| name | worktree-helper |
| description | Guide for creating and working in Git worktrees with a consistent workflow. Use when a user wants to run a task in a separate worktree, create or clean up worktrees, migrate a repo into a main/worktrees layout, or implement work based on an issue ID using GitHub/GitLab tooling. |
Worktree Helper
Overview
Use this skill to set up a clean worktree workflow, create new worktrees, and guide issue-based or task-based work. Keep the user in control for any destructive or structural change.
Workflow Decision Tree
- Is the request issue-based?
- Yes → Use
references/hosting.md to fetch issue details (MCP → gh → glab → manual).
- No → Continue with the task description.
- Is the repo layout already
main/ + worktrees/?
- Yes → Work from
main/.
- No → Recommend migration and offer to run
scripts/migrate_to_main_layout.sh.
-
Run preflight checks (clean tree, base branch, existing worktrees) using references/workflow.md.
-
Create a worktree using the naming rules in references/workflow.md.
-
Implement the task in the worktree, then review with the user.
-
Finish: merge or open a PR/MR, then clean up worktrees and branches.
Required Checks
- Confirm the user wants to migrate before running any migration command.
- Confirm before deleting branches or removing worktrees.
- If tooling is missing for issue intake, ask the user to paste issue details.
Core References
references/workflow.md — step-by-step commands, naming, create/remove worktrees.references/hosting.md — MCP/CLI/manual issue intake and tooling detection.references/troubleshooting.md — common worktree errors and fixes.
Bundled Scripts
scripts/migrate_to_main_layout.sh — migrate a repo root into a main/ + worktrees/ layout. Use only with explicit user confirmation.
