revert: promote Agent Skills to stable (#17693) (#17712)

docs/cli/commands.md

@@ -199,8 +199,8 @@ Slash commands provide meta-level control over the CLI itself.
     while others require a restart.
 
 - [**`/skills`**](./skills.md)
-  - **Description:** Manage Agent Skills, which provide on-demand expertise and
-    specialized workflows.
+  - **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

docs/cli/index.md

@@ -29,8 +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):** Extend the CLI with specialized expertise and
-  procedural workflows.
+- **[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/cli/settings.md

@@ -117,15 +117,10 @@ they appear in the UI.
 
 | UI Label         | Setting                      | Description                                                                         | Default |
 | ---------------- | ---------------------------- | ----------------------------------------------------------------------------------- | ------- |
+| Agent Skills     | `experimental.skills`        | Enable Agent Skills (experimental).                                                 | `false` |
 | Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions). | `false` |
 | Plan             | `experimental.plan`          | Enable planning features (Plan Mode and tools).                                     | `false` |
 
-### Skills
-
-| UI Label            | Setting          | Description          | Default |
-| ------------------- | ---------------- | -------------------- | ------- |
-| Enable Agent Skills | `skills.enabled` | Enable Agent Skills. | `true`  |
-
 ### HooksConfig
 
 | UI Label           | Setting                     | Description                                      | Default |

docs/cli/skills.md

@@ -1,5 +1,9 @@
 # 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

docs/cli/tutorials/skills-getting-started.md

@@ -1,10 +1,37 @@
 # 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 and using it in a
-session.
+tutorial will guide you through creating your first skill, enabling it, and
+using it in a session.
 
-## 1. Create your first skill
+## 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
@@ -59,7 +86,7 @@ responding correctly.
       .catch((e) => console.error(`Result: Failed (${e.message})`));
     ```
 
-## 2. Verify the skill is discovered
+## 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.
@@ -72,7 +99,7 @@ In a Gemini CLI session:
 
 You should see `api-auditor` in the list of available skills.
 
-## 3. Use the skill in a chat
+## 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.

docs/extensions/writing-extensions.md

@@ -225,6 +225,8 @@ file in every session where the extension is active.
 
 ## (Optional) Step 6: Add an Agent Skill
 
+_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.

docs/get-started/configuration.md

@@ -861,6 +861,11 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `false`
   - **Requires restart:** Yes
 
+- **`experimental.skills`** (boolean):
+  - **Description:** Enable Agent Skills (experimental).
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 - **`experimental.useOSC52Paste`** (boolean):
   - **Description:** Use OSC 52 sequence for pasting instead of clipboardy
     (useful for remote sessions).
@@ -873,11 +878,6 @@ their corresponding top-level category object in your `settings.json` file.
 
 #### `skills`
 
-- **`skills.enabled`** (boolean):
-  - **Description:** Enable Agent Skills.
-  - **Default:** `true`
-  - **Requires restart:** Yes
-
 - **`skills.disabled`** (array):
   - **Description:** List of disabled skills.
   - **Default:** `[]`

docs/index.md

@@ -56,8 +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):** Extend the CLI with specialized expertise
-  and procedural workflows.
+- **[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/sidebar.json

@@ -77,7 +77,7 @@
   {
     "label": "Ecosystem and extensibility",
     "items": [
-      { "label": "Agent skills", "slug": "docs/cli/skills" },
+      { "label": "Agent skills (experimental)", "slug": "docs/cli/skills" },
       {
         "label": "Sub-agents (experimental)",
         "slug": "docs/core/subagents"

docs/tools/index.md

@@ -91,8 +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)**: On-demand expertise packages that are
-  activated via the `activate_skill` tool to provide specialized guidance and
-  resources.
+- **[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.