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
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-nextWhat 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
.envto a new worktree - list all worktrees in the project
Example prompts for the agent
- Create a worktree
feature-authfromdevelopbranch - Switch to worktree
hotfix-login - Remove worktrees
old-featureandtest-branch
How to install flow-next-worktree-kit
1Plugin marketplace
/plugin marketplace add gmickel/flow-next/plugin install flow-next@flow-nextThis 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-code3Manually: put the files in place
~/.claude/skills/flow-next-worktree-kit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/flow-next-worktree-kit/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-worktree-kit -a codex2Manually: put the files in place
.agents/skills/flow-next-worktree-kit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-worktree-kit -a cursor2Manually: put the files in place
.cursor/skills/flow-next-worktree-kit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gmickel/flow-next plugins/flow-next/skills/flow-next-worktree-kit2Manually: put the files in place
.github/skills/flow-next-worktree-kit/SKILL.md1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-worktree-kit -a gemini-cli2Platform CLI
gemini skills install https://github.com/gmickel/flow-next --path plugins/flow-next/skills/flow-next-worktree-kitManually: put the files in place
.devin/skills/flow-next-worktree-kit/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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