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 | TranslatedConversion type: TranslatedActively 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 |