diff --git a/docs/cli/settings.md b/docs/cli/settings.md index 96912995d4..f281ec8da0 100644 --- a/docs/cli/settings.md +++ b/docs/cli/settings.md @@ -111,3 +111,4 @@ they appear in the UI. | ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | ------- | | Enable Codebase Investigator | `experimental.codebaseInvestigatorSettings.enabled` | Enable the Codebase Investigator agent. | `true` | | Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent. | `10` | +| Agent Skills | `experimental.skills` | Enable Agent Skills (experimental). | `false` | diff --git a/docs/cli/skills.md b/docs/cli/skills.md new file mode 100644 index 0000000000..0badd9adaa --- /dev/null +++ b/docs/cli/skills.md @@ -0,0 +1,156 @@ +# Agent Skills + +_Note: This is an experimental feature enabled via `experimental.skills`. You +can also search for "Skills" within the `/settings` interactive UI to toggle +this and manage other skill-related settings._ + +Agent Skills allow you to 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 +persistent project-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. + +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. + +## Key Benefits + +- **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. + +## Skill Discovery Tiers + +Gemini CLI discovers skills from three primary locations: + +1. **Project Skills** (`.gemini/skills/`): Project-specific skills that are + typically committed to version control and shared with the team. +2. **User Skills** (`~/.gemini/skills/`): Personal skills available across all + your projects. +3. **Extension Skills**: Skills bundled within installed + [extensions](../extensions/index.md). + +**Precedence:** If multiple skills share the same name, higher-precedence +locations override lower ones: **Project > User > Extension**. + +## Managing Skills + +### In an Interactive Session + +Use the `/skills` slash command to view and manage available expertise: + +- `/skills list` (default): Shows all discovered skills and their status. +- `/skills disable `: Prevents a specific skill from being used. +- `/skills enable `: Re-enables a disabled skill. +- `/skills reload`: Refreshes the list of discovered skills from all tiers. + +_Note: `/skills disable` and `/skills enable` default to the `user` scope. Use +`--scope project` to manage project-specific settings._ + +### From the Terminal + +The `gemini skills` command provides management utilities: + +```bash +# List all discovered skills +gemini skills list + +# Enable/disable skills. Can use --scope to specify project or user +gemini skills enable my-expertise +gemini skills disable my-expertise +``` + +## Creating a Skill + +A skill is a directory containing a `SKILL.md` file at its root. This file uses +YAML frontmatter for metadata and Markdown for instructions. + +### Basic Structure + +```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 + +```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 project'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 + 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. diff --git a/docs/cli/tutorials.md b/docs/cli/tutorials.md index dff8918b5e..fe41220679 100644 --- a/docs/cli/tutorials.md +++ b/docs/cli/tutorials.md @@ -2,6 +2,10 @@ This page contains tutorials for interacting with Gemini CLI. +## Agent Skills + +- [Getting Started with Agent Skills](./tutorials/skills-getting-started.md) + ## Setting up a Model Context Protocol (MCP) server > [!CAUTION] Before using a third-party MCP server, ensure you trust its source diff --git a/docs/cli/tutorials/skills-getting-started.md b/docs/cli/tutorials/skills-getting-started.md new file mode 100644 index 0000000000..f559f6b1e5 --- /dev/null +++ b/docs/cli/tutorials/skills-getting-started.md @@ -0,0 +1,124 @@ +# Getting Started with Agent Skills + +Agent Skills allow you to extend Gemini CLI with specialized expertise. This +tutorial will guide you through creating your first skill, enabling it, and +using it in a session. + +## 1. Enable Agent Skills + +Agent Skills are currently an experimental feature and must be enabled in your +settings. + +### Via the interactive UI + +1. Start a Gemini CLI session by running `gemini`. +2. Type `/settings` to open the interactive settings dialog. +3. Search for "Skills". +4. Toggle **Agent Skills** to `true`. +5. Press `Esc` to save and exit. You may need to restart the CLI for the + changes to take effect. + +### Via `settings.json` + +Alternatively, you can manually edit your global settings file at +`~/.gemini/settings.json` (create it if it doesn't exist): + +```json +{ + "experimental": { + "skills": true + } +} +``` + +## 2. Create Your First Skill + +A skill is a directory containing a `SKILL.md` file. Let's create an **API +Auditor** skill that helps you verify if local or remote endpoints are +responding correctly. + +1. **Create the skill directory structure:** + + ```bash + mkdir -p .gemini/skills/api-auditor/scripts + ``` + +2. **Create the `SKILL.md` file:** Create a file at + `.gemini/skills/api-auditor/SKILL.md` with the following content: + + ```markdown + --- + name: api-auditor + description: + Expertise in auditing and testing API endpoints. Use when the user asks to + "check", "test", or "audit" a URL or API. + --- + + # API Auditor Instructions + + You act as a QA engineer specialized in API reliability. When this skill is + active, you MUST: + + 1. **Audit**: Use the bundled `scripts/audit.js` utility to check the + status of the provided URL. + 2. **Report**: Analyze the output (status codes, latency) and explain any + failures in plain English. + 3. **Secure**: Remind the user if they are testing a sensitive endpoint + without an `https://` protocol. + ``` + +3. **Create the bundled Node.js script:** Create a file at + `.gemini/skills/api-auditor/scripts/audit.js`. This script will be used by + the agent to perform the actual check: + + ```javascript + // .gemini/skills/api-auditor/scripts/audit.js + const url = process.argv[2]; + + if (!url) { + console.error('Usage: node audit.js '); + process.exit(1); + } + + console.log(`Auditing ${url}...`); + fetch(url, { method: 'HEAD' }) + .then((r) => console.log(`Result: Success (Status ${r.status})`)) + .catch((e) => console.error(`Result: Failed (${e.message})`)); + ``` + +## 3. Verify the Skill is Discovered + +Use the `/skills` slash command (or `gemini skills list` from your terminal) to +see if Gemini CLI has found your new skill. + +In a Gemini CLI session: + +``` +/skills list +``` + +You should see `api-auditor` in the list of available skills. + +## 4. Use the Skill in a Chat + +Now, let's see the skill in action. Start a new session and ask a question about +an endpoint. + +**User:** "Can you audit http://geminili.com" + +Gemini will recognize the request matches the `api-auditor` description and will +ask for your permission to activate it. + +**Model:** (After calling `activate_skill`) "I've activated the **api-auditor** +skill. I'll run the audit script now..." + +Gemini will then use the `run_shell_command` tool to execute your bundled Node +script: + +`node .gemini/skills/api-auditor/scripts/audit.js http://geminili.com` + +## Next Steps + +- Explore [Agent Skills Authoring Guide](../skills.md#creating-a-skill) to learn + about more advanced skill features. +- Learn how to share skills via [Extensions](../../extensions/index.md). diff --git a/docs/sidebar.json b/docs/sidebar.json index 147bbe106b..a65bade052 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -88,6 +88,10 @@ "label": "Session Management", "slug": "docs/cli/session-management" }, + { + "label": "Agent Skills", + "slug": "docs/cli/skills" + }, { "label": "Settings", "slug": "docs/cli/settings"