AGENT SKILL

using-git-worktrees

Create or verify an isolated git worktree before starting any development work. Prevents main branch contamination, enables parallel feature development, and gives subagents a clean baseline. Use at the start of every feature branch.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
using-git-worktrees
description
Create or verify an isolated git worktree before starting any development work. Prevents main branch contamination, enables parallel feature development, and gives subagents a clean baseline. Use at the start of every feature branch.

03 SKILL.md 正文

Using Git Worktrees

Why Worktrees

A worktree is a second checkout of the same repo in a separate directory. Each worktree has its own working tree and HEAD, but shares the git object store. This means:

  • Subagents work in isolation — no interference with your main session
  • You can switch tasks without stashing
  • Parallel features develop independently
  • Clean rollback: abandon the worktree, nothing pollutes main

When to Use

Use at the START of every feature or bug fix. Do NOT start implementation until a clean worktree exists or you've confirmed you're already in one.

Mandatory before:

  • subagent-driven-development skill
  • executing-plans skill
  • Any work touching more than one file

The Process

Step 1: Detect Existing Isolation

First check — are you already isolated?

# Check if current directory is a worktree (not the main checkout)
git worktree list
pwd

If you're already in a worktree for this feature: proceed to Step 3 (verify clean baseline). If you're in the main checkout: proceed to Step 2.

Step 2: Create the Worktree

# Create worktree + new branch in one command
git worktree add ../worktrees/<feature-name> -b feat/<feature-name>

# Examples:
git worktree add ../worktrees/stripe-billing -b feat/stripe-billing
git worktree add ../worktrees/fix-auth-bug -b fix/auth-token-expiry

The worktree is created at ../worktrees/<feature-name> (sibling of the project root). If the project uses .claude/worktrees/, use that path instead:

git worktree add .claude/worktrees/<feature-name> -b feat/<feature-name>

Step 3: Verify Clean Baseline

Move into the worktree and confirm it starts clean:

cd ../worktrees/<feature-name>   # or .claude/worktrees/<feature-name>
git status                        # Should show: "nothing to commit"
git log --oneline -3              # Confirm you branched from the right point

If status shows unexpected changes: something is wrong — investigate before proceeding.

Step 4: Run Project Setup

Install dependencies and confirm the baseline builds:

npm install          # or pip install -r requirements.txt / go mod download
npm run build        # Confirm baseline build passes BEFORE any changes
npm test             # Confirm baseline tests pass BEFORE any changes

If baseline build or tests fail: STOP. Fix the issue on main first, then recreate the worktree.

Step 5: Proceed with Work

Now development starts. The worktree is isolated, the baseline is confirmed clean.

Cleanup After Work Completes

After the branch is merged or abandoned:

# From the main checkout (not from inside the worktree)
git worktree remove ../worktrees/<feature-name>
git branch -d feat/<feature-name>   # Only after merge

Common Issues

Issue Fix
"already checked out" error The branch exists in another worktree — use a different branch name
Worktree has unexpected changes Run git status to investigate; never force-remove with uncommitted work
Setup script fails in worktree Check for absolute paths in scripts; worktrees use different working directories
Submodules not initialized Run git submodule update --init --recursive in the new worktree

Worktree vs Branch Checkout

git worktree git checkout -b
Main session disrupted No Yes
Parallel work possible Yes No
Independent node_modules Yes (separate dir) Shared
Subagent isolation Clean Risk of contamination

Always use worktrees for subagent work. The isolation is the point.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k