How do I install the Use Worktrees skill?

Run npx skillmds@latest add maxedapps/use-worktrees in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Use Worktrees safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Use Worktrees?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Use Worktrees free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Use Worktrees?

maxedapps (@maxedapps) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Use Worktrees by maxedapps — Agent Skill

Name: Use Worktrees
Author: maxedapps

Use Worktrees

Manages Git worktrees for isolated feature or milestone work. Use this skill whenever work should happen in a worktree, a worktree needs syncing with its target branch, or a finished worktree branch should be merged or cleaned up. Do not use for ordinary single-checkout branch work or subagent delegation that does not require worktree operations.

maxedapps 0b41920 3.4 KB Updated Sep 17, 2026

File contents

Use git worktrees

Location

All worktrees live in ~/worktrees/<project>/<worktree>, where <project> is the repo's directory name and <worktree> matches the branch name:

git worktree add ~/worktrees/course-platform/milestone-4-auth -b milestone-4-auth <target-branch>

Never create worktrees inside the repository or scattered elsewhere. git worktree list shows what exists.

Setup after creating

Follow the repository's setup instructions and install dependencies in the worktree; generated or ignored dependency directories are not shared between checkouts.
Give deployments from concurrent worktrees a dedicated stage/environment. Never let parallel checkouts mutate the same deployment state.
For delegated work, also follow use-subagents; the parent agent owns all worktree creation, integration, and cleanup.

Working in the worktree

All work for the feature happens on the worktree's branch, committed incrementally. The main checkout stays untouched and free for parallel work.
Sync direction during work is always target branch → worktree branch (git merge <target-branch> inside the worktree) at natural checkpoints, and mandatorily before touching anything that parallel work may have changed. Never rebase or rewrite shared branches.
After every sync, run the repository's full check suite.
Sync conflict rules:
- Sequential migrations: if the target branch took a number this branch also uses, renumber this branch's migration to the next free slot. Check this on every sync even without a textual conflict.
- Lockfile conflicts: preserve both sides' manifest/workspace changes, then regenerate with the repository's package manager. Never hand-edit a generated lockfile.
- Resolve everything else by reading both sides; the combined test suites are the arbiter.

Merging back

Never merge a worktree branch back into master (or any target branch) automatically. Review cycles happen in the worktree first; the merge happens only when the user explicitly asks for it. When they do:

Final sync target → worktree branch; resolve conflicts and get the full check suite green in the worktree.
Merge the worktree branch into the target with --no-ff from the main checkout.
Review git diff <target-before>..<merge-result> to confirm nothing from the target's side was dropped.
Push. No force-push, no bulk --theirs/--ours resolutions, ever.

Cleanup

After a merge is pushed and verified:

git worktree remove ~/worktrees/<project>/<worktree>
git branch -d <branch>

For unmerged cleanup, first inspect uncommitted changes and commits absent from the target. Remove a safe, fully handled workflow-owned worktree with no unique work according to use-subagents. Otherwise report the unique work and require explicit user approval; use forced worktree removal or branch deletion only when that approval specifically accepts the identified data loss.

git worktree prune clears stale registrations if a worktree directory was deleted manually.

---name: use-worktreesdescription: Manages Git worktrees for isolated feature or milestone work. Use this skill whenever work should happen in a worktree, a worktree needs syncing with its target branch, or a finished worktree branch should be merged or cleaned up. Do not use for ordinary single-checkout branch work or subagent delegation that does not require worktree operations.license: MIT---# Use git worktrees## LocationAll worktrees live in `~/worktrees/<project>/<worktree>`, where `<project>` is the repo's directory name and `<worktree>` matches the branch name:```git worktree add ~/worktrees/course-platform/milestone-4-auth -b milestone-4-auth <target-branch>```Never create worktrees inside the repository or scattered elsewhere. `git worktree list` shows what exists.## Setup after creating- Follow the repository's setup instructions and install dependencies in the worktree; generated or ignored dependency directories are not shared between checkouts.- Give deployments from concurrent worktrees a **dedicated stage/environment**. Never let parallel checkouts mutate the same deployment state.- For delegated work, also follow `use-subagents`; the parent agent owns all worktree creation, integration, and cleanup.## Working in the worktree- All work for the feature happens on the worktree's branch, committed incrementally. The main checkout stays untouched and free for parallel work.- Sync direction during work is always **target branch → worktree branch** (`git merge <target-branch>` inside the worktree) at natural checkpoints, and mandatorily before touching anything that parallel work may have changed. Never rebase or rewrite shared branches.- After every sync, run the repository's full check suite.- Sync conflict rules: - **Sequential migrations**: if the target branch took a number this branch also uses, renumber this branch's migration to the next free slot. Check this on every sync even without a textual conflict. - **Lockfile conflicts**: preserve both sides' manifest/workspace changes, then regenerate with the repository's package manager. Never hand-edit a generated lockfile. - Resolve everything else by reading both sides; the combined test suites are the arbiter.## Merging back**Never merge a worktree branch back into master (or any target branch) automatically.** Review cycles happen in the worktree first; the merge happens only when the user explicitly asks for it. When they do:1. Final sync target → worktree branch; resolve conflicts and get the full check suite green **in the worktree**.2. Merge the worktree branch into the target with `--no-ff` from the main checkout.3. Review `git diff <target-before>..<merge-result>` to confirm nothing from the target's side was dropped.4. Push. No force-push, no bulk `--theirs`/`--ours` resolutions, ever.## CleanupAfter a merge is pushed and verified:```git worktree remove ~/worktrees/<project>/<worktree>git branch -d <branch>```For unmerged cleanup, first inspect uncommitted changes and commits absent from the target. Remove a safe, fully handled workflow-owned worktree with no unique work according to `use-subagents`. Otherwise report the unique work and require explicit user approval; use forced worktree removal or branch deletion only when that approval specifically accepts the identified data loss.`git worktree prune` clears stale registrations if a worktree directory was deleted manually.

Frequently asked questions