| name | configure-worktreeinclude |
| description | Generate a .worktreeinclude so Claude Code copies gitignored env/secret/config files into new worktrees. Use when worktrees miss .env or local config. |
| args | [--check-only] [--fix] |
| argument-hint | [--check-only] [--fix] |
| allowed-tools | Glob, Grep, Read, Write, Edit, Bash(git add *), Bash(git status *), Bash(git check-ignore *), Bash(git ls-files *), Bash(find *), AskUserQuestion, TodoWrite |
| created | "2026-06-25T00:00:00.000Z" |
| modified | "2026-06-25T00:00:00.000Z" |
| compatibility | claude-code |
| reviewed | "2026-06-25T00:00:00.000Z" |
/configure:worktreeinclude
Generate a .worktreeinclude file whose patterns tell Claude Code which
gitignored files to copy from the main checkout into a newly-created git
worktree. A worktree is a fresh checkout containing only git-tracked files, so
gitignored runtime inputs — .env, local secrets, local config — do not come
along by default; this skill builds the include list from the gitignored files
actually present in this repo, so the patterns match the project instead of
a generic template.
When to Use This Skill
| Use this skill when... | Use another approach when... |
|---|
Worktrees / subagent worktrees start without .env or local config | Ignoring a build artifact — use /configure:gitignore |
Onboarding a repo to Claude Code (also reachable via /configure:repo) | Copying large regenerable dirs (node_modules/) — let the worktree's setup hook reinstall them |
| You want gitignored inputs reproduced per-worktree without committing them | A non-git VCS — a custom WorktreeCreate hook must copy files itself; .worktreeinclude is git-only |
What .worktreeinclude is
.worktreeinclude lives at the repo root, alongside .gitignore, and uses
.gitignore glob syntax. When Claude Code creates a worktree (the
--worktree flag, subagent worktree isolation, or parallel desktop sessions),
every file that matches a pattern and is gitignored is copied into the new
worktree. The match is constrained two ways by design:
- Only gitignored files are copied. A pattern that matches a tracked file is
a no-op — tracked files are already in the worktree, never duplicated.
- You choose the inputs, not the bulk. The right entries are small
per-environment inputs (env files, local secrets, local config). Large
regenerable trees (
node_modules/, .venv/, build output) are better
rebuilt by the worktree's setup than copied — copying is slow and can carry
platform-specific binaries or absolute paths.
Commit .worktreeinclude so the whole team (and every agent worktree) shares
the same include list.
Context
