worktree-helper

majiayu000's avatarfrom majiayu000

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Developer Tools]

When & Why to Use This Skill

The Worktree Helper is a specialized Claude skill designed to optimize Git workflows through efficient worktree management. It automates the creation, cleanup, and migration of Git worktrees, enabling developers to handle multiple tasks simultaneously without the overhead of context-switching or stashing. By integrating with GitHub and GitLab, it facilitates issue-based development and ensures a consistent, organized repository structure for professional software engineering.

Use Cases

  • Parallel Feature Development: Create isolated worktrees to work on urgent bug fixes or secondary features without interrupting or stashing changes in your primary working directory.
  • Repository Structure Migration: Automatically migrate standard Git repositories into a structured 'main/' and 'worktrees/' layout to improve project isolation and organization.
  • Issue-Driven Workflow: Fetch task details directly from GitHub or GitLab using MCP tools to automatically initialize dedicated worktrees named according to specific issue IDs.
  • Environment Maintenance: Perform guided preflight checks and safe cleanup of stale branches and worktrees after merging Pull Requests or Merge Requests to keep the local environment clean.
nameworktree-helper
descriptionGuide 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

  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.
  1. Is the repo layout already main/ + worktrees/?
  • Yes → Work from main/.
  • No → Recommend migration and offer to run scripts/migrate_to_main_layout.sh.

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

  2. Create a worktree using the naming rules in references/workflow.md.

  3. Implement the task in the worktree, then review with the user.

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