@google/gemini-cli-core 0.41.0-preview.1 → 0.42.0-nightly.20260501.gcaa046641

package/dist/docs/cli/creating-skills.md

@@ -1,18 +1,21 @@
 # Creating Agent Skills
 
-This guide provides an overview of how to create your own Agent Skills to extend
-the capabilities of Gemini CLI.
+Agent Skills let you extend Gemini CLI with specialized expertise, procedural
+workflows, and task-specific resources. This guide walks you through both
+automated and manual methods for creating and organizing your skills.
 
-## Getting started: The `skill-creator` skill
+## Quickstart: Create a skill with a prompt
 
-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.
+The fastest way to create a new skill is to use the built-in `skill-creator`.
+This meta-skill guides you through designing, scaffolding, and validating your
+expertise.
 
-**Example prompt:**
+Simply ask Gemini CLI to create a skill for you:
 
-> "create a new skill called 'code-reviewer'"
+> "Create a new skill called 'code-reviewer' that analyzes local files for
+> common errors and style violations."
 
-Gemini CLI will then use the `skill-creator` to generate the skill:
+Gemini will then:
 
 1.  Generate a new directory for your skill (for example, `my-new-skill/`).
 2.  Create a `SKILL.md` file with the necessary YAML frontmatter (`name` and
@@ -20,61 +23,185 @@ Gemini CLI will then use the `skill-creator` to generate the skill:
 3.  Create the standard resource directories: `scripts/`, `references/`, and
     `assets/`.
 
-## Manual skill creation
+Once created, you can find your new skill in `.gemini/skills/code-reviewer/`.
 
-If you prefer to create skills manually:
+## Manual creation
 
 1.  **Create a directory** for your skill (for example, `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.
+### 1. Create the directory structure
 
-## Skill structure
+The first step is to create the necessary folders for your skill and its
+scripts.
 
-A skill is a directory containing a `SKILL.md` file at its root.
+**macOS/Linux**
 
-### Folder structure
+```bash
+mkdir -p .gemini/skills/code-reviewer/scripts
+```
 
-While a `SKILL.md` file is the only required component, we recommend the
-following structure for organizing your skill's resources:
+**Windows (PowerShell)**
 
-```text
-my-skill/
-├── SKILL.md       (Required) Instructions and metadata
-├── scripts/       (Optional) Executable scripts
-├── references/    (Optional) Static documentation
-└── assets/        (Optional) Templates and other resources
+```powershell
+New-Item -ItemType Directory -Force -Path ".gemini\skills\code-reviewer\scripts"
 ```
 
-### `SKILL.md` file
+### 2. Define the skill (`SKILL.md`)
 
-The `SKILL.md` file is the core of your skill. This file uses YAML frontmatter
-for metadata and Markdown for instructions. For example:
+The `SKILL.md` file defines the skill's purpose and instructions for the agent.
+Create a file at `.gemini/skills/code-reviewer/SKILL.md`.
 
 ```markdown
 ---
 name: code-reviewer
 description:
-  Use this skill to review code. It supports both local changes and remote Pull
-  Requests.
+  Expertise in reviewing code changes for correctness, security, and style. Use
+  when the user asks to "review" their code or a PR.
 ---
 
-# Code Reviewer
+# Code Reviewer Instructions
+
+You act as a senior software engineer specialized in code quality. When this
+skill is active, you MUST:
+
+1.  **Analyze**: Review the provided code for logical errors, security
+    vulnerabilities, and style violations.
+2.  **Review**: Use the bundled `scripts/review.js` utility to perform an
+    automated check.
+3.  **Feedback**: Provide constructive feedback, clearly distinguishing between
+    critical issues and minor improvements.
+```
+
+### 3. Add the tool logic
+
+Skills can bundle resources like scripts to perform deterministic tasks. Create
+a file at `.gemini/skills/code-reviewer/scripts/review.js`.
+
+```javascript
+// .gemini/skills/code-reviewer/scripts/review.js
+const file = process.argv[2];
 
-This skill guides the agent in conducting thorough code reviews.
+if (!file) {
+  console.error('Usage: node review.js <file>');
+  process.exit(1);
+}
 
-## Workflow
+console.log(`Reviewing ${file}...`);
+// Simple mock review logic
+setTimeout(() => {
+  console.log(`Result: Success (No major issues found in ${file})`);
+}, 500);
+```
+
+### 4. Test the skill
+
+Gemini CLI automatically discovers skills in the `.gemini/skills` directory.
+
+1.  Start a new session and ask a question that triggers the skill's
+    description: "Can you review index.js"
+2.  Gemini identifies the request matches the `code-reviewer` description and
+    asks for permission to activate it.
+3.  Once you approve, Gemini executes the bundled script:
+    `node .gemini/skills/code-reviewer/scripts/review.js index.js`
 
-### 1. Determine Review Target
+To determine whether your skill has been correctly loaded, run the command:
 
-- **Remote PR**: If the user gives a PR number or URL, target that remote PR.
-- **Local Changes**: If changes are local... ...
+```bash
+/skills
 ```
 
+### 5. Optional: Share your skill
+
+You can share your skills in several ways depending on your target audience.
+
+- **Workspace skills**: Commit your skill to a `.gemini/skills/` directory in
+  your project repository.
+- **Extensions**: Bundle your skill within a
+  [Gemini CLI extension](../extensions/writing-extensions.md).
+- **Git repositories**: Share the skill directory as a standalone Git repo and
+  install it using `gemini skills install <url>`.
+
+---
+
+## Core concepts
+
+Now that you've built your first skill, let's explore the core components and
+workflows for developing more complex expertise.
+
+### Skill 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
+```
+
+When a skill is activated, the model is granted access to this entire directory.
+You can instruct the model to use the tools and files found within these
+folders.
+
+### Metadata and triggers
+
+The `SKILL.md` file uses YAML frontmatter for metadata.
+
 - **`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.
+- **`description`**: **CRITICAL.** This is how Gemini decides when to use the
+  skill. Be specific about the tasks it handles and the keywords that should
+  trigger it.
+
+### Discovery tiers
+
+Gemini CLI discovers skills from several locations, following a specific order
+of precedence (lowest to highest):
+
+1.  **Built-in Skills**: Included with Gemini CLI (pre-approved).
+2.  **Extension Skills**: Bundled within [extensions](../extensions/).
+3.  **User Skills**: `~/.gemini/skills/` or the `~/.agents/skills/` alias.
+4.  **Workspace Skills**: `.gemini/skills/` or the `.agents/skills/` alias.
+
+### Discovery aliases
+
+You can use `.agents/skills` as an alternative to `.gemini/skills`. This alias
+is compatible with other AI agent tools following the
+[Agent Skills](https://agentskills.io) standard.
+
+## Advanced development
+
+Once you've built a basic skill, you can use specialized scripts and workflows
+to streamline your development process.
+
+### Creation scripts
+
+If you are developing a skill and want to use the same scripts the built-in
+tools use, you can find them in the core package. These scripts help automate
+the initialization, validation, and packaging of skills.
+
+- **Initialize**: `node scripts/init_skill.cjs <name> --path <dir>`
+- **Validate**: `node scripts/validate_skill.cjs <path/to/skill>`
+- **Package**: `node scripts/package_skill.cjs <path/to/skill>` (Creates a
+  `.skill` zip file)
+
+### Linking for local development
+
+If you are developing a skill in a separate directory, you can link it to your
+user skills directory for testing:
+
+```bash
+gemini skills link .
+```
+
+## Next steps
+
+- [Skill best practices](./skills-best-practices.md): Learn strategies for
+  building reliable and effective skills.
+- [Agent Skills overview](./skills.md): Deep dive into discovery tiers and the
+  skill lifecycle.
+- [Get started with Agent Skills](./tutorials/skills-getting-started.md): A
+  quick walkthrough of triggering and using skills.

package/dist/docs/cli/custom-commands.md

@@ -34,6 +34,7 @@ separator (`/` or `\`) being converted to a colon (`:`).
 > [!TIP]
 > After creating or modifying `.toml` command files, run
 > `/commands reload` to pick up your changes without restarting the CLI.
+> To see all available command files, run `/commands list`.
 
 ## TOML file format (v1)
 

package/dist/docs/cli/model-routing.md

@@ -34,11 +34,11 @@ Gemini CLI will use a locally-running **Gemma** model to make routing decisions
 reduce costs associated with hosted model usage while offering similar routing
 decision latency and quality.
 
-In order to use this feature, the local Gemma model **must** be served behind a
-Gemini API and accessible via HTTP at an endpoint configured in `settings.json`.
+The easiest way to set this up is using the automated `gemini gemma setup`
+command.
 
 For more details on how to configure local model routing, see
-[Local Model Routing](../core/local-model-routing.md).
+[`gemini gemma` — Local Model Routing Setup](../core/gemma-setup.md).
 
 ### Model selection precedence
 

package/dist/docs/cli/plan-mode.md

@@ -470,7 +470,8 @@ associated plan files and task trackers.
 
 - **Default behavior:** Sessions (and their plans) are retained for **30 days**.
 - **Configuration:** You can customize this behavior via the `/settings` command
-  (search for **Session Retention**) or in your `settings.json` file. See
+  (search for **Enable Session Cleanup** or **Keep chat history**) or in your
+  `settings.json` file. See
   [session retention](../cli/session-management.md#session-retention) for more
   details.
 

package/dist/docs/cli/skills-best-practices.md

@@ -0,0 +1,78 @@
+# Agent Skill best practices
+
+Create high-quality, reliable Agent Skills by following these established design
+principles and patterns.
+
+## Design for discovery
+
+The most important part of a skill is its `description`. This is the only
+information the model has before activation.
+
+- **Be specific**: Use keywords that are likely to appear in user prompts (for
+  example, "audit," "security," "refactor," "migration").
+- **Define the trigger**: Clearly state _when_ the skill should be used (for
+  example, "Use this skill when the user asks to review a PR for performance
+  regressions").
+- **Avoid overlap**: Ensure your skill descriptions are distinct from one
+  another and from the general capabilities of the model.
+
+## Progressive disclosure
+
+The "context window" is a shared resource. Use a three-level loading system to
+manage context efficiently.
+
+1.  **Metadata (name + description)**: Always in context (~100 words).
+2.  **`SKILL.md` body**: Loaded only after the skill triggers (<5k words).
+3.  **Bundled resources**: Loaded only as needed by the model.
+
+**Best practice**: Keep the `SKILL.md` body focused on core procedural
+instructions. Move detailed reference material, schemas, and examples into
+separate files in a `references/` directory.
+
+## Degrees of freedom
+
+Match the level of instruction specificity to the task's fragility.
+
+- **High freedom (text-based instructions)**: Use when multiple approaches are
+  valid or decisions depend heavily on context.
+- **Medium freedom (pseudocode or scripts with parameters)**: Use when a
+  preferred pattern exists but some variation is acceptable.
+- **Low freedom (specific scripts, few parameters)**: Use when operations are
+  fragile and error-prone, or a specific sequence MUST be followed.
+
+## Bundle resources effectively
+
+Leverage the skill's ability to include scripts and assets to extend the agent's
+capabilities.
+
+- **Use scripts for deterministic tasks**: If a task can be automated with a
+  script (for example, running a linter, fetching data from an API), bundle it
+  in the `scripts/` folder.
+- **Agentic ergonomics**: Ensure scripts output LLM-friendly stdout. Suppress
+  verbose tracebacks and provide clear, concise success/failure messages.
+- **Provide templates**: Include common file headers or boilerplate code in the
+  `assets/` folder to ensure the agent produces consistent output.
+
+## Anatomy of a great skill
+
+A well-structured skill directory organizes its resources into specialized
+sub-folders.
+
+```text
+my-skill/
+├── SKILL.md       (Required) Core instructions and metadata
+├── scripts/       (Optional) Executable logic (Node.js, Python, etc.)
+├── references/    (Optional) Documentation to be loaded as needed
+└── assets/        (Optional) Templates and non-executable resources
+```
+
+## Security and privacy
+
+Design your skills with security in mind to protect your workspace and data.
+
+- **Avoid hardcoded secrets**: Never include API keys or passwords in your
+  skill's scripts or documentation.
+- **Review third-party skills**: Inspect the `SKILL.md` and scripts of any skill
+  before installing it from an untrusted source.
+- **Limit scope**: Design skills to be as focused as possible to minimize the
+  potential impact of errors.

package/dist/docs/cli/skills.md

@@ -1,136 +1,141 @@
 # Agent Skills
 
-Agent Skills allow you to extend Gemini CLI with specialized expertise,
-procedural workflows, and task-specific resources. Based on the
+Agent Skills let you extend Gemini CLI with specialized expertise, procedural
+workflows, and task-specific resources. Based on the
 [Agent Skills](https://agentskills.io) open standard, a "skill" is a
 self-contained directory that packages instructions and assets into a
 discoverable capability.
 
-## Overview
-
-Unlike general context files ([`GEMINI.md`](./gemini-md.md)), which provide
+Unlike general context files ([GEMINI.md](./gemini-md.md)), which provide
 persistent workspace-wide background, Skills represent **on-demand expertise**.
-This allows Gemini to maintain a vast library of specialized capabilities—such
-as security auditing, cloud deployments, or codebase migrations—without
-cluttering the model's immediate context window.
+This lets Gemini CLI maintain a vast library of specialized capabilities—such as
+security auditing, cloud deployments, or codebase migrations—without cluttering
+the model's immediate context window.
 
-Gemini autonomously decides when to employ a skill based on your request and the
-skill's description. When a relevant skill is identified, the model "pulls in"
-the full instructions and resources required to complete the task using the
-`activate_skill` tool.
+## How it works
 
-## Key Benefits
+The lifecycle of an Agent Skill involves discovery, activation, and conditional
+resource access.
 
-- **Shared Expertise:** Package complex workflows (like a specific team's PR
-  review process) into a folder that anyone can use.
-- **Repeatable Workflows:** Ensure complex multi-step tasks are performed
-  consistently by providing a procedural framework.
-- **Resource Bundling:** Include scripts, templates, or example data alongside
-  instructions so the agent has everything it needs.
-- **Progressive Disclosure:** Only skill metadata (name and description) is
-  loaded initially. Detailed instructions and resources are only disclosed when
-  the model explicitly activates the skill, saving context tokens.
+1.  **Discovery**: At the start of a session, Gemini CLI scans the discovery
+    tiers and injects the name and description of all enabled skills into the
+    system prompt.
+2.  **Activation**: When Gemini identifies a task matching a skill's
+    description, it calls the `activate_skill` tool.
+3.  **Consent**: You will see a confirmation prompt in the UI detailing the
+    skill's name, purpose, and the directory path it will gain access to.
+4.  **Injection**: Upon your approval:
+    - The `SKILL.md` body and folder structure is added to the conversation
+      history.
+    - The skill's directory is added to the agent's allowed file paths, granting
+      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.
 
-## Skill Discovery Tiers
+## Discovery tiers
 
-Gemini CLI discovers skills from three primary locations:
+Gemini CLI discovers skills from several locations, following a specific order
+of precedence (lowest to highest):
 
-1.  **Workspace Skills**: Located in `.gemini/skills/` or the `.agents/skills/`
-    alias. Workspace skills are typically committed to version control and
-    shared with the team.
-2.  **User Skills**: Located in `~/.gemini/skills/` or the `~/.agents/skills/`
-    alias. These are personal skills available across all your workspaces.
-3.  **Extension Skills**: Skills bundled within installed
+1.  **Built-in skills**: Standard skills included with Gemini CLI that provide
+    foundational capabilities.
+2.  **Extension skills**: Skills bundled within installed
     [extensions](../extensions/index.md).
+3.  **User skills**: Located in `~/.gemini/skills/` or the `~/.agents/skills/`
+    alias.
+4.  **Workspace skills**: Located in `.gemini/skills/` or the `.agents/skills/`
+    alias. Workspace skills are shared with your team via version control.
 
-**Precedence:** If multiple skills share the same name, higher-precedence
-locations override lower ones: **Workspace > User > Extension**.
+### Precedence and aliases
 
-Within the same tier (user or workspace), the `.agents/skills/` alias takes
-precedence over the `.gemini/skills/` directory. This generic alias provides an
-intuitive path for managing agent-specific expertise that remains compatible
-across different AI agent tools.
+If multiple skills share the same name, the version from the higher-precedence
+location is used. Within the same tier (user or workspace), the
+`.agents/skills/` alias takes precedence over the `.gemini/skills/` directory.
 
-## Managing Skills
+The `.agents/skills/` alias provides an interoperable path for managing
+agent-specific expertise that remains compatible across different AI tools.
 
-### In an Interactive Session
+## Key benefits
 
-Use the `/skills` slash command to view and manage available expertise:
+Agent Skills provide several advantages for managing specialized knowledge and
+complex workflows.
 
-- `/skills list` (default): Shows all discovered skills and their status.
-- `/skills link <path>`: Links agent skills from a local directory via symlink.
-- `/skills disable <name>`: Prevents a specific skill from being used.
-- `/skills enable <name>`: Re-enables a disabled skill.
-- `/skills reload`: Refreshes the list of discovered skills from all tiers.
+- **Shared expertise**: Package complex workflows (like a specific team's PR
+  review process) into a folder that anyone can use.
+- **Repeatable workflows**: Ensure complex multi-step tasks are performed
+  consistently by providing a procedural framework.
+- **Resource bundling**: Include scripts, templates, or example data alongside
+  instructions so the agent has everything it needs.
+- **Progressive disclosure**: Only skill metadata (name and description) is
+  loaded initially. Detailed instructions and resources are only disclosed when
+  the model explicitly activates the skill, saving context tokens.
 
 <!-- prettier-ignore -->
 > [!NOTE]
 > `/skills disable` and `/skills enable` default to the `user` scope. Use
 > `--scope workspace` to manage workspace-specific settings.
 
-### From the Terminal
+To see all available skills in your current session, use the `/skills list`
+command.
 
-The `gemini skills` command provides management utilities:
+## Managing skills
 
-```bash
-# List all discovered skills
-gemini skills list
+You can manage Agent Skills through interactive session commands or directly
+from your terminal.
 
-# Link agent skills from a local directory via symlink
-# Discovers skills (SKILL.md or */SKILL.md) and creates symlinks in ~/.gemini/skills
-# (or ~/.agents/skills)
-gemini skills link /path/to/my-skills-repo
+### In an interactive session
 
-# Link to the workspace scope (.gemini/skills or .agents/skills)
-gemini skills link /path/to/my-skills-repo --scope workspace
+Use the `/skills` slash command to view and manage available expertise:
 
-# Install a skill from a Git repository, local directory, or zipped skill file (.skill)
-# Uses the user scope by default (~/.gemini/skills or ~/.agents/skills)
-gemini skills install https://github.com/user/repo.git
-gemini skills install /path/to/local/skill
-gemini skills install /path/to/local/my-expertise.skill
+- `/skills list [all] [nodesc]`: Shows discovered skills. Use `all` to include
+  built-in skills and `nodesc` to hide descriptions.
+- `/skills link <path> [--scope user|workspace]`: Links skills from a local
+  directory.
+- `/skills disable <name>`: Prevents a specific skill from being used.
+- `/skills enable <name>`: Re-enables a disabled skill.
+- `/skills reload` (or `/skills refresh`): Refreshes the list of discovered
+  skills from all tiers.
 
-# Install a specific skill from a monorepo or subdirectory using --path
-gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design
+### From the terminal
 
-# Install to the workspace scope (.gemini/skills or .agents/skills)
-gemini skills install /path/to/skill --scope workspace
+The `gemini skills` command provides management utilities:
 
-# Uninstall a skill by name
-gemini skills uninstall my-expertise --scope workspace
+```bash
+# List all discovered skills. Use --all to include built-in skills.
+gemini skills list --all
 
-# Enable a skill (globally)
-gemini skills enable my-expertise
+# Install a skill from a Git repository or local directory.
+# Use --consent to skip the security confirmation prompt.
+gemini skills install https://github.com/user/repo.git --consent
 
-# Disable a skill. Can use --scope to specify workspace or user (defaults to workspace)
-gemini skills disable my-expertise --scope workspace
+# Uninstall a skill.
+gemini skills uninstall my-skill --scope workspace
 ```
 
-## How it Works
+#### Command options
 
-1.  **Discovery**: At the start of a session, Gemini CLI scans the discovery
-    tiers and injects the name and description of all enabled skills into the
-    system prompt.
-2.  **Activation**: When Gemini identifies a task matching a skill's
-    description, it calls the `activate_skill` tool.
-3.  **Consent**: You will see a confirmation prompt in the UI detailing the
-    skill's name, purpose, and the directory path it will gain access to.
-4.  **Injection**: Upon your approval:
-    - The `SKILL.md` body and folder structure is added to the conversation
-      history.
-    - The skill's directory is added to the agent's allowed file paths, granting
-      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.
+The skill management commands support several global and command-specific
+options.
+
+- `--scope`: Either `user` (global, default) or `workspace` (local to the
+  project).
+- `--path`: The sub-directory within a Git repository containing the skill.
+- `--consent`: Acknowledge security risks and skip the interactive confirmation
+  during installation.
 
-### Skill activation
+For more details on CLI commands, see the
+[CLI reference](./cli-reference.md#skills-management).
 
-Once a skill is activated (typically by Gemini identifying a task that matches
-the skill's description and your approval), its specialized instructions and
-resources are loaded into the agent's context. A skill remains active and its
-guidance is prioritized for the duration of the session.
+## Next steps
 
-## Creating your own skills
+Explore these resources to refine your skills and understand the framework
+better.
 
-To create your own skills, see the [Create Agent Skills](./creating-skills.md)
-guide.
+- [Get started with Agent Skills](./tutorials/skills-getting-started.md): A
+  quick walkthrough of triggering and using skills.
+- [Creating Agent Skills](./creating-skills.md): Create your first skill and
+  bundle custom logic.
+- [Using Agent Skills](./using-agent-skills.md): Learn how to leverage built-in
+  and custom skills.
+- [Best practices](./skills-best-practices.md): Learn strategies for building
+  effective skills.

package/dist/docs/cli/tutorials/session-management.md

@@ -61,6 +61,19 @@ gemini --list-sessions
 gemini --delete-session 1
 ```
 
+### Scenario: Delete session on exit
+
+If you're doing a one-off task and don't want to leave any session history
+behind, use the `--delete` flag when exiting:
+
+```
+/exit --delete
+```
+
+This removes the current session's conversation history and tool output files
+before exiting. It's useful for privacy-sensitive tasks or quick one-off
+interactions.
+
 ## How to rewind time (Undo mistakes)
 
 Gemini CLI's **Rewind** feature is like `Ctrl+Z` for your workflow.