holocron/plugins/kyberforge/skills/write-agent/references/claude-code-agents.md

topic, source_keys

topic	source_keys
claude-code-agents	claude-code-docs-subagents claude-code-docs-plugins

Overview

Claude Code agents (called subagents) are Markdown files with YAML frontmatter stored in one of several scoped locations. Each runs in its own context window with a custom system prompt, specific tool access, and independent permissions. The parent conversation delegates to a subagent when its description matches the task.

File format

---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. Review for:
1. Correctness: logic errors, edge cases
2. Security: injection, auth bypass
3. Maintainability: naming, complexity

The body becomes the subagent's system prompt. Subagents receive only this system prompt plus basic environment details (working directory) — not the full Claude Code system prompt and not the parent conversation history.

Supported frontmatter fields

Only name and description are required. All others are optional.

Field	Description
name	Unique identifier: lowercase letters and hyphens. Used as agent_type in hooks. Filename does not have to match.
description	When Claude should delegate to this subagent — determines automatic routing. Write imperatively.
tools	Allowlist of tools the subagent can use. Inherits all tools if omitted. Comma-separated or array. Use Agent(type1, type2) syntax to restrict which subagents this agent can spawn.
disallowedTools	Denylist — removed from inherited or specified list. If both tools and disallowedTools are set, denylist is applied first. Supports mcp__<server> patterns.
model	Model alias (sonnet, opus, haiku, fable) or full ID (claude-opus-4-8). Defaults to inherit (parent model).
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan. Inherited from parent; parent's mode takes precedence if stricter. Ignored for plugin agents.
maxTurns	Maximum agentic turns before the subagent stops.
skills	Skills to preload into the subagent's context at startup (full skill content injected, not just description).
mcpServers	MCP servers scoped to this subagent. Inline definitions connect on start, disconnect on finish. String references reuse the parent session's connection. Ignored for plugin agents.
hooks	Lifecycle hooks scoped to this subagent. Ignored for plugin agents.
memory	Persistent memory scope: user, project, or local. Enables cross-session learning.
background	true to always run as a background task. Default: false.
effort	Reasoning effort: low, medium, high, xhigh, max. Overrides session effort level.
isolation	worktree — runs in a temporary git worktree (isolated repo copy). Auto-cleaned up if no changes.
color	Display color in the task list: red, blue, green, yellow, purple, orange, pink, cyan.
initialPrompt	Auto-submitted as the first user turn when this agent runs as the main session agent (via --agent).

Storage locations and scope priority

Location	Scope	Priority
Managed settings .claude/agents/	Organization-wide	1 (highest)
--agents CLI flag	Current session only	2
.claude/agents/	Current project	3
~/.claude/agents/	All projects (user-level)	4
Plugin agents/ directory	Where plugin is enabled	5 (lowest)

When the same name is defined in multiple locations, the highest-priority location wins. Claude Code scans both .claude/agents/ and ~/.claude/agents/ recursively — files can be organized into subfolders. Identity comes from the name frontmatter, not the filename.

Plugin agent constraints

Plugin agents (in a plugin's agents/ directory) have three fields ignored for security reasons:

• hooks — ignored
• mcpServers — ignored
• permissionMode — ignored

If any of these are needed, copy the agent file to .claude/agents/ or ~/.claude/agents/ instead.

Plugin agents in subfolders get a scoped identifier: plugin-name:subfolder:agent-name (e.g., a file at agents/review/security.md in plugin my-plugin registers as my-plugin:review:security).

Repo-specific placement (this repo)

Per ADR-0010, two categories of agent definitions exist in this repo:

• Subagent definitions (isolated context, separate context window): live in core/agents/ — deployed to ~/.claude/agents/ by install.sh. These are the "true" subagents.
• Plugin agents: live in plugins/<name>/agents/<name>.md. Installed with the plugin.
• Role skills (inline mode switches, NOT agents): live in .agents/skills/ with category: roles.

Never put role skills in core/agents/. Never put subagent definitions in .agents/skills/. The distinction is the isolation boundary — subagents get a fresh context window; role skills load inline.

Model routing guidance (from factory §9)

• haiku — formatting, classification, fast lookups
• sonnet — most coding, review, analysis
• opus — adversarial reasoning, complex multi-step, security-critical
• Omit model to inherit from the parent session