Gemini CLI extensions: packaged superpowers

By the time a team gets serious about Gemini CLI, the setup is no longer trivial: three MCP servers, a tuned GEMINI.md, a couple of custom commands wrapping the deploy checklist. And the distribution mechanism for all of it is usually a wiki page titled Agent Setup that was last accurate in March. Extensions are Gemini CLI's answer: package the whole bundle, version it, install it as a unit.

What's in the box

An extension is a directory with a gemini-extension.json manifest carrying up to three payloads: MCP server definitions, a context file that merges into the instruction stack alongside your GEMINI.md files, and custom commands. Point gemini extensions install at a git URL or a local path, and every machine on the team gets the same capabilities at the same version. That's the difference in kind from documentation. A wiki page describes a setup. An extension is the setup.

There's a genuine ecosystem now: vendors ship official extensions for their platforms, and teams ship private ones for internal stacks. Treat both like the dependencies they are. Installing one authorizes processes to run and commands to exist on your machine.

Extension, or just a GEMINI.md?

This is the decision that actually matters, and my rule is short: instructions belong in a context file, capabilities belong in an extension.

• Stay with GEMINI.md when you're sharing knowledge about one repo: conventions, commands, architecture. It lives with the code, versions with the code, and gets reviewed like code.
• Build an extension when the setup spans repos, includes machinery like MCP servers or custom commands, or needs versioned rollout to people who will never read the onboarding doc.
• The smell test. If your onboarding page says then paste this into settings.json, that paste is an extension waiting to be written.

A GEMINI.md tells the agent what to know. An extension changes what it can do, and ships both in one install.

The bill

An extension is a supply-chain surface. It starts processes and registers tools with real permissions, and an update can change behavior under you without a single diff landing in your repo. So: pin versions where you can, review updates the way you'd review a lockfile bump, and keep an inventory of what's installed across the team. It's the same governance problem as skills at scale, wearing a different manifest. The context tax applies too: every bundled server and instruction rides into every session where the extension is active, so one fat everything-extension quietly degrades all your projects at once. The MCP discipline (scope tightly, prefer read-only, prune) applies double when the servers arrive pre-bundled and out of sight.

If it's you and one repo, skip all of this: a lean GEMINI.md is plenty and one less thing to govern. The moment two teammates need the same three servers, spend the afternoon writing the extension. It beats every onboarding conversation you'd otherwise repeat, and it turns works-on-my-machine agent setups into something with a version number.