gh-jduncan-rva-skill-porter/templates/GEMINI_ARCH_GUIDE.md

Gemini CLI Extension Architecture Guide

This document serves as the "Source of Truth" for understanding, maintaining, and extending this Gemini CLI Extension.

1. Extension Structure

A valid Gemini CLI extension consists of the following core components:

.
├── gemini-extension.json  # Manifest file (Required)
├── GEMINI.md              # Context & Instructions (Required)
├── commands/              # Custom Slash Commands (Optional)
│   └── command.toml       # Command definition
├── docs/                  # Documentation (Recommended)
│   └── GEMINI_ARCHITECTURE.md # This file
└── mcp-server/            # (Optional) Model Context Protocol server

2. Manifest Schema (gemini-extension.json)

The gemini-extension.json file defines the extension's metadata, configuration, and tools.

{
  "name": "extension-name",
  "version": "1.0.0",
  "description": "Description of what the extension does.",
  "contextFileName": "GEMINI.md",
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${extensionPath}/mcp-server/index.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  },
  "settings": [
    {
      "name": "API_KEY",
      "description": "API Key for the service",
      "secret": true,
      "required": true
    }
  ],
  "excludeTools": ["Bash"] // Tools to blacklist (optional)
}

3. Custom Commands (commands/*.toml)

Custom commands provide interactive shortcuts (e.g., /deploy, /review) for users. They are defined in TOML files within the commands/ directory.

File Structure

Filename determines the command name:

• commands/review.toml -> /review
• commands/git/commit.toml -> /git:commit (Namespaced)

TOML Format

description = "Description of what this command does"

# The prompt sent to the model.
# {{args}} is replaced by the user's input text.
prompt = """
You are an expert code reviewer.
Review the following code focusing on security and performance:

{{args}}
"""

Best Practices

• Use {{args}}: Always include this placeholder to capture user input.
• Clear Description: Helps the user understand what the command does when listing commands.
• Prompt Engineering: Provide clear persona instructions and constraints within the prompt string.

4. Context Management (GEMINI.md)

The GEMINI.md file is injected into the LLM's context window for every interaction (not just specific commands).

• Keep it Concise: Token usage matters.
• Global Instructions: Use this for broad behavior rules (e.g., "Always speak like a pirate").
• Safety First: Explicitly state what the extension cannot do.

5. Maintenance

When modifying this extension:

1. Add Commands: Create new .toml files in commands/ for distinct tasks or agents.
2. Update Manifest: Edit gemini-extension.json if you change settings or MCP servers.
3. Update Context: Edit GEMINI.md for global behavioral changes.