agentleFS
Sign inStart free
DROOdotFOODROOdotFOO/agent-skills/skills/git-worktree-manager/SKILL.md

git-worktree-manager

Skill1 starsChanged 2 months agoMITView on GitHub

Parallel development with git worktrees and deterministic port isolation. TRIGGER when: user wants to work on multiple branches simultaneously, run parallel agent sessions, manage worktree-based dev environments, or asks about port conflicts between concurrent services. DO NOT TRIGGER when: simple branch switching (use git checkout), or single-branch development with no parallelism needed.

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never create worktrees inside the main working tree

    line 51
  2. Very specific:

    Use sibling directories: ../project-feature, not ./worktrees/feature

    line 52
  3. Distinctive:

    Always allocate ports before starting services

    line 53
  4. Distinctive:

    Commit or stash before removing a worktree

    line 55

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

git-worktree-manager

Parallel development using git worktrees with deterministic port allocation. Designed for multi-agent workflows where multiple branches run services concurrently without port collisions.

What You Get

  • Worktree lifecycle management (create, list, cleanup)
  • Deterministic port allocation with collision detection
  • Docker Compose patterns for per-worktree services
  • Decision matrix for when worktrees add value

Workflow

  1. Decide -- Check the decision matrix below. Worktrees add overhead; use them only when parallelism is required.
  2. Create -- git worktree add ../project-feature feature-branch
  3. Allocate ports -- Use deterministic formula from port-allocation.md
  4. Run sessions -- Each worktree gets isolated services on unique ports
  5. Cleanup -- git worktree remove ../project-feature and release ports

Decision matrix

SituationUse worktree?Why
Quick fix while feature branch is runningYesKeep feature services up, fix on main
Multiple agents working different featuresYesEach agent gets isolated environment
Long-running test suite on one branchYesContinue development without waiting
Simple feature branch, no running servicesNogit checkout is simpler
Reviewing a PR locallyMaybeOnly if your current branch has state
Shared database migrations in flightNoWorktrees share .git; migrations collide

Rules

  1. Never create worktrees inside the main working tree
  2. Use sibling directories: ../project-feature, not ./worktrees/feature
  3. Always allocate ports before starting services
  4. Clean up worktrees when the branch is merged
  5. Commit or stash before removing a worktree

Reading guide

Working onRead
Port formula, collision checks, Docker Composeport-allocation

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free