How the Gemini CLI Extension Achieves Always-On Functionality with GEMINI.md

TLDR: The Gemini CLI extension enables always-on behavior by using an extension manifest (gemini-extension.json) that points to a persistent context file (GEMINI.md), which imports the full ADHD skill definition — so the skill loads automatically in every session without user commands.

The i-have-adhd repository implements a Gemini CLI extension that injects a set of ADHD-friendly response rules into every Gemini session. According to the source code, this works through two complementary mechanisms: a simple manifest and a lightweight context file. The extension's design is deliberately minimal, making it easy to install and immediately effective.

How the Extension Works

The always-on pipeline relies on two files located at the repository root:

1. gemini-extension.json — the extension manifest that registers GEMINI.md as the persistent context file.
2. GEMINI.md — a wrapper that imports the actual skill prompt from the skills/ directory.

When the extension is installed, the Gemini runtime reads the manifest, identifies the context file, and prepends GEMINI.md to the system prompt before processing any user message. Because this happens at the framework level, the rules are applied from the very first turn of every conversation — no dedicated command required.

The Extension Manifest (gemini-extension.json)

The manifest tells the Gemini runtime exactly which file to load as persistent context. The critical entry is "contextFileName":

{
  "name": "i-have-adhd",
  "contextFileName": "GEMINI.md"
}

Once the extension is installed, Gemini automatically reads this file before handling any user input. This is the foundation of the always-on behavior.

The Context File (GEMINI.md)

The GEMINI.md file is intentionally short — it acts as a layer that imports the full skill definition using an @ reference. Here is the complete file:

# i-have-adhd

Shape every response for a reader with ADHD. Follow the rules imported below in full: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible, and cut all preamble and closers.

@./skills/i-have-adhd/SKILL.md

The @./skills/i-have-adhd/SKILL.md line is the key: it imports the canonical skill prompt (the 10 response rules) into the current context. Because GEMINI.md is loaded automatically, the imported rules are appended to the system prompt as soon as the extension loads.

Two Ways to Use the Skill with Gemini

According to the [repository’s INSTALL.md](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), users have two paths:

• Opt-in custom command — requires the user to manually invoke the skill each time.
• Always-on extension — the topic of this article; installs automatically via the manifest and loads GEMINI.md on every session.

The extension path is "always-on" because the manifest guarantees that Gemini imports GEMINI.md before any user input, making the skill permanently active.

Installation and Verification

Installing the Extension (one-time step)

# Clone the repository (if not already)

git clone https://github.com/ayghri/i-have-adhd.git
cd i-have-adhd

# Install the Gemini extension (creates a link in ~/.gemini)

gemini plugin install ./gemini-extension.json

Inspecting the Injected Context (debugging)

# Show the context that Gemini will prepend

gemini plugin show-context i-have-adhd

The output displays the contents of GEMINI.md, which includes the imported SKILL.md — confirming that the skill is active in your session.

Key Files

File	Role	Link
GEMINI.md	Wrapper that imports the ADHD skill; loaded as persistent context.	GEMINI.md
gemini-extension.json	Extension manifest; points Gemini to GEMINI.md for always-on loading.	gemini-extension.json
skills/i-have-adhd/SKILL.md	The canonical ADHD skill containing the 10 response rules.	SKILL.md
INSTALL.md	Documentation describing the two Gemini integration routes (custom command vs. always-on extension).	INSTALL.md

Summary

• The Gemini CLI extension achieves always-on behavior by referencing GEMINI.md in gemini-extension.json as the persistent context file.
• GEMINI.md is a concise wrapper that imports the full skill prompt from skills/i-have-adhd/SKILL.md via an @ directive.
• Because the manifest loads this file before every user interaction, the skill is active from session zero, with no manual invocation.
• The two integration routes (custom command vs. extension) are clearly documented in INSTALL.md, with the extension being the preferred path for hands-off operation.

Frequently Asked Questions

Does the Gemini extension modify the system prompt permanently?

No. The extension only prepends GEMINI.md to the context used in your current session. It does not alter any system files or change your Gemini defaults globally — it only affects sessions where the extension is active.

Can I use the skill without installing the extension?

Yes. As documented in INSTALL.md, you can also use a custom command approach, where you explicitly invoke the skill. However, that requires an extra step each time. The extension is the "always-on" alternative that removes that manual work.

How long does the installed extension stay active?

The extension stays active as long as the link in ~/.gemini exists and the context file is accessible. Removing the link or the repository will disable the always-on behavior. You can re-install it at any time with the same install command.

Why does GEMINI.md only contain a single line of instructions and then @ import?

That's intentional. The GEMINI.md file acts as a wrapper — it keeps the version of the canonical rules in one place (skills/i-have-adhd/SKILL.md) so you can update the rules without changing the extension manifest. The import directive makes the full prompt available immediately without duplicating content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}