# Worktree Helper

> 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.

- Skill: `majiayu000/worktree-helper-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/worktree-helper-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/worktree-helper-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/worktree-helper-2

---


# 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

1) **Is the request issue-based?**
- Yes → Use `references/hosting.md` to fetch issue details (MCP → gh → glab → manual).
- No → Continue with the task description.

2) **Is the repo layout already `main/` + `worktrees/`?**
- Yes → Work from `main/`.
- No → Recommend migration and offer to run `scripts/migrate_to_main_layout.sh`.

3) **Run preflight checks** (clean tree, base branch, existing worktrees) using `references/workflow.md`.

4) **Create a worktree** using the naming rules in `references/workflow.md`.

5) **Implement the task** in the worktree, then review with the user.

6) **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.