Create Gemini CLI Subagents Skill

Create Gemini CLI Subagents

This skill provides the instructions for creating custom Subagents (specialist agents) within the Gemini CLI.

1. Agent Definition

Subagents are defined as Markdown files (.md) with YAML frontmatter. These files act as the system instructions for a new specialist agent that can be invoked as a tool.

Location

Project-level: .gemini/agents/*.md (shared with the team via git).
User-level: ~/.gemini/agents/*.md (personal agents available in all sessions).

File Format

The file MUST start with YAML frontmatter. The body of the markdown file becomes the agent's System Prompt.

---
name: my-special-agent
description: Specialized in doing specific tasks. This description is used by the main agent to decide when to invoke this subagent.
kind: local
tools:
  - read_file
  - grep_search
model: inherit
temperature: 0.2
max_turns: 10
---
You are a specialist agent. Your job is to...

Note: name (unique slug, a-z, 0-9, -, _) and description are required.

2. Configuration

Ensure subagents are enabled in the Gemini CLI settings (either in the project or user .gemini/settings.json):

{
  "experimental": {
    "enableAgents": true
  }
}

3. Activation

After creating or modifying a subagent file, you MUST inform the user to run the following command in their CLI to load the new definitions:

/agents refresh

4. Usage & Delegation

Once refreshed, the subagent becomes available as a tool matching its name.

Delegation: You can delegate complex, repetitive, or high-volume tasks to the subagent by calling its tool.
Reporting: Subagents return a summary of their work, which keeps the main session context clean and focused.

Agent Skills: Create Gemini CLI Subagents

Install this agent skill to your local

Skill Files