Claude Code — Agents
- File format
- Markdown
- Discovery path
-
.claude/agents - Global install path
-
~/.claude/agents - Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
- Native frontmatter fields
-
name,description,tools,disallowedTools,model,maxTurns,permissionMode,skills,mcpServers,memory,background,isolation,effort,hooks,color,temperature,timeout_mins,kind
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
background | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Agents run foreground (blocking, interactive prompts pass through) or background (concurrent, pre-approved tools only; AskUserQuestion fails but agent continues); set background: true or press Ctrl+B. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 disables all background tasks. |
mcpServers | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Gives an agent inline or referenced MCP servers; inline definitions keep tool descriptions out of the parent context; ignored for plugin subagents. |
memory | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Gives an agent a persistent directory (user: ~/.claude/agent-memory/<name>/, project: .claude/agent-memory/<name>/, local: .claude/agent-memory-local/<name>/) seeded with MEMORY.md and Read/Write/Edit tools auto-enabled. First 200 lines or 25KB of MEMORY.md injected at startup. |
permissionMode | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | permissionMode field controls permission handling: default (standard prompts), acceptEdits (auto-accept file edits in working dir or additionalDirectories), auto (background classifier), dontAsk (auto-deny non-allowed tools), bypassPermissions (skip all prompts except root/home removals), plan (read-only). Parent bypassPermissions or acceptEdits overrides subagent mode. Ignored for plugin subagents. |
skills | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | The skills frontmatter field injects full skill content into the subagent's context at startup (not just made available for invocation). Subagents do not inherit skills from parent conversation. Skills with disable-model-invocation: true cannot be preloaded; missing or disabled skills are skipped with a warning. |
tools | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | tools allowlist, disallowedTools denylist. Agent(type) in tools allowlist restricts which subagent types can be spawned; Agent without parentheses allows any; omit Agent entirely to block spawning. Use permissions.deny with Agent(subagent-name) to prevent Claude from using specific subagents. disallowedTools applied before tools if both present. |
CLAUDE_CODE_FORK_SUBAGENT | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | Experimental fork mode (CLAUDE_CODE_FORK_SUBAGENT=1, CC v2.1.117+): forks inherit the full conversation context instead of starting fresh; every subagent spawn runs in background in fork mode; /fork command spawns a fork instead of aliasing /branch; named subagents like Explore still spawn as before. |
color | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | The color frontmatter field sets a display color for the subagent in the task list and transcript. Accepts: red, blue, green, yellow, purple, orange, pink, or cyan. |
initialPrompt | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | initialPrompt is auto-submitted as the first user turn when the agent runs as the main session agent (via --agent or agent setting). Commands and skills are processed. Prepended to any user-provided prompt. |
isolation | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | Runs the agent in a temporary git worktree when set to worktree, auto-cleaned if no changes are made. |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
agent_scopes | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | 5 scopes (highest-first): managed settings (org-wide, priority 1), CLI --agents flag (current session, priority 2), project (.claude/agents/, priority 3), user (~/.claude/agents/, priority 4), plugin agents/ directory (priority 5); highest-priority wins on name collision |
definition_format | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Markdown files with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (user); file body becomes system prompt; only name and description are required |
| Five Agent Scopes and Priority Ordering | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Five agent scopes (highest first): managed settings (priority 1), CLI --agents flag (priority 2, session-only inline JSON), project (priority 3), user (priority 4), plugin (priority 5). The --agents flag accepts same frontmatter fields as file-based agents using 'prompt' for the system prompt body. |
invocation_patterns | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | natural language (Claude auto-delegates), @agent-<name> @-mention from typeahead, or --agent flag at startup for session-wide agent; plugin subagents appear as <plugin>:<name> in typeahead |
| Markdown + YAML Frontmatter Agent Files | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Agents are .md files with YAML frontmatter; body is the system prompt, name and description are the only required fields. Subagents receive only their own system prompt plus basic environment details at startup, not the parent session's context. |
model_selection | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | model frontmatter field accepts sonnet/opus/haiku alias, full model ID (e.g. claude-opus-4-7), or inherit (default); resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var > per-invocation model param > frontmatter model > main conversation model |
per_agent_mcp | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | mcpServers frontmatter field: list of server names referencing already-configured workspace servers or inline server definitions; ignored for plugin subagents |
subagent_spawning | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | main-thread agents spawn subagents via Agent tool; subagents cannot spawn further subagents; Agent(type) in tools allowlist restricts which subagent types are allowed; Agent without parentheses allows spawning any subagent; omitting Agent from tools list blocks all spawning |
tool_restrictions | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | tools allowlist and disallowedTools denylist in frontmatter; if both set, disallowedTools applied first then tools resolved against remaining pool; Agent(type) syntax in tools allowlist restricts which subagent types a main-thread agent can spawn |
| Full Frontmatter Field Set | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | Frontmatter supports tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt. Plugin subagents ignore hooks, mcpServers, and permissionMode for security reasons. |
| Three Invocation Patterns | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | Three invocation patterns: natural language auto-delegation, @agent-<name> mention (or @agent-<plugin>:<name> for plugin agents), or --agent flag for session-wide agent (replaces default system prompt; agent name setting persists on session resume). |
| CLI-Defined Session Agents via --agents Flag | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | --agents flag accepts inline JSON agent definitions for the session only (not persisted). Accepts same frontmatter fields as file-based agents; uses 'prompt' key for the system prompt body. |
| Subagent Auto-Compaction | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Subagents support automatic compaction using the same logic as the main conversation (triggers at approximately 95% capacity by default; configurable via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE). Compaction events logged in subagent transcript files. |
| Subagent Resumption | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | SendMessage tool resumes existing subagents (gated on CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1); transcripts persist independently of main conversation compaction at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl; auto-resumes in background on SendMessage without requiring new Agent invocation. |
Sources
| Source |
|---|
| https://code.claude.com/docs/en/sub-agents.md |