pleaseai/migrating-gemini-extensions

Migrating a Gemini Extension to a Claude Code Plugin

Preserve functionality while adopting Claude Code best practices. Keep gemini-extension.json for backwards compatibility.

Phase 1 — Analysis

1. Read the existing structure: gemini-extension.json, any context file (e.g. GEMINI.md), commands, MCP servers/tools, custom scripts.
2. Map components: Gemini context → Claude skill (preferred) or commands/agents; Gemini tools → MCP servers; Gemini scripts → hook scripts.

Phase 2 — Structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json        # NEW: Claude manifest (source of truth)
├── gemini-extension.json  # KEEP: backwards compatibility
├── skills/                # NEW (preferred): convert context → a skill
├── commands/              # optional: convert context → commands
├── hooks/
│   ├── hooks.json         # if you keep SessionStart context loading
│   └── scripts/           # ADAPT: update paths to ${CLAUDE_PLUGIN_ROOT}
└── README.md              # UPDATE: add Claude install instructions

Phase 3 — Convert the manifest

gemini-extension.json → .claude-plugin/plugin.json:

{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Description",
  "author": { "name": "...", "url": "https://github.com/..." },
  "homepage": "...",
  "repository": "...",
  "license": "MIT",
  "keywords": ["..."]
}

Phase 4 — Migrate the context file (prefer a skill)

Preferred: turn GEMINI.md into a skills/<name>/SKILL.md with frontmatter describing when it should activate. This loads only when relevant instead of every session. See ../plugin-authoring/references/best-practices.md for why skills beat SessionStart hooks.

Legacy alternative — SessionStart hook (only if you must load context every session):

{
  "description": "Load usage instructions at session start",
  "hooks": {
    "SessionStart": [
      { "matcher": "startup",
        "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh", "timeout": 10 } ] }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail
CONTEXT_FILE="${CLAUDE_PLUGIN_ROOT}/hooks/CONTEXT.md"
if [ -f "$CONTEXT_FILE" ]; then
  jq -n --arg context "$(cat "$CONTEXT_FILE")" \
    '{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": $context } }'
fi

Then chmod +x hooks/context.sh.

Phase 5 — Migrate MCP servers

Gemini tools → inline mcpServers (or .mcp.json):

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@package/name"],
      "env": { "API_KEY": "${PLUGIN_API_KEY:-}" }
    }
  }
}

Key changes: ${CLAUDE_PLUGIN_ROOT} for local paths, ${VAR:-} for optional env vars, npx -y for npm packages.

Phase 6 — Update docs

Add a Claude Code install section to the README (marketplace add + /plugin install ...) and keep the Gemini CLI section for backwards compatibility.

Phase 7 — Test

• Claude Code: claude --debug, /plugin list, run the plugin's components.
• Gemini CLI still works: gemini ext list.
• Confirm commands, hooks, and MCP servers behave.

Checklist

• [ ] Create .claude-plugin/plugin.json; keep gemini-extension.json.
• [ ] Convert context to a skill (or SessionStart hook); make hook scripts executable.
• [ ] Update paths to ${CLAUDE_PLUGIN_ROOT}; migrate MCP config.
• [ ] Update README (both install methods); update CHANGELOG.
• [ ] Test with Claude Code and Gemini CLI. Submit an upstream PR for third-party extensions.

Common issues

• Context not loading → hook script not executable or bad JSON output.
• MCP server won't start → paths not using ${CLAUDE_PLUGIN_ROOT}, or command missing.
• Commands not appearing → commands/ nested in .claude-plugin/ instead of at root.

Reference

• docs/lessons-learned/context7.md — a complete migration example.
• Claude Code Plugin Documentation
• MCP Documentation