docs(extensions): add Agent Skills support and mark feature as experimental (#16859)

docs/cli/commands.md

@@ -204,6 +204,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.
 
+- [**`/skills`**](./skills.md)
+  - **Description:** (Experimental) Manage Agent Skills, which provide on-demand
+    expertise and specialized workflows.
+  - **Sub-commands:**
+    - **`list`**:
+      - **Description:** List all discovered skills and their current status
+        (enabled/disabled).
+    - **`enable`**:
+      - **Description:** Enable a specific skill by name.
+      - **Usage:** `/skills enable <name>`
+    - **`disable`**:
+      - **Description:** Disable a specific skill by name.
+      - **Usage:** `/skills disable <name>`
+    - **`reload`**:
+      - **Description:** Refresh the list of discovered skills from all tiers
+        (workspace, user, and extensions).
+
 - **`/stats`**
   - **Description:** Display detailed statistics for the current Gemini CLI
     session, including token usage, cached token savings (when available), and

docs/cli/index.md

@@ -29,6 +29,8 @@ overview of Gemini CLI, see the [main documentation page](../index.md).
   in an enterprise environment.
 - **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
   containerized environment.
+- **[Agent Skills](./skills.md):** (Experimental) Extend the CLI with
+  specialized expertise and procedural workflows.
 - **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
   performance.
 - **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.

docs/extensions/getting-started-extensions.md

@@ -222,9 +222,45 @@ need this for extensions built to expose commands and prompts.
 Restart the CLI again. The model will now have the context from your `GEMINI.md`
 file in every session where the extension is active.
 
-## Step 6: Releasing your extension
+## (Optional) Step 6: Add an Agent Skill
 
-Once you are happy with your extension, you can share it with others. The two
+_Note: This is an experimental feature enabled via `experimental.skills`._
+
+[Agent Skills](../cli/skills.md) let you bundle specialized expertise and
+procedural workflows. Unlike `GEMINI.md`, which provides persistent context,
+skills are activated only when needed, saving context tokens.
+
+1.  Create a `skills` directory and a subdirectory for your skill:
+
+    ```bash
+    mkdir -p skills/security-audit
+    ```
+
+2.  Create a `skills/security-audit/SKILL.md` file:
+
+    ```markdown
+    ---
+    name: security-audit
+    description:
+      Expertise in auditing code for security vulnerabilities. Use when the user
+      asks to "check for security issues" or "audit" their changes.
+    ---
+
+    # Security Auditor
+
+    You are an expert security researcher. When auditing code:
+
+    1. Look for common vulnerabilities (OWASP Top 10).
+    2. Check for hardcoded secrets or API keys.
+    3. Suggest remediation steps for any findings.
+    ```
+
+Skills bundled with your extension are automatically discovered and can be
+activated by the model during a session when it identifies a relevant task.
+
+## Step 7: Release your extension
+
+Once you're happy with your extension, you can share it with others. The two
 primary ways of releasing extensions are via a Git repository or through GitHub
 Releases. Using a public Git repository is the simplest method.
 
@@ -239,6 +275,7 @@ You've successfully created a Gemini CLI extension! You learned how to:
 - Add custom tools with an MCP server.
 - Create convenient custom commands.
 - Provide persistent context to the model.
+- Bundle specialized Agent Skills.
 - Link your extension for local development.
 
 From here, you can explore more advanced features and build powerful new

docs/extensions/index.md

@@ -2,10 +2,10 @@
 
 _This documentation is up-to-date with the v0.4.0 release._
 
-Gemini CLI extensions package prompts, MCP servers, and custom commands into a
+Gemini CLI extensions package prompts, MCP servers, Agent Skills, and custom
-familiar and user-friendly format. With extensions, you can expand the
+commands into a familiar and user-friendly format. With extensions, you can
-capabilities of Gemini CLI and share those capabilities with others. They are
+expand the capabilities of Gemini CLI and share those capabilities with others.
-designed to be easily installable and shareable.
+They're designed to be easily installable and shareable.
 
 To see examples of extensions, you can browse a gallery of
 [Gemini CLI extensions](https://geminicli.com/extensions/browse/).
@@ -263,6 +263,40 @@ Would provide these commands:
 - `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
 - `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
 
+### Agent Skills
+
+_Note: This is an experimental feature enabled via `experimental.skills`._
+
+Extensions can bundle [Agent Skills](../cli/skills.md) to provide on-demand
+expertise and specialized workflows. To include skills in your extension, place
+them in a `skills/` subdirectory within the extension directory. Each skill must
+follow the [Agent Skills structure](../cli/skills.md#folder-structure),
+including a `SKILL.md` file.
+
+**Example**
+
+An extension named `security-toolkit` with the following structure:
+
+```
+.gemini/extensions/security-toolkit/
+├── gemini-extension.json
+└── skills/
+    ├── audit/
+    │   ├── SKILL.md
+    │   └── scripts/
+    │       └── scan.py
+    └── hardening/
+        └── SKILL.md
+```
+
+Upon installation, these skills will be discovered by Gemini CLI and can be
+activated during a session when the model identifies a task matching their
+descriptions.
+
+Extension skills have the lowest precedence and will be overridden by user or
+workspace skills of the same name. They can be viewed and managed (enabled or
+disabled) using the [`/skills` command](../cli/skills.md#managing-skills).
+
 ### Hooks
 
 Extensions can provide [hooks](../hooks/index.md) to intercept and customize

docs/index.md

@@ -56,6 +56,8 @@ This documentation is organized into the following sections:
   commands with `/model`.
 - **[Sandbox](./cli/sandbox.md):** Isolate tool execution in a secure,
   containerized environment.
+- **[Agent Skills](./cli/skills.md):** (Experimental) Extend the CLI with
+  specialized expertise and procedural workflows.
 - **[Settings](./cli/settings.md):** Configure various aspects of the CLI's
   behavior and appearance with `/settings`.
 - **[Telemetry](./cli/telemetry.md):** Overview of telemetry in the CLI.

docs/tools/index.md

@@ -91,5 +91,8 @@ Additionally, these tools incorporate:
 
 - **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the
   Gemini model and your local environment or other services like APIs.
+- **[Agent Skills](../cli/skills.md)**: (Experimental) On-demand expertise
+  packages that are activated via the `activate_skill` tool to provide
+  specialized guidance and resources.
 - **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
   changes from your environment to reduce potential risk.