/convert-to-gemini

Convert Claude Plugin to Gemini Extension

Convert a Claude Code plugin directory to a Gemini CLI extension.

Process

Step 1: Identify Plugin Directory

If no path argument provided, check if current directory is a Claude plugin by looking for .claude-plugin/plugin.json. If not found, prompt the user for the plugin path using AskUserQuestion.

Step 2: Analyze Plugin Structure

Read and analyze the Claude plugin:

1. Read manifest: .claude-plugin/plugin.json
2. Find commands: commands/*.md files
3. Find skills: skills/*/SKILL.md files
4. Find agents: agents/*.md files
5. Find hooks: hooks/hooks.json
6. Find MCP config: .mcp.json

Use Glob tool to discover all component files.

Step 3: Prompt for Output Location

Use AskUserQuestion to ask the user where to create the Gemini extension:

Question: "Where should I create the Gemini extension?"

Suggest these options:

• ../[plugin-name]-gemini/ (sibling directory)
• ./.gemini-extension/ (inside plugin)
• Custom path

Step 4: Create Gemini Extension Structure

Create the extension directory structure:

[output-path]/
├── gemini-extension.json
├── GEMINI.md
├── commands/
└── README.md

Step 5: Convert Components

5.1 Manifest Conversion

Transform plugin.json to gemini-extension.json:

{
  "name": "[from plugin.json name]",
  "version": "[from plugin.json version, or '1.0.0']"
}

Add mcpServers if .mcp.json exists. Transform path variables:

• ${CLAUDE_PLUGIN_ROOT} → ${extensionPath}

Add excludeTools if hooks contain tool restrictions.

5.2 Command Conversion

For each commands/*.md file:

1. Read the markdown file
2. Parse YAML frontmatter for: name, description, argument-hint
3. Extract body content (after frontmatter)
4. Create commands/[name].toml:

description = "[from frontmatter description]"
prompt = """
[body content, with modifications:]
- Remove tool usage instructions (e.g., "Use the Read tool to...")
- Replace file references with @{...} injection
- Replace bash commands with !{...} injection
- Add {{args}} where arguments are expected
"""

5.3 Skill Conversion

Consolidate all skills/*/SKILL.md files into a single GEMINI.md:

1. Read each SKILL.md file
2. Strip YAML frontmatter
3. Remove Claude-specific tool instructions
4. Combine into sections with headers

Format:

# [Extension Name] Context

## [Skill 1 Name]
[Content from skill 1]

## [Skill 2 Name]
[Content from skill 2]

5.4 Agent Conversion

Agents have no direct equivalent. For each agents/*.md:

1. Extract knowledge/instructions → Add to GEMINI.md
2. Extract actionable behavior → Create corresponding command in commands/
3. Document in README what was converted and any limitations

5.5 Hook Conversion

From hooks/hooks.json:

1. Extract tool blocking patterns → excludeTools array
2. Document non-convertible hooks in README
3. Suggest alternatives for complex validation

5.6 MCP Conversion

From .mcp.json:

1. Copy mcpServers config to gemini-extension.json
2. Transform all ${CLAUDE_PLUGIN_ROOT} to ${extensionPath}
3. Extract environment variables → Add to settings array if sensitive

Step 6: Create README

Generate a comprehensive README.md documenting:

1. Original Plugin: Name, version, description
2. Conversion Summary: What was converted
3. Component Mapping: Table of Claude → Gemini mappings
4. Manual Steps Required: Any manual configuration needed
5. Limitations: Features that couldn't be converted
6. Usage Instructions: How to install and use the extension

Step 7: Generate Conversion Report

Display a summary to the user:

## Conversion Complete

**Source**: [claude-plugin-path]
**Output**: [gemini-extension-path]

### Components Converted
- Manifest: ✓
- Commands: X of Y converted
- Skills: X merged into GEMINI.md
- Agents: X converted (with limitations)
- Hooks: X restrictions converted
- MCP: ✓ (or N/A)

### Manual Review Required
- [List any items needing attention]

### Next Steps
1. Review generated files
2. Test with: gemini extensions link [path]
3. Verify commands work as expected

Step 8: Trigger Validation

After conversion completes, the gemini-extension-validator agent will automatically validate the generated extension.

Conversion Rules Reference

Load the claude-gemini-mapping skill for detailed conversion patterns and handle edge cases according to its guidance.

Error Handling

• If plugin.json not found: Report error and exit
• If output directory exists: Ask user to confirm overwrite
• If conversion fails for a component: Log warning, continue with others
• Document all skipped/failed conversions in README