Claude Code v2.1.271 Lets Focused Subagents Skip CLAUDE.md With omitClaudeMd

At a glance

Claude Corner tip

• Keep focused subagents from reloading the full user, project, and local CLAUDE.md stack into every worker turn.
• Set `omitClaudeMd: true` on agent frontmatter or `–agents` JSON so those workers skip instruction files while managed policy still loads.
• Pin Claude Code to `v2.1.271` or newer (prefer your current fleet pin at `v2.1.278+`) before relying on the flag.

You spawn a custom or plugin subagent for a narrow job, and it still swallows the whole CLAUDE.md pile. That burns context and can fight the parent’s scoped instructions. From v2.1.271, agent frontmatter and `–agents` JSON accept `omitClaudeMd` so those subagents skip user, project, and local CLAUDE.md while managed policy files still load.

Why it matters

Parent sessions need the full project playbook. Narrow workers usually do not. Reloading CLAUDE.md on every teammate duplicates instructions and can make a worker treat repo conventions as orders that conflict with the parent’s scoped task. `omitClaudeMd` keeps managed policy while dropping the local instruction stack for that agent only. Pair it with Claude Corner: Blind Agent Edits → Plan Mode Before Disk Changes when the risk is premature edits; use omit when the risk is context bloat on workers. The one move: set `omitClaudeMd: true` on focused agents, pin past v2.1.271, and verify the worker does not quote CLAUDE.md rules it should not have seen.

How to omit CLAUDE.md on focused subagents

Works in Claude Code CLI and Desktop (or VS Code agent configs with the same frontmatter / `–agents` JSON). Prefer `v2.1.278` if your fleet already pinned it this weekend, so you also keep server-side auto-mode classifier defaults.

1. Confirm the pin: `claude –version` should report at least `v2.1.271` (prefer `v2.1.278+`). 2. Open the custom or plugin agent markdown (or the JSON you pass to `–agents`). 3. Add `omitClaudeMd: true` in the frontmatter (or the matching JSON field) for workers that should not inherit user, project, or local CLAUDE.md. 4. Leave default agents unchanged when they still need the full project playbook. 5. Start a fresh session, invoke the focused agent on a throwaway task, and confirm it does not cite CLAUDE.md-only rules you planted for the test.

#!/usr/bin/env bash
set -euo pipefail

# Feature landed in v2.1.271; prefer current weekend pin when already on it.
npm install -g "@anthropic-ai/claude-code@2.1.278"
claude --version  # expect 2.1.278 (minimum for this tip: 2.1.271)

mkdir -p .claude/agents
cat > .claude/agents/narrow-worker.md <<'MD'
---
name: narrow-worker
description: Short research worker that should not reload project CLAUDE.md
omitClaudeMd: true
---


... click "Show full code" below to expand

#!/usr/bin/env bash
set -euo pipefail

# Feature landed in v2.1.271; prefer current weekend pin when already on it.
npm install -g "@anthropic-ai/claude-code@2.1.278"
claude --version  # expect 2.1.278 (minimum for this tip: 2.1.271)

mkdir -p .claude/agents
cat > .claude/agents/narrow-worker.md <<'MD'
---
name: narrow-worker
description: Short research worker that should not reload project CLAUDE.md
omitClaudeMd: true
---

You are a narrow worker. Answer only the parent task. Do not invent project conventions.
MD

# Optional: pass equivalent omitClaudeMd via --agents JSON for one-off runs.

claude -p "Using the narrow-worker agent if available, list which instruction files you loaded (CLAUDE.md vs none). Do not read files unless needed."

Gotchas

• Managed policy files still load when `omitClaudeMd` is true. This is not a bypass of org policy.
• Parent sessions and agents without the flag still read CLAUDE.md as usual. Only mark workers that should stay narrow.
• If a worker must follow project conventions, leave `omitClaudeMd` off (or omit the field) and shrink CLAUDE.md instead.
• Pin past v2.1.271 before documenting the flag for the team; older builds will ignore it.
• This how-to is for Claude Code / Desktop agent configs. It is not an API Messages request shape.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever you use.

You are helping me configure Claude Code subagents so focused workers stop reloading the full CLAUDE.md stack. From Claude Code v2.1.271, agent frontmatter and –agents JSON support omitClaudeMd: true (skip user/project/local CLAUDE.md; managed policy still loads). Ask which agents we run, which need full conventions versus a narrow task, and which version we pin (min v2.1.271, prefer fleet pin). Then produce (1) agents that should set omitClaudeMd, (2) a sample frontmatter block, (3) a verification prompt that the worker did not load CLAUDE.md, and (4) gotchas that managed policy still applies. Keep it concrete and copy-paste ready.