93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
.
|
|
├── 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.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```toml
|
|
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.
|