git-worktree skill

A harness-agnostic skill that teaches coding agents to isolate development in Git worktrees and carry each isolated task through verified integration and safe cleanup.

Why

A worktree is useful only when it becomes an actual execution boundary. Agents, background workers, subprocesses, and resumed sessions can all inherit or retain the wrong directory. Merely creating a worktree—or mentioning its path in a prompt—does not keep feature work out of the main checkout.

This skill teaches the principles needed to make worktree development reliable:

1. The assigned worktree is authoritative. Every task-related operation is explicitly routed to its canonical path, regardless of where the coordinator is running.
2. One task stays in one checkout. Feature edits, tests, builds, commits, review fixes, and conflict resolution remain inside the worktree.
3. Parallelism respects mutable state. Read-only work can fan out; each independent writing lane gets its own branch and worktree, with one coordinating writer by default.
4. Lifecycle ownership is explicit. Existing and externally managed worktrees are never removed merely because a worker used them.
5. Completion means integration. A task is not done at implementation, push, or review creation. Unless the user requests handoff only, the work is reconciled, merged according to repository policy, verified in its integrated form, and cleaned up.
6. Recovery favors preservation. Locks, dirty state, interrupted operations, and stale registrations are investigated instead of forced away.

The skill focuses on concepts and strategies rather than any particular coding agent, orchestrator, shell, or hosting platform.

What's in it

skills/git-worktree/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── references/
    ├── coordination.md
    ├── integration.md
    └── recovery.md

The main skill defines the lifecycle and invariants. References provide deeper guidance for multi-worker coordination, repository-policy-aware integration, and preservation-first recovery.

Install

npx skills add HamStudy/git-worktree-skill

Or copy skills/git-worktree/ into a skill directory supported by your agentic tooling.

Companion skills

This skill owns isolation, execution scope, integration state, and cleanup. It is designed to compose with:

• HamStudy/git-commit-skill for ownership-aware staging, atomic commits, and commit messages.
• HamStudy/unit-testing-skill for behavior-focused test design and test-quality review.

Repository-specific instructions remain authoritative for verification, review, and merge strategy.