From d43d772e657b0262f90d73efce1e3993a266da3c Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Thu, 29 Jan 2026 15:52:06 -0800 Subject: [PATCH] Create skills page, update commands, refine docs (#17842) --- docs/cli/commands.md | 212 ++++++++++++++++++++++-------------- docs/cli/creating-skills.md | 80 ++++++++++++++ docs/cli/skills.md | 83 +------------- docs/core/subagents.md | 59 +++++----- docs/sidebar.json | 4 + 5 files changed, 252 insertions(+), 186 deletions(-) create mode 100644 docs/cli/creating-skills.md diff --git a/docs/cli/commands.md b/docs/cli/commands.md index a5b2183206..e79c374e71 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -10,6 +10,14 @@ Slash commands provide meta-level control over the CLI itself. ### Built-in Commands +- **`/about`** + - **Description:** Show version info. Please share this information when + filing issues. + +- **`/auth`** + - **Description:** Open a dialog that lets you change the authentication + method. + - **`/bug`** - **Description:** File an issue about Gemini CLI. By default, the issue is filed within the GitHub repository for Gemini CLI. The string you enter @@ -22,10 +30,21 @@ Slash commands provide meta-level control over the CLI itself. conversation state interactively, or resuming a previous state from a later session. - **Sub-commands:** - - **`save`** + - **`delete `** + - **Description:** Deletes a saved conversation checkpoint. + - **`list`** + - **Description:** Lists available tags for chat state resumption. + - **Note:** This command only lists chats saved within the current + project. Because chat history is project-scoped, chats saved in other + project directories will not be displayed. + - **`resume `** + - **Description:** Resumes a conversation from a previous save. + - **Note:** You can only resume chats that were saved within the current + project. To resume a chat from a different project, you must run the + Gemini CLI from that project's directory. + - **`save `** - **Description:** Saves the current conversation history. You must add a `` for identifying the conversation state. - - **Usage:** `/chat save ` - **Details on checkpoint location:** The default locations for saved chat checkpoints are: - Linux/macOS: `~/.gemini/tmp//` @@ -37,25 +56,11 @@ Slash commands provide meta-level control over the CLI itself. conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../cli/checkpointing.md). - - **`resume`** - - **Description:** Resumes a conversation from a previous save. - - **Usage:** `/chat resume ` - - **Note:** You can only resume chats that were saved within the current - project. To resume a chat from a different project, you must run the - Gemini CLI from that project's directory. - - **`list`** - - **Description:** Lists available tags for chat state resumption. - - **Note:** This command only lists chats saved within the current - project. Because chat history is project-scoped, chats saved in other - project directories will not be displayed. - - **`delete`** - - **Description:** Deletes a saved conversation checkpoint. - - **Usage:** `/chat delete ` - - **`share`** + - **`share [filename]`** - **Description** Writes the current conversation to a provided Markdown - or JSON file. - - **Usage** `/chat share file.md` or `/chat share file.json`. If no - filename is provided, then the CLI will generate one. + or JSON file. If no filename is provided, then the CLI will generate + one. + - **Usage** `/chat share file.md` or `/chat share file.json`. - **`/clear`** - **Description:** Clear the terminal screen, including the visible session @@ -98,6 +103,9 @@ Slash commands provide meta-level control over the CLI itself. `--include-directories`. - **Usage:** `/directory show` +- **`/docs`** + - **Description:** Open the Gemini CLI documentation in your browser. + - **`/editor`** - **Description:** Open a dialog for selecting supported editors. @@ -109,30 +117,65 @@ Slash commands provide meta-level control over the CLI itself. - **Description:** Display help information about Gemini CLI, including available commands and their usage. +- **`/hooks`** + - **Description:** Manage hooks, which allow you to intercept and customize + Gemini CLI behavior at specific lifecycle events. + - **Sub-commands:** + - **`disable-all`**: + - **Description:** Disable all enabled hooks. + - **`disable `**: + - **Description:** Disable a hook by name. + - **`enable-all`**: + - **Description:** Enable all disabled hooks. + - **`enable `**: + - **Description:** Enable a hook by name. + - **`list`** (or `show`, `panel`): + - **Description:** Display all registered hooks with their status. + +- **`/ide`** + - **Description:** Manage IDE integration. + - **Sub-commands:** + - **`disable`**: + - **Description:** Disable IDE integration. + - **`enable`**: + - **Description:** Enable IDE integration. + - **`install`**: + - **Description:** Install required IDE companion. + - **`status`**: + - **Description:** Check status of IDE integration. + +- **`/init`** + - **Description:** To help users easily create a `GEMINI.md` file, this + command analyzes the current directory and generates a tailored context + file, making it simpler for them to provide project-specific instructions to + the Gemini agent. + +- **`/introspect`** + - **Description:** Provide debugging information about the current Gemini CLI + session, including the state of loaded sub-agents and active hooks. This + command is primarily for advanced users and developers. + - **`/mcp`** - **Description:** Manage configured Model Context Protocol (MCP) servers. - **Sub-commands:** - - **`list`** or **`ls`**: - - **Description:** List configured MCP servers and tools. This is the - default action if no subcommand is specified. - - **`desc`** - - **Description:** List configured MCP servers and tools with - descriptions. - - **`schema`**: - - **Description:** List configured MCP servers and tools with descriptions - and schemas. - **`auth`**: - **Description:** Authenticate with an OAuth-enabled MCP server. - **Usage:** `/mcp auth ` - **Details:** If `` is provided, it initiates the OAuth flow for that server. If no server name is provided, it lists all configured servers that support OAuth authentication. + - **`desc`** + - **Description:** List configured MCP servers and tools with + descriptions. + - **`list`** or **`ls`**: + - **Description:** List configured MCP servers and tools. This is the + default action if no subcommand is specified. - **`refresh`**: - **Description:** Restarts all MCP servers and re-discovers their available tools. - -- [**`/model`**](./model.md) - - **Description:** Opens a dialog to choose your Gemini model. + - **`schema`**: + - **Description:** List configured MCP servers and tools with descriptions + and schemas. - **`/memory`** - **Description:** Manage the AI's instructional context (hierarchical memory @@ -141,23 +184,40 @@ Slash commands provide meta-level control over the CLI itself. - **`add`**: - **Description:** Adds the following text to the AI's memory. Usage: `/memory add ` - - **`show`**: - - **Description:** Display the full, concatenated content of the current - hierarchical memory that has been loaded from all `GEMINI.md` files. - This lets you inspect the instructional context being provided to the - Gemini model. + - **`list`**: + - **Description:** Lists the paths of the GEMINI.md files in use for + hierarchical memory. - **`refresh`**: - **Description:** Reload the hierarchical instructional memory from all `GEMINI.md` files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the model with the latest `GEMINI.md` content. - - **`list`**: - - **Description:** Lists the paths of the GEMINI.md files in use for - hierarchical memory. + - **`show`**: + - **Description:** Display the full, concatenated content of the current + hierarchical memory that has been loaded from all `GEMINI.md` files. + This lets you inspect the instructional context being provided to the + Gemini model. - **Note:** For more details on how `GEMINI.md` files contribute to hierarchical memory, see the [CLI Configuration documentation](../get-started/configuration.md). +- [**`/model`**](./model.md) + - **Description:** Opens a dialog to choose your Gemini model. + +- **`/policies`** + - **Description:** Manage policies. + - **Sub-commands:** + - **`list`**: + - **Description:** List all active policies grouped by mode. + +- **`/privacy`** + - **Description:** Display the Privacy Notice and allow users to select + whether they consent to the collection of their data for service improvement + purposes. + +- **`/quit`** (or **`/exit`**) + - **Description:** Exit Gemini CLI. + - **`/restore`** - **Description:** Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file @@ -168,18 +228,24 @@ Slash commands provide meta-level control over the CLI itself. [settings](../get-started/configuration.md). See [Checkpointing documentation](../cli/checkpointing.md) for more details. +- **`/rewind`** + - **Description:** Navigates backward through the conversation history, + allowing you to review past interactions and potentially revert to a + previous state. This feature helps in managing complex or branched + conversations. + - **`/resume`** - **Description:** Browse and resume previous conversation sessions. Opens an interactive session browser where you can search, filter, and select from automatically saved conversations. - **Features:** - - **Session Browser:** Interactive interface showing all saved sessions with - timestamps, message counts, and first user message for context - - **Search:** Use `/` to search through conversation content across all - sessions - - **Sorting:** Sort sessions by date or message count - **Management:** Delete unwanted sessions directly from the browser - **Resume:** Select any session to resume and continue the conversation + - **Search:** Use `/` to search through conversation content across all + sessions + - **Session Browser:** Interactive interface showing all saved sessions with + timestamps, message counts, and first user message for context + - **Sorting:** Sort sessions by date or message count - **Note:** All conversations are automatically saved as you chat - no manual saving required. See [Session Management](../cli/session-management.md) for complete details. @@ -198,19 +264,23 @@ Slash commands provide meta-level control over the CLI itself. modify them as desired. Changes to some settings are applied immediately, while others require a restart. +- **`/setup-github`** + - **Description:** Set up GitHub Actions to triage issues and review PRs with + Gemini. + - [**`/skills`**](./skills.md) - **Description:** Manage Agent Skills, which provide on-demand expertise and specialized workflows. - **Sub-commands:** + - **`disable `**: + - **Description:** Disable a specific skill by name. + - **Usage:** `/skills disable ` + - **`enable `**: + - **Description:** Enable a specific skill by name. + - **Usage:** `/skills enable ` - **`list`**: - **Description:** List all discovered skills and their current status (enabled/disabled). - - **`enable`**: - - **Description:** Enable a specific skill by name. - - **Usage:** `/skills enable ` - - **`disable`**: - - **Description:** Disable a specific skill by name. - - **Usage:** `/skills disable ` - **`reload`**: - **Description:** Refresh the list of discovered skills from all tiers (workspace, user, and extensions). @@ -222,18 +292,14 @@ Slash commands provide meta-level control over the CLI itself. cached tokens are being used, which occurs with API key authentication but not with OAuth authentication at this time. +- **`/terminal-setup`** + - **Description:** Configure terminal keybindings for multiline input (VS + Code, Cursor, Windsurf). + - [**`/theme`**](./themes.md) - **Description:** Open a dialog that lets you change the visual theme of Gemini CLI. -- **`/auth`** - - **Description:** Open a dialog that lets you change the authentication - method. - -- **`/about`** - - **Description:** Show version info. Please share this information when - filing issues. - - [**`/tools`**](../tools/index.md) - **Description:** Display a list of tools that are currently available within Gemini CLI. @@ -245,37 +311,23 @@ Slash commands provide meta-level control over the CLI itself. - **`nodesc`** or **`nodescriptions`**: - **Description:** Hide tool descriptions, showing only the tool names. -- **`/privacy`** - - **Description:** Display the Privacy Notice and allow users to select - whether they consent to the collection of their data for service improvement - purposes. - -- **`/quit`** (or **`/exit`**) - - **Description:** Exit Gemini CLI. - - **`/vim`** - **Description:** Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes. - **Features:** + - **Count support:** Prefix commands with numbers (e.g., `3h`, `5w`, `10G`) + - **Editing commands:** Delete with `x`, change with `c`, insert with `i`, + `a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw` + - **INSERT mode:** Standard text input with escape to return to NORMAL mode - **NORMAL mode:** Navigate with `h`, `j`, `k`, `l`; jump by words with `w`, `b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines with `G` (or `gg` for first line) - - **INSERT mode:** Standard text input with escape to return to NORMAL mode - - **Editing commands:** Delete with `x`, change with `c`, insert with `i`, - `a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw` - - **Count support:** Prefix commands with numbers (e.g., `3h`, `5w`, `10G`) - - **Repeat last command:** Use `.` to repeat the last editing operation - **Persistent setting:** Vim mode preference is saved to `~/.gemini/settings.json` and restored between sessions - - **Status indicator:** When enabled, shows `[NORMAL]` or `[INSERT]` in the - footer - -- **`/init`** - - **Description:** To help users easily create a `GEMINI.md` file, this - command analyzes the current directory and generates a tailored context - file, making it simpler for them to provide project-specific instructions to - the Gemini agent. + - **Repeat last command:** Use `.` to repeat the last editing operation + - **Status indicator:** When enabled, shows `[NORMAL]` or `[INSERT]` in the + footer ### Custom commands diff --git a/docs/cli/creating-skills.md b/docs/cli/creating-skills.md new file mode 100644 index 0000000000..9826ddbfce --- /dev/null +++ b/docs/cli/creating-skills.md @@ -0,0 +1,80 @@ +# Creating Agent Skills + +This guide provides an overview of how to create your own Agent Skills to extend +the capabilities of Gemini CLI. + +## Getting started: The `skill-creator` skill + +The recommended way to create a new skill is to use the built-in `skill-creator` +skill. To use it, ask Gemini CLI to create a new skill for you. + +**Example prompt:** + +> "create a new skill called 'code-reviewer'" + +Gemini CLI will then use the `skill-creator` to generate the skill: + +1. Generate a new directory for your skill (e.g., `my-new-skill/`). +2. Create a `SKILL.md` file with the necessary YAML frontmatter (`name` and + `description`). +3. Create the standard resource directories: `scripts/`, `references/`, and + `assets/`. + +## Manual skill creation + +If you prefer to create skills manually: + +1. **Create a directory** for your skill (e.g., `my-new-skill/`). +2. **Create a `SKILL.md` file** inside the new directory. + +To add additional resources that support the skill, refer to the skill +structure. + +## Skill structure + +A skill is a directory containing a `SKILL.md` file at its root. + +### Folder structure + +While a `SKILL.md` file is the only required component, we recommend the +following structure for organizing your skill's resources: + +```text +my-skill/ +├── SKILL.md (Required) Instructions and metadata +├── scripts/ (Optional) Executable scripts +├── references/ (Optional) Static documentation +└── assets/ (Optional) Templates and other resources +``` + +### `SKILL.md` file + +The `SKILL.md` file is the core of your skill. This file uses YAML frontmatter +for metadata and Markdown for instructions. For example: + +```markdown +--- +name: code-reviewer +description: + Use this skill to review code. It supports both local changes and remote Pull + Requests. +--- + +# Code Reviewer + +This skill guides the agent in conducting thorough code reviews. + +## Workflow + +### 1. Determine Review Target + +- **Remote PR**: If the user gives a PR number or URL, target that remote PR. +- **Local Changes**: If changes are local... ... +``` + +- **`name`**: A unique identifier for the skill. This should match the directory + name. +- **`description`**: A description of what the skill does and when Gemini should + use it. +- **Body**: The Markdown body of the file contains the instructions that guide + the agent's behavior when the skill is active. diff --git a/docs/cli/skills.md b/docs/cli/skills.md index 3b3519121c..b8a71fde86 100644 --- a/docs/cli/skills.md +++ b/docs/cli/skills.md @@ -89,84 +89,6 @@ gemini skills enable my-expertise gemini skills disable my-expertise --scope workspace ``` -## Creating a Skill - -A skill is a directory containing a `SKILL.md` file at its root. This file -serves as the entry point for your skill and uses YAML frontmatter for metadata -and Markdown for instructions. - -### Folder Structure - -Skills are self-contained directories. At a minimum, a skill requires a -`SKILL.md` file, but can include other resources: - -```text -my-skill/ -├── SKILL.md (Required) Instructions and metadata -├── scripts/ (Optional) Executable scripts/tools -├── references/ (Optional) Static documentation and examples -└── assets/ (Optional) Templates and binary resources -``` - -### Basic Structure (SKILL.md) - -```markdown ---- -name: -description: ---- - - -``` - -- **`name`**: A unique identifier (lowercase, alphanumeric, and dashes). -- **`description`**: The most critical field. Gemini uses this to decide when - the skill is relevant. Be specific about the expertise provided. -- **Body**: Everything below the second `---` is injected as expert procedural - guidance for the model. - -### Example: Team Code Reviewer - -Create `~/.gemini/skills/code-reviewer/SKILL.md`: - -```markdown ---- -name: code-reviewer -description: - Expertise in reviewing code for style, security, and performance. Use when the - user asks for "feedback," a "review," or to "check" their changes. ---- - -# Code Reviewer - -You are an expert code reviewer. When reviewing code, follow this workflow: - -1. **Analyze**: Review the staged changes or specific files provided. Ensure - that the changes are scoped properly and represent minimal changes required - to address the issue. -2. **Style**: Ensure code follows the workspace's conventions and idiomatic - patterns as described in the `GEMINI.md` file. -3. **Security**: Flag any potential security vulnerabilities. -4. **Tests**: Verify that new logic has corresponding test coverage and that - the test coverage adequately validates the changes. - -Provide your feedback as a concise bulleted list of "Strengths" and -"Opportunities." -``` - -### Resource Conventions - -While you can structure your skill directory however you like, the Agent Skills -standard encourages these conventions: - -- **`scripts/`**: Executable scripts (bash, python, node) the agent can run. -- **`references/`**: Static documentation, schemas, or example data for the - agent to consult. -- **`assets/`**: Code templates, boilerplate, or binary resources. - -When a skill is activated, Gemini CLI provides the model with a tree view of the -entire skill directory, allowing it to discover and utilize these assets. - ## How it Works (Security & Privacy) 1. **Discovery**: At the start of a session, Gemini CLI scans the discovery @@ -183,3 +105,8 @@ entire skill directory, allowing it to discover and utilize these assets. it permission to read any bundled assets. 5. **Execution**: The model proceeds with the specialized expertise active. It is instructed to prioritize the skill's procedural guidance within reason. + +## Creating your own skills + +To create your own skills, see the +[Create Agent Skills](./guides/creating-skills.md) guide. diff --git a/docs/core/subagents.md b/docs/core/subagents.md index a9be1bdae5..d43d1f3aa1 100644 --- a/docs/core/subagents.md +++ b/docs/core/subagents.md @@ -24,30 +24,29 @@ the main agent's context or toolset. ## What are sub-agents? -Think of sub-agents as "specialists" that the main Gemini agent can hire for a -specific job. +Sub-agents are "specialists" that the main Gemini agent can hire for a specific +job. - **Focused context:** Each sub-agent has its own system prompt and persona. - **Specialized tools:** Sub-agents can have a restricted or specialized set of tools. - **Independent context window:** Interactions with a sub-agent happen in a - separate context loop. The main agent only sees the final result, saving - tokens in your main conversation history. + separate context loop, which saves tokens in your main conversation history. -Sub-agents are exposed to the main agent as a tool of the same name which -delegates to the sub-agent, when called. Once the sub-agent completes its task -(or fails), it reports back to the main agent with its findings (usually as a -text summary or structured report returned by the tool). +Sub-agents are exposed to the main agent as a tool of the same name. When the +main agent calls the tool, it delegates the task to the sub-agent. Once the +sub-agent completes its task, it reports back to the main agent with its +findings. ## Built-in sub-agents -Gemini CLI comes with powerful built-in sub-agents. +Gemini CLI comes with the following built-in sub-agents: ### Codebase Investigator - **Name:** `codebase_investigator` -- **Purpose:** Deep analysis of the codebase, reverse engineering, and - understanding complex dependencies. +- **Purpose:** Analyze the codebase, reverse engineer, and understand complex + dependencies. - **When to use:** "How does the authentication system work?", "Map out the dependencies of the `AgentRegistry` class." - **Configuration:** Enabled by default. You can configure it in @@ -67,20 +66,25 @@ Gemini CLI comes with powerful built-in sub-agents. ### CLI Help Agent - **Name:** `cli_help` -- **Purpose:** Expert knowledge about Gemini CLI itself, its commands, +- **Purpose:** Get expert knowledge about Gemini CLI itself, its commands, configuration, and documentation. - **When to use:** "How do I configure a proxy?", "What does the `/rewind` command do?" - **Configuration:** Enabled by default. +### Generalist Agent + +- **Name:** `generalist_agent` +- **Purpose:** Route tasks to the appropriate specialized sub-agent. +- **When to use:** Implicitly used by the main agent for routing. Not directly + invoked by the user. +- **Configuration:** Enabled by default. No specific configuration options. + ## Creating custom sub-agents You can create your own sub-agents to automate specific workflows or enforce -specific personas. - -### Prerequisites - -To use custom sub-agents, you must enable them in your `settings.json`: +specific personas. To use custom sub-agents, you must enable them in your +`settings.json`: ```json { @@ -123,10 +127,10 @@ vulnerabilities. Focus on: -1. SQL Injection -2. XSS (Cross-Site Scripting) -3. Hardcoded credentials -4. Unsafe file operations +1. SQL Injection +2. XSS (Cross-Site Scripting) +3. Hardcoded credentials +4. Unsafe file operations When you find a vulnerability, explain it clearly and suggest a fix. Do not fix it yourself; just report it. @@ -147,17 +151,16 @@ it yourself; just report it. ### Optimizing your sub-agent -The main agent system prompt contains language that encourages use of an expert -sub-agent when one is available for the task at hand. It decides whether an -agent is a relevant expert based on the agent's description. You can improve the -reliability with which an agent is used by updating the description to more -clearly indicate: +The main agent's system prompt encourages it to use an expert sub-agent when one +is available. It decides whether an agent is a relevant expert based on the +agent's description. You can improve the reliability with which an agent is used +by updating the description to more clearly indicate: - Its area of expertise. - When it should be used. - Some example scenarios. -For example: the following sub-agent description should be called fairly +For example, the following sub-agent description should be called fairly consistently for Git operations. > Git expert agent which should be used for all local and remote git operations. @@ -173,7 +176,7 @@ that your sub-agent was called with a specific prompt and the given description. ## Remote subagents (Agent2Agent) (experimental) -Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent +Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent (A2A) protocol. > **Note: Remote subagents are currently an experimental feature.** diff --git a/docs/sidebar.json b/docs/sidebar.json index 589ad32f14..dfbfba80e7 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -79,6 +79,10 @@ "label": "Ecosystem and extensibility", "items": [ { "label": "Agent skills", "slug": "docs/cli/skills" }, + { + "label": "Creating Agent skills", + "slug": "docs/cli/creating-skills" + }, { "label": "Sub-agents (experimental)", "slug": "docs/core/subagents"