omitClaudeMd: Claude Code's New Flag Lets Subagents Skip CLAUDE.md Entirely (v2.1.271, 2026)

Claude Code v2.1.271 (September 14, 2026) added a one-line fix for a problem the community had been solving with folder gymnastics for over a year: omitClaudeMd: true in a subagent’s frontmatter now launches that subagent without loading the user, project, or local CLAUDE.md files. It’s aimed at subagents that are meant to be fully self-contained — everything they need comes from the delegation prompt, not from your project’s house rules.

What omitClaudeMd Actually Does

Per the current subagent frontmatter reference, the field is documented like this:

Set to true to launch this subagent without the user, project, and local CLAUDE.md files; managed policy files still load, except for managed subagents. Use it for subagents that take everything they need from the delegation prompt. Ignored when the agent runs as the main session agent via --agent or the agent setting. Requires Claude Code v2.1.271 or later.

Concretely, three files are in scope:

A minimal frontmatter block:

---
name: isolated-researcher
description: Fetches and summarizes external URLs. Has no need for project conventions.
tools: WebFetch, WebSearch
omitClaudeMd: true
---

The same field works in --agents JSON, for subagents defined at the CLI rather than as files:

claude --agents '{
  "isolated-researcher": {
    "description": "Fetches and summarizes external URLs",
    "prompt": "You research external sources and return a summary. You have no access to this repository'\''s conventions.",
    "tools": ["WebFetch", "WebSearch"],
    "omitClaudeMd": true
  }
}'

Requirement: Claude Code v2.1.271 or later. Check your version with claude --version before adding this to a shared subagent definition — older clients will silently ignore an unrecognized frontmatter field rather than error, so a team member on an old build gets full CLAUDE.md loading with no warning that the flag did nothing.

The Governance Exception: Managed Policy Files Still Load — Mostly

The interesting design decision is the carve-out. omitClaudeMd skips the CLAUDE.md files you control (user, project, local) but not the ones an organization administrator pushes via managed settings. That’s deliberate: a subagent opting out of your team’s coding-style rules shouldn’t also opt out of your org’s compliance or security policy.

There’s a second-order exception on top of that, and it’s the one most likely to trip people up: if the subagent itself is a managed subagent — meaning it’s deployed by an org admin through the managed settings .claude/agents/ directory, not a project or user-level file — then omitClaudeMd: true skips the managed policy files too. The reasoning, per the docs, is that an admin who deploys a managed subagent has already made the call about what that subagent should and shouldn’t see; a project-level or user-level subagent doesn’t get to make that same call for org policy on its own.

In practice: if you’re setting omitClaudeMd on a subagent in your own .claude/agents/ or ~/.claude/agents/, expect managed policy CLAUDE.md content to still show up in that subagent’s context no matter what. If you’re an admin authoring subagents that ship via managed settings, omitClaudeMd on those definitions is the stronger opt-out.

The Workaround This Replaces

We covered the pre-omitClaudeMd state of this problem in our earlier piece on per-agent AGENTS.md files: before this flag existed, the only way to stop a specialized subagent from inheriting your entire project’s CLAUDE.md — commit conventions, naming rules, framework-specific instructions that have nothing to do with the subagent’s one job — was to restructure your repo so each subagent ran from its own working directory with its own scoped AGENTS.md, using .agents/review/AGENTS.md, .agents/security/AGENTS.md, and so on.

That workaround still has a use case omitClaudeMd doesn’t cover: giving a subagent different, role-specific instructions. omitClaudeMd is binary — a subagent either gets your CLAUDE.md hierarchy or it gets none of it (short of managed policy). It has no concept of “give the security subagent the security rules but not the style rules.” If that’s what you need, the directory-split approach — or simply writing the relevant rules directly into the subagent’s own system prompt — is still the right tool.

Where omitClaudeMd wins outright is the case that directory-splitting was always a clumsy fit for: a subagent that needs zero project context, full stop. A subagent that fetches and summarizes an external URL, converts a file format, or runs a fixed validation script doesn’t need your commit message conventions or your src/ naming rules — restructuring your repo into a .agents/ tree just to give it an empty AGENTS.md was solving the problem with more infrastructure than the problem required. One frontmatter field now does what used to take a directory layout change.

What Else Loads (and Doesn’t) When You Set It

omitClaudeMd only touches CLAUDE.md files. Everything else Claude Code normally hands a subagent at startup is unaffected:

