configure-gitignore

/configure:gitignore

Append a managed Claude Code runtime-state block to a repo's .gitignore so the files Claude Code writes during a session — agent worktrees, the scheduled-task lock, the per-user local settings overlay — never get committed. The block is added non-destructively: every other line in the repo's .gitignore is left untouched.

When to Use This Skill

Use this skill when...	Use another approach when...
Onboarding a repo to Claude Code (also reachable via /configure:repo)	Ignoring a project-specific build artifact — edit .gitignore directly
A repo's .gitignore is missing the Claude Code runtime-state entries	Configuring .gitattributes — use /configure:gitattributes
.claude/worktrees/ or settings.local.json keeps showing as untracked	Configuring Claude Code settings — use /configure:repo

The managed block

# Claude Code runtime state (managed by /configure:gitignore)
.claude/worktrees/
/worktrees/
.claude/scheduled_tasks.lock
.claude/settings.local.json

Entry	Why it's ignored
.claude/worktrees/	Agent worktree checkouts created by Agent(isolation: "worktree") and Wave dispatch
/worktrees/	Repo-root variant some workflows use for the same agent worktrees
.claude/scheduled_tasks.lock	Scheduled-task lock — pure runtime state
.claude/settings.local.json	Per-user local settings overlay — personal, not shared

The block is additive only — it never removes or reorders existing lines, and a project that wants more ignored (e.g. OpenCode export artifacts) keeps those entries alongside this block.

Context

• Existing gitignore: !find . -maxdepth 1 -name .gitignore -type f
• Claude dir present: !find . -maxdepth 2 -type d -name .claude

Parameters

Parameter	Description
--check-only	Report which managed entries are missing without writing any file
--fix	Append the missing entries without prompting

Default (no flag): report the missing entries, append them, and git add the file (staged, not committed).

Execution

Execute this .gitignore configuration workflow:

Step 1: Read existing state

Parse $ARGUMENTS for --check-only / --fix. If a .gitignore exists (from Context), Read it and record which managed entries are already present — counting an entry as covered when its exact line appears or a broader existing pattern already ignores it (e.g. a bare .claude/ covers .claude/worktrees/). Otherwise plan to create .gitignore.

Step 2: Compute the missing entries

From the managed block above, build the set of entries not already covered. If every entry is present, report "already configured" and stop.

Step 3: Write or report

• --check-only: print the missing entries as a diff-style block; write nothing.
• Otherwise: append the managed-block header comment (only if not already present) followed by the missing entries to the end of .gitignore (or create the file with the block). Preserve all existing content verbatim. Then git add .gitignore.

Step 4: Verify

Confirm the block took effect: git check-ignore -v .claude/worktrees/probe should report a match against the new line. (The probe path need not exist — git check-ignore matches patterns, not files.)

Step 5: Report

Print a summary: entries added vs already-present, the file path, and the git diff --cached hint. If --check-only, prefix with "DRY RUN — no files modified".

Important Notes

• Additive only. Never remove, reorder, or rewrite existing .gitignore lines — append the managed block at the end. This makes the skill safe to re-run (idempotent) and safe alongside project-specific ignores.
• Respect broader existing patterns. If the repo already ignores a parent (.claude/), don't add the narrower child — it's redundant.
• .claude/worktrees/ is the load-bearing entry. Agent worktrees are full repo clones; committing one is a large accidental diff. This is the entry the cross-repo rollout exists to guarantee.
• Never auto-commit; stage and let the user review with git diff --cached.

Agentic Optimizations

Context	Command
Propose + append the managed block	/configure:gitignore
Dry-run, no file changes	/configure:gitignore --check-only
Append headless (no prompt)	/configure:gitignore --fix
Confirm an entry took effect	git check-ignore -v .claude/worktrees/probe
Review staged change	git diff --cached

See Also

• /configure:repo — full repo onboarding (offers this skill)
• /configure:gitattributes — the sibling skill for .gitattributes
• .claude/rules/agent-coworker-detection.md (claude-plugins) — why .claude/worktrees/ matters in shared checkouts