Docs: Clarify extensions documentation. (#19277)

docs/extensions/index.md

@@ -6,19 +6,44 @@ With extensions, you can expand the capabilities of Gemini CLI and share those
 capabilities with others. They are 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/).
+To see what's possible, browse the
+[Gemini CLI extension gallery](https://geminicli.com/extensions/browse/).
 
-## Managing extensions
+## Choose your path
 
-You can verify your installed extensions and their status using the interactive
-command:
+Choose the guide that best fits your needs.
+
+### I want to use extensions
+
+Learn how to discover, install, and manage extensions to enhance your Gemini CLI
+experience.
+
+- **[Manage extensions](#manage-extensions):** List and verify your installed
+  extensions.
+- **[Install extensions](#installation):** Add new capabilities from GitHub or
+  local paths.
+
+### I want to build extensions
+
+Learn how to create, test, and share your own extensions with the community.
+
+- **[Build extensions](writing-extensions.md):** Create your first extension
+  from a template.
+- **[Best practices](best-practices.md):** Learn how to build secure and
+  reliable extensions.
+- **[Publish to the gallery](releasing.md):** Share your work with the world.
+
+## Manage extensions
+
+Use the interactive `/extensions` command to verify your installed extensions
+and their status:
 
 ```bash
 /extensions list
 ```
 
-or in noninteractive mode:
+You can also manage extensions from your terminal using the `gemini extensions`
+command group:
 
 ```bash
 gemini extensions list
@@ -26,20 +51,11 @@ gemini extensions list
 
 ## Installation
 
-To install a real extension, you can use the `extensions install` command with a
-GitHub repository URL in noninteractive mode. For example:
+Install an extension by providing its GitHub repository URL. For example:
 
 ```bash
 gemini extensions install https://github.com/gemini-cli-extensions/workspace
 ```
 
-## Next steps
-
-- [Writing extensions](writing-extensions.md): Learn how to create your first
-  extension.
-- [Extensions reference](reference.md): Deeply understand the extension format,
-  commands, and configuration.
-- [Best practices](best-practices.md): Learn strategies for building great
-  extensions.
-- [Extensions releasing](releasing.md): Learn how to share your extensions with
-  the world.
+For more advanced installation options, see the
+[Extension reference](reference.md#install-an-extension).