omitClaudeMd for subagents

Agents

Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.

Location: agents/ directory in plugin root

File format: Markdown files describing agent capabilities

Agent structure:

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Plugin agent frontmatter

A plugin agent file uses the same frontmatter fields as a subagent file, except that Claude Code honors only some of them when the agent comes from a plugin:

• Supported: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, and experimental. The only valid isolation value is "worktree".
• Not supported, for security reasons: hooks, mcpServers, and permissionMode. Claude Code ignores these when loading an agent from a plugin. To use them, copy the agent file into .claude/agents/ or ~/.claude/agents/.
• Not supported: initialPrompt.

You can put plugin agent files in subfolders of agents/. Claude Code loads them recursively and joins the plugin name, each subfolder name, and the file name with colons to form the agent's scoped name. For example, agents/review/security.md in a plugin named my-plugin loads as my-plugin:review:security. Two settings change that name:

• Frontmatter name: it replaces only the file name, so name: audit in agents/review/security.md loads as my-plugin:review:audit
• Manifest agents field: a file you list there loads without subfolder names, so "agents": "./custom/review/security.md" loads as my-plugin:security

Claude Code loads a plugin agent even when its frontmatter has no name or doesn't parse:

• No name: Claude Code names the agent after the file, so agents/reviewer.md in a plugin named my-plugin loads as my-plugin:reviewer
• Frontmatter that doesn't parse: Claude Code names the agent after the file, uses Agent from my-plugin plugin as its description, and ignores every field in the file

By contrast, Claude Code skips a project, user, or managed agent file whose frontmatter has no name or doesn't parse.

To find files in a plugin's default agents/ directory whose frontmatter doesn't parse, run claude plugin validate. The path you pass depends on whether the plugin has a manifest, and both examples use ./my-plugin as the plugin directory:

• A plugin with a manifest: claude plugin validate ./my-plugin
• A plugin without a manifest: claude plugin validate ./my-plugin/agents. Requires Claude Code v2.1.233 or later.

Agents appear in the @-mention typeahead under their scoped name, such as my-plugin:code-reviewer, once the plugin is enabled.

For complete details, see Subagents.