worktree-helper

提供一套一致的工作流程，指导开发者创建与使用 Git 工作树。当用户希望在独立的工作树中运行任务、创建或清理工作树、将仓库迁移到主分支与工作树并存的布局，或借助 GitHub/GitLab 工具，根据问题 ID 开展相关工作时，可使用此指南。

SKILL.md

--- frontmatter

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.

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