Gemini CLI — Agents
- File format
- Markdown
- Discovery path
-
.gemini/agents - Global install path
-
~/.gemini/agents - Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
- Native frontmatter fields
-
name,description,tools,model,max_turns,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 |
|---|---|---|---|
tools | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Tool allowlists support wildcards: '*' (all tools), 'mcp_*' (all MCP tools), 'mcp_<server>_*' (per-server). Wildcards apply to the subagent's effective tool set at invocation time. |
agents.overrides | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | settings.json agents.overrides map applies per-agent configuration overrides by agent name, supporting enabled (boolean to disable an agent), modelConfig (arbitrary model params), and runConfig (maxTimeMinutes, maxTurns) without editing individual agent files. |
kind | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | Optional 'kind' frontmatter field (string) accepts 'local' (default) or 'remote'; remote subagents are documented separately and support a list format that allows multiple remote subagents per file. |
max_turns | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | max_turns frontmatter field (number, default 30) caps the number of conversation turns a subagent may take before it must return to the main agent. |
temperature | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | temperature frontmatter field (number 0.0-2.0, default 1) sets the model sampling temperature for the subagent independently of the parent session. |
timeout_mins | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | timeout_mins frontmatter field (number, default 10) caps the wall-clock execution time of a subagent invocation. |
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 → | Two scopes: project (.gemini/agents/*.md) and user/global (~/.gemini/agents/*.md). Both directories are scanned at session start and merged into a single registry; explicit collision-precedence behavior is not documented upstream. |
definition_format | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Markdown files with YAML frontmatter (delimited by ---) in .gemini/agents/*.md (project) or ~/.gemini/agents/*.md (user/global); the file body becomes the subagent's system prompt. |
invocation_patterns | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Two patterns: (1) automatic delegation by the main agent based on task relevance and the subagent's description, (2) explicit @-mention at the start of a prompt (e.g., '@codebase_investigator review this'); /agents list/enable/disable/configure manages the registry. |
model_selection | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | model frontmatter field (string); accepts a specific model id (e.g., 'gemini-3-preview') or 'inherit' (default) which uses the parent session's model. Optional 'temperature' field (0.0-2.0, default 1) sets per-subagent sampling temperature. |
per_agent_mcp | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | mcpServers object in frontmatter; declares inline MCP server configurations scoped to this subagent. Each entry follows the same shape as the global mcpServers config and is isolated to the subagent's invocation. |
tool_restrictions | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | tools array in frontmatter; supports wildcards: '*' for all built-in and MCP tools, 'mcp_*' for all MCP tools, 'mcp_<server-name>_*' for tools from a single MCP server. If omitted, the subagent inherits the full tool set from the parent session. |
| /agents management command | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | /agents list, enable, disable, configure, and reload manages the subagent registry; /agents reload rescans both ~/.gemini/agents and .gemini/agents without restarting the CLI. |
| Built-in expert subagents | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Gemini CLI ships built-in subagents alongside user-authored ones: @codebase_investigator (codebase analysis), @cli_help (CLI docs), @generalist (multi-file operations), @browser_agent (experimental web automation). |
| Remote subagents | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Remote subagents (kind: remote) are also Markdown files with YAML frontmatter at the same locations; a list format permits multiple remote subagents in a single file (mixed local+remote or multiple local agents in one file is not supported). |
Sources
| Source |
|---|
| https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/core/subagents.md |
| https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/core/remote-agents.md |