• Task message — the delegation prompt the parent writes still arrives in full. This is by design: it’s supposed to be the only thing a fully self-contained subagent needs.
• Git status snapshot — still included, unless the working directory isn’t a Git repo or includeGitInstructions is false. omitClaudeMd doesn’t touch this.
• Preloaded skills — any skill named in the subagent’s skills field still loads in full, independent of the CLAUDE.md setting.
• Sibling roster (for multi-agent sessions using SendMessage) — unaffected.

What a subagent with omitClaudeMd: true does not get, same as any non-fork subagent: your conversation history, your active output style, and auto memory from the main session. None of that is new behavior from this release — it’s the baseline for how subagents already worked. omitClaudeMd just adds CLAUDE.md to the list of things a specific subagent can be told to skip.

One consequence worth flagging: because the delegation prompt is now carrying the entire context for that subagent, anything it needs — including “don’t touch the vendor/ directory,” which would normally live in CLAUDE.md and reach every subagent automatically — has to be restated explicitly in the prompt each time you invoke it. Skipping CLAUDE.md doesn’t reduce what the subagent needs to know; it just moves the responsibility for supplying that knowledge from the file system to whoever writes the delegation prompt.

When to Reach for It

• A subagent that only calls out to external services or APIs (URL fetchers, format converters, linters run as a black box): omitClaudeMd: true. Your project’s coding conventions are noise to a task like this.
• A subagent published as a reusable plugin, meant to work identically across every repo it’s installed into: omitClaudeMd: true, so its behavior doesn’t silently shift based on whatever CLAUDE.md happens to exist in the host project.
• A subagent that needs some project context but not all of it (e.g., environment variables and build commands, but not code style): the directory-split AGENTS.md approach, or writing the specific rules into the subagent’s own prompt, still fits better than a blanket skip.
• A subagent enforcing something that must never be violated (security boundaries, forbidden directories): neither omitClaudeMd nor CLAUDE.md inheritance is the right mechanism either way — both are context, not enforcement. Use a PreToolUse hook with permissions.deny for anything that has to hold regardless of what any file says.

If you’re building or publishing subagents that call out to third-party services, the delegation prompt is also where any credentials that subagent needs have to live now, since it’s not inheriting your project’s .env-reading conventions from CLAUDE.md. Hardcoding an API key into that prompt or into the subagent’s frontmatter defeats the isolation omitClaudeMd is trying to give you — anyone who can read the subagent definition can read the key. 1Password’s CLI sidesteps that: op run injects the specific secret into the process environment at the moment the subagent actually calls out, so the credential never has to sit in a prompt, a frontmatter field, or a file that a self-contained, no-CLAUDE.md subagent might otherwise expose.

Related Articles

• Claude Sub-agents with Dedicated AGENTS.md: Per-Agent Instructions Without the Overlap
• Claude Code’s Most-Upvoted Issue Hit 5,146 for AGENTS.md Support. Anthropic Closed It as ‘Completed’ Anyway (2026)
• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• AGENTS.md vs CLAUDE.md: What’s the Difference and When to Use Each

Browse the full collection of AI coding rule files and templates in our gallery.

FAQ

What does omitClaudeMd do in Claude Code?

It’s a subagent frontmatter field (and --agents JSON field), added in Claude Code v2.1.271, that launches a subagent without loading the user, project, or local CLAUDE.md files. It’s intended for subagents that are fully self-contained and get everything they need from the delegation prompt instead of project context.

Do managed policy CLAUDE.md files still load with omitClaudeMd?

Yes, in the normal case — managed policy files (deployed via managed settings) still load even when omitClaudeMd: true is set on a project or user subagent. The one exception: if the subagent itself is a managed subagent (deployed by an org admin through managed settings), managed policy files are skipped too.

Does omitClaudeMd work with the —agents CLI flag?

Yes. omitClaudeMd is a supported field in the --agents JSON configuration, in addition to subagent markdown frontmatter, so CLI-defined session-only subagents can use it the same way as file-based ones.

What Claude Code version is required for omitClaudeMd?

v2.1.271 or later, released September 14, 2026. Older versions will not recognize the field.

Does omitClaudeMd affect the main session agent?

No. The field is explicitly ignored when the agent runs as the main session agent via the --agent flag or the agent setting — CLAUDE.md loads normally in that case regardless of the field.