Skip to main content
skill CX Codex

flow-next-worktree-kit — Claude Code skill: git worktrees

flow-next-worktree-kit is a Claude Code skill that creates, switches, and removes git worktrees and copies .env files between them. It supports parallel feature work without switching branches.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-worktree-kit does

The skill manages git worktrees via the worktree.sh script. It creates a worktree under .worktrees/<name>, switches to it, lists all worktrees or removes them along with branches.

The create command leaves the current branch unchanged and sets no upstream on the new branch: the first git push needs -u origin <name>. The cleanup command does not force removal: if a worktree is not clean, deletion fails. Environment file copying skips symlinks and does not overwrite existing files.

When parallel agents run in sibling worktrees, claim state in .git/flow-state is shared: concurrent flow pipelines require a separate FLOW_STATE_DIR per agent.

What it helps with

  • create a worktree for a feature without switching the main branch
  • switch to another worktree for code review
  • remove worktrees and branches after merge
  • copy .env to a new worktree
  • list all worktrees in the project

Example prompts for the agent

  • Create a worktree feature-auth from develop branch
  • Switch to worktree hotfix-login
  • Remove worktrees old-feature and test-branch

How to install flow-next-worktree-kit

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-worktree-kit -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-worktree-kit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-worktree-kit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-worktree-kit

How to install flow-next-worktree-kit in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next, then npx skills add gmickel/flow-next --skill flow-next-worktree-kit -a claude-code. The skill will appear at ~/.claude/skills/flow-next-worktree-kit/SKILL.md.

What does flow-next-worktree-kit do?

The skill creates, switches and removes git worktrees, copies .env files between them. This lets you work on multiple features in parallel without switching branches in the main directory.

Where are worktrees created?

All worktrees are placed under .worktrees/ in the repository root. On first creation the skill adds .worktrees/.gitignore with * and !.gitignore so git add -A does not stage them as gitlinks.

Source text

SKILL.md · MIT
---
name: flow-next-worktree-kit
description: Manage git worktrees (create/list/switch/cleanup) and copy .env files. Use for parallel feature work, isolated review, clean workspace, or when user mentions worktrees.
---

# Worktree kit

Use the manager script for all worktree actions.

```bash
WORKTREE_SH="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-worktree-kit/scripts/worktree.sh"
[ -f "$WORKTREE_SH" ] || WORKTREE_SH="<plugin-root>/skills/flow-next-worktree-kit/scripts/worktree.sh"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
bash "$WORKTREE_SH" <command> [args]
```

Commands:
- `create <name> [base]`
- `list`
- `switch <name>` (prints the worktree path; it cannot change your shell's directory - use `cd "$(... switch <name>)"`)
- `cleanup [<name>...] [--yes]` (no args = interactive; names skip the prompt; `--yes` skips the confirmation, required off a terminal)
- `copy-env <name>`

Safety notes:
- `create` does not change the current branch
- `create` sets no upstream on the new branch (`--no-track`) - under the upstream-based push modes (`simple`, `upstream`, `current`) a bare `git push` cannot aim at the base branch; under the default `push.default=simple` (without `push.autoSetupRemote`) the first push needs `git push -u origin <name>` (legacy `push.default=matching` pushes all name-matched branches regardless of upstream)
- `cleanup` does not force-remove worktrees and does not delete branches
- `cleanup` deletes the worktree directory (including ignored files); removal fails if the worktree is not clean
- `.env*` is copied with no overwrite (symlinks skipped)
- refuses to operate if `.worktrees/` or any worktree path component is a symlink
- `copy-env` only targets registered worktrees
- `origin` fetch is optional; local base refs are allowed
- fetch from `origin` only when base looks like a branch
- Worktrees live under `.worktrees/`
- `create` initializes `.worktrees/.gitignore` (`*` plus `!.gitignore`) when
  absent, so `git add -A` cannot stage nested worktrees as gitlinks; existing
  custom ignore files are preserved

**Shared claim state.** Parallel agents in sibling worktrees driving `flowctl` on the same repo share claim state via `.git/flow-state`. Set `FLOW_STATE_DIR` per agent (outside the tree) when running flow pipelines concurrently.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Git and GitHub →

From the same set70

The whole set →
flow The flow command drives a task from idea or bug to ready PR. Works for unattended runs on a ready spec or step-by-step with stops before decisions. CX Codex +1 ★ 730repo stars flow-next-prose flow-next-prose — a skill for Claude and Codex that makes the agent read the prose contract in docs/prose.md before a long reply and draft under rules 1–10. CX Codex +1 ★ 730repo stars flow-next flow-next directs AI models to manage fn-N tasks using flowctl instead of markdown TODO lists. CX Codex +1 ★ 730repo stars flow-next-make-pr flow-next-make-pr is a Claude Code skill that builds a briefing from an aid artifact and opens or updates a PR through gh. It detects the spec from the branch and accepts options for draft state, base branch, and dry runs. CX Codex +1 ★ 730repo stars flow-next-land The flow-next-land skill handles feedback and CI checks for a named pull request, then squash-merges it when authorized and ready. Use it when asked to land a specific PR. CX Codex +1 ★ 730repo stars flow-next-make-pr flow-next-make-pr opens a pull request through gh, with the briefing body rendered by flowctl from the flow-next spec state. Fits repos where PRs are expected to follow a spec. CX Codex +1 ★ 730repo stars uninstall uninstall removes flow-next from your repository. It cleans docs markers and generates safe terminal commands for deleting project files. CX Codex +1 ★ 730repo stars refine refine is a Claude Code command that asks one focused round of questions about a spec, task, or file, or researches related documentation. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open