gemini-extension-structure

name: Gemini Extension Structure description: This skill should be used when the user asks about "Gemini CLI extensions", "gemini-extension.json format", "Gemini commands TOML format", "GEMINI.md context files", "Gemini extension directory structure", or needs to understand how Gemini CLI extensions are organized and configured. version: 0.1.0

Gemini CLI Extension Structure

Reference documentation for creating and understanding Gemini CLI extensions.

Overview

Gemini CLI extensions package prompts, MCP servers, and custom commands into shareable, installable formats. Extensions expand CLI capabilities through a standardized structure.

Directory Structure

Extensions reside in specific locations with a required manifest:

extension-name/
├── gemini-extension.json    # Required: Extension manifest
├── GEMINI.md                # Optional: Context file
├── commands/                # Optional: Custom commands (TOML)
│   ├── command.toml
│   └── namespace/
│       └── subcommand.toml
└── .env                     # Optional: Environment variables

Installation locations:

• User scope: ~/.gemini/extensions/extension-name/
• Workspace scope: <workspace>/.gemini/extensions/extension-name/

Extension Manifest (gemini-extension.json)

The manifest defines extension metadata and configuration.

Required Properties

{
  "name": "extension-name"
}

Name requirements:

• Lowercase letters, numbers, and dashes only
• Must match directory name
• No spaces or special characters

Full Schema

{
  "name": "extension-name",
  "version": "1.0.0",
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${extensionPath}/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command(rm -rf)"],
  "settings": [
    {
      "name": "API_KEY",
      "description": "API key for service",
      "sensitive": true
    }
  ]
}

Variable Substitution

Use these variables in gemini-extension.json:

• ${extensionPath} - Full filesystem path to extension
• ${workspacePath} - Current workspace path
• ${/} or ${pathSeparator} - OS-specific path separator

Custom Commands (TOML Format)

Commands are defined as TOML files in commands/ directory.

File Location and Naming

• commands/test.toml → /test command
• commands/git/commit.toml → /git:commit command

TOML Structure

# Required
prompt = """
Your prompt instructions here.
Use {{args}} for user-provided arguments.
"""

# Optional
description = "Brief description shown in /help"

Dynamic Content

Arguments: Use {{args}} placeholder:

prompt = "Generate a test for: {{args}}"

Shell commands: Use !{...} for dynamic output:

prompt = """
Based on these changes:
```diff
!{git diff --staged}

"""

**File injection:** Use `@{...}` for file/directory content:
```toml
prompt = """
Review this code:
@{src/main.py}
"""

Processing order: @{...} → !{...} → {{args}}

Context Files (GEMINI.md)

Context files provide persistent instructions and knowledge.

Location Hierarchy

1. Global: ~/.gemini/GEMINI.md
2. Workspace/Project: <project>/GEMINI.md or <project>/.gemini/GEMINI.md
3. Extension: Specified by contextFileName in manifest

Precedence: More specific files override general ones.

Format

Standard Markdown with any content:

• Coding conventions
• Project-specific rules
• Style guides
• Domain knowledge

MCP Server Configuration

Configure MCP servers in mcpServers field:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["${extensionPath}/mcp-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Server types:

• command + args: Local stdio-based servers
• HTTP servers: Via URL configuration

Tool Restrictions

Control tool access with excludeTools:

{
  "excludeTools": [
    "run_shell_command",
    "run_shell_command(rm -rf)",
    "file_write"
  ]
}

Supports both full tool blocking and command-specific restrictions.

Extension Settings

Define user-configurable settings:

{
  "settings": [
    {
      "name": "API_KEY",
      "description": "Service API key",
      "sensitive": true
    }
  ]
}

Sensitive settings: Stored in keychain, prompted during installation, saved to extension's .env file.

Extension Management

Install: gemini extensions install <github-url-or-path> Uninstall: gemini extensions uninstall extension-name Enable/Disable: gemini extensions enable/disable extension-name Update: gemini extensions update extension-name Create: gemini extensions new path/to/dir Link (dev): gemini extensions link path/to/dir

Additional Resources

Reference Files

For detailed documentation, consult:

• references/manifest-schema.md - Complete gemini-extension.json schema
• references/commands-toml.md - Full TOML command format documentation

Example Files

Working examples in examples/:

• minimal-extension/ - Minimal extension structure
• full-extension/ - Complete extension with all features