Prepare or audit Git worktrees for Claude automation, scheduled/background agents, long-running tasks, or isolated branch work. Use when Claude needs to create a worktree, refresh a worktree, make a worktree ready for unattended execution, or replicate local-only context such as AGENTS.md, user.bazelrc, .bazelrc.user, .buckconfig.local, credentials-backed build config, editor/tooling config, or repo-specific ignored files from a primary checkout.
Prepare or audit Git worktrees for Claude automation, scheduled/background agents, long-running tasks, or isolated branch work. Use when Claude needs to create a worktree, refresh a worktree, make a worktree ready for unattended execution, or replicate local-only context such as AGENTS.md, user.bazelrc, .bazelrc.user, .buckconfig.local, credentials-backed build config, editor/tooling config, or repo-specific ignored files from a primary checkout.
Prepare Worktree
Use this skill to make a Git worktree behave like the normal checkout before
starting automation or background agent work. A Git worktree shares Git object
state, but it does not automatically bring along untracked or ignored local files.
Workflow
Identify the primary checkout and target worktree.
Use this command to find existing worktrees:
git -C <repo> worktree list --porcelain
Treat the normal checkout as the source of local-only context unless the
user names a different source.
Keep unrelated dirty changes in the primary checkout untouched.
Create or refresh the worktree.
Prefer this command for new worktrees:
git worktree add <path> <branch-or-ref>
If reusing an existing worktree, inspect git status --short there before
changing it.
Keep automation work on an explicit branch or detached ref that matches the
requested task.
Audit local-only files in the primary checkout before running automation.
Run:
git -C <primary> status --porcelain=v1 --untracked-files=all
Also inspect ignored-but-important files with targeted checks, for example:
Fall back to symlinks when hardlinks fail or when linking directories:
ln -s <source> <dest>
Prefer links over copies so API key or token rotations in one checkout are
visible to other worktrees.
Create missing parent directories first.
Do not print credential file contents.
Give special treatment to build and agent-context files.
Link Bazel local config such as user.bazelrc and .bazelrc.user by default
when present in the primary checkout; these often enable Remote Build
Execution or remote cache credentials.
Link Buck2 local config such as .buckconfig.local by default when present in
the primary checkout; it may contain remote execution, authentication, or
local platform settings.
Link untracked or ignored AGENTS.md files by default when present in the
primary checkout; they provide task-critical context for agents operating
below that directory.
Do not overwrite a tracked file in the target worktree unless the user
explicitly asks. If a tracked AGENTS.md already exists there, leave it and
only add missing local-only context files.
Validate readiness.
Use ls -li to confirm hardlinks share an inode.
Use readlink or readlink -f to confirm symlinks.
Run a narrow repo-appropriate sanity check when practical, such as bazel
info, buck2 root, or git status --short.
Report the linked files and any intentionally skipped local files.
Link Selection
Prefer hardlinks for secret-bearing regular files because they avoid path
fragility and keep changes synchronized by inode. Use symlinks when hardlinks are
impossible across filesystems, when the source is a directory, or when the target
should always point at the primary checkout current path.
Avoid linking generated outputs, caches, logs, editor swap files, or task-specific
scratch files unless the user explicitly requests them.
Automation Notes
Prepare worktrees conservatively for unattended runs:
Verify credentials-backed local config exists before scheduling background work.
Preserve the primary checkout untracked files; replicate only what the target
worktree needs.
Prefer idempotent linking commands that detect existing destinations and compare
them before replacement.
Record assumptions in the final response so future scheduled agents know which
checkout supplied the local context.
Resources
scripts/link_local_context.py: discover special local-only files in a primary
checkout, then dry-run or create hardlinks/symlinks into a target worktree
without printing file contents.
