Overview

The gk convert command bridges different AI provider ecosystems by translating agent definitions, skills, and configurations between formats. Whether you're migrating from Claude Code to GemKit, experimenting with dual-provider setups, or sharing agents across teams using different tools, this command handles the format translation automatically while preserving agent personality, instructions, and capabilities.

Supported Conversions

Provider Matrix

Source Format	Target Format	Status	Notes
Claude agents (.claude/)	Gemini agents (.gemini/)	✅ Supported	Full translation
Claude skills	Gemini extensions	✅ Supported	Tool mapping included
Gemini agents	Claude agents	✅ Supported	Reverse conversion
Gemini extensions	Claude skills	✅ Supported	Reverse conversion
OpenAI Assistants	Gemini agents	🚧 Planned	Coming soon
Custom JSON	Gemini agents	🚧 Planned	Coming soon

Basic Usage

Convert Claude Agent to Gemini

bash

gk convert claude-agent <source-path> --output <destination-path>

Example:

bash

# Convert a single Claude agent
gk convert claude-agent .claude/agents/code-reviewer --output .gemini/agents/

# Result:
# .gemini/agents/code-reviewer/
#   ├── agent.md
#   └── config.json

What it translates:

Agent personality and role from Claude format to Gemini format
System instructions and constraints
Tool permissions and capabilities
Model configuration (maps to equivalent Gemini models)
Output format specifications

Convert Claude Skill to Gemini Extension

bash

gk convert claude-skill <source-path> --output <destination-path>

Example:

bash

# Convert a skill/extension
gk convert claude-skill .claude/extensions/research --output .gemini/extensions/

# Result:
# .gemini/extensions/research/
#   └── SKILL.md

Convert Gemini Agent to Claude

bash

gk convert gemini-agent <source-path> --output <destination-path>

Example:

bash

# Convert from Gemini to Claude format
gk convert gemini-agent .gemini/agents/tester --output .claude/agents/

# Result:
# .claude/agents/tester/
#   ├── CLAUDE.md
#   └── config.json

Options

--output / -o

Specify the destination directory for converted files.

bash

gk convert claude-agent ./claude/agents/reviewer --output ./.gemini/agents/

Default behavior: If not specified, creates output in current directory.

--overwrite / --force

Replace existing files at the destination without prompting.

bash

gk convert claude-agent .claude/agents/reviewer \
  --output .gemini/agents/ \
  --overwrite

Safety note: Use with caution. Without this flag, the command prompts for confirmation if files already exist.

--dry-run

Preview the conversion without writing any files.

bash

gk convert claude-agent .claude/agents/reviewer \
  --output .gemini/agents/ \
  --dry-run

Output:

Dry Run - No files will be written

Source: .claude/agents/reviewer/CLAUDE.md
Target: .gemini/agents/reviewer/agent.md

Changes to be made:
──────────────────────────────────────────
✓ Translate frontmatter format
✓ Convert system prompt structure
✓ Map Claude tools to Gemini tools
✓ Update model reference: claude-3-opus → gemini-2.5-pro
✓ Preserve agent personality and instructions

Files that would be created:
- .gemini/agents/reviewer/agent.md (2.1 KB)
- .gemini/agents/reviewer/config.json (456 bytes)

--map-model

Specify custom model mapping between providers.

bash

gk convert claude-agent .claude/agents/reviewer \
  --output .gemini/agents/ \
  --map-model "claude-3-opus=gemini-2.5-pro"

Default mappings:

Claude Model	Gemini Equivalent	Use Case
claude-3-haiku	gemini-2.0-flash	Fast, cost-effective
claude-3-sonnet	gemini-2.0-pro	Balanced performance
claude-3-opus	gemini-2.5-pro	Complex reasoning
claude-3.5-sonnet	gemini-2.0-pro	General use

--preserve-comments

Keep comment blocks from source format in converted files.

bash

gk convert claude-agent .claude/agents/reviewer \
  --output .gemini/agents/ \
  --preserve-comments

Useful for maintaining team documentation and context within agent definitions.

Practical Examples

Example 1: Complete Claude to Gemini Migration

bash

# Step 1: Backup your Claude configuration
cp -r .claude .claude.backup

# Step 2: Convert all agents
for agent in .claude/agents/*; do
  agent_name=$(basename "$agent")
  gk convert claude-agent "$agent" --output .gemini/agents/
  echo "✓ Converted $agent_name"
done

# Step 3: Convert all skills
for skill in .claude/extensions/*; do
  skill_name=$(basename "$skill")
  gk convert claude-skill "$skill" --output .gemini/extensions/
  echo "✓ Converted $skill_name"
done

# Step 4: Verify conversions
gk agent list

# Step 5: Test converted agents
gk agent spawn --agent code-reviewer --prompt "Review this code"

# Step 6: Remove old Claude directory (optional)
# rm -rf .claude

Example 2: Dual-Provider Setup (Claude + Gemini)

bash

# Convert Claude agents to Gemini format for comparison
gk convert claude-agent .claude/agents/researcher \
  --output .gemini/agents/

# Now you can use either provider:
gk agent spawn --cli gemini --agent researcher --prompt "Research AI"
gk agent spawn --cli claude --agent researcher --prompt "Research AI"

# Compare results and choose the best provider per task

bash

# Your team uses Claude, partner team uses Gemini
# Convert your Gemini agents for sharing
gk convert gemini-agent .gemini/agents/api-designer \
  --output ./shared/claude-agents/

# Send to partner team
tar -czf api-designer-agent.tar.gz ./shared/claude-agents/api-designer/

# Partner team extracts and uses with Claude CLI

Example 4: Safe Conversion with Verification

bash

# Preview conversion first
gk convert claude-agent .claude/agents/security-reviewer \
  --output .gemini/agents/ \
  --dry-run

# If preview looks good, perform actual conversion
gk convert claude-agent .claude/agents/security-reviewer \
  --output .gemini/agents/

# Test converted agent
gk agent info security-reviewer
gk agent spawn --agent security-reviewer --prompt "Review for vulnerabilities"

# Compare with original Claude agent behavior

Example 5: Custom Model Mapping for Cost Optimization

bash

# Map expensive Claude Opus to cheaper Gemini Pro
gk convert claude-agent .claude/agents/code-executor \
  --output .gemini/agents/ \
  --map-model "claude-3-opus=gemini-2.0-pro"

# Verify cost savings
gk tokens summary --model gemini-2.0-pro

Conversion Details

Agent Translation

Claude format (CLAUDE.md):

markdown

---
name: code-reviewer
model: claude-3-opus
---

# System

You are a code reviewer focused on quality and security.

# Instructions

- Review code for bugs and vulnerabilities
- Check for code style violations
- Suggest improvements

# Output Format

Provide reviews in markdown format with severity levels.

Converted Gemini format (agent.md):

markdown

---
name: code-reviewer
description: Code reviewer focused on quality and security
model: gemini-2.5-pro
---

# Role

You are a code reviewer focused on quality and security.

# Instructions

- Review code for bugs and vulnerabilities
- Check for code style violations
- Suggest improvements

# Output Format

Provide reviews in markdown format with severity levels.

Skill Translation

Claude skill format:

markdown

---
name: prisma-helper
description: Prisma ORM expertise
---

# Tools and Knowledge

## Database Schema Design
[content...]

## Query Optimization
[content...]

Converted Gemini extension format:

markdown

---
name: prisma-helper
description: Prisma ORM expertise
keywords: [prisma, database, orm, postgresql]
---

# Knowledge

## Database Schema Design
[content...]

## Query Optimization
[content...]

# Guidelines

[Converted from original instructions...]

Tool Mapping

GemKit automatically maps provider-specific tools:

Claude Tool	Gemini Tool	Notes
`read_file`	`Read`	File reading
`write_file`	`Write`	File writing
`edit_file`	`Edit`	File editing
`bash`	`Bash`	Command execution
`search`	`Grep`	Code search
`list_files`	`Glob`	File listing
`web_search`	`WebSearch`	Internet search

Advanced Usage

Batch Conversion Script

bash

#!/bin/bash
# batch-convert.sh - Convert all Claude agents and skills

echo "Starting batch conversion from Claude to Gemini..."

# Create output directories
mkdir -p .gemini/agents .gemini/extensions

# Convert agents
echo "Converting agents..."
for agent in .claude/agents/*/; do
  if [ -d "$agent" ]; then
    agent_name=$(basename "$agent")
    echo "  Converting agent: $agent_name"
    gk convert claude-agent "$agent" --output .gemini/agents/ --overwrite
  fi
done

# Convert skills/extensions
echo "Converting skills..."
for skill in .claude/extensions/*/; do
  if [ -d "$skill" ]; then
    skill_name=$(basename "$skill")
    echo "  Converting skill: $skill_name"
    gk convert claude-skill "$skill" --output .gemini/extensions/ --overwrite
  fi
done

echo "✓ Batch conversion complete!"
echo "Verify with: gk agent list"

Conversion Validation Script

bash

#!/bin/bash
# validate-conversion.sh - Test converted agents

echo "Validating converted agents..."

# List all converted agents
agents=$(gk agent list --json | jq -r '.[].name')

for agent in $agents; do
  echo "Testing agent: $agent"

  # Spawn with simple prompt
  gk agent spawn --agent "$agent" \
    --prompt "Introduce yourself briefly" \
    > "validation-$agent.log" 2>&1

  if [ $? -eq 0 ]; then
    echo "  ✓ $agent works correctly"
  else
    echo "  ✗ $agent failed, check validation-$agent.log"
  fi
done

echo "Validation complete!"

Migration Guide: Claude to GemKit

Full Migration Process

1. Preparation

bash

# Backup existing Claude configuration
cp -r .claude .claude.backup
tar -czf claude-backup-$(date +%Y%m%d).tar.gz .claude/

# Verify current Claude setup works
# (Test your agents before converting)

2. Conversion

bash

# Initialize GemKit structure
gk init

# Convert all components
gk convert claude-agent .claude/agents/ --output .gemini/agents/
gk convert claude-skill .claude/extensions/ --output .gemini/extensions/

3. Configuration Update

bash

# Update .gk.json with your preferences
gk config set defaultAgent code-executor
gk config set defaultModel gemini-2.0-flash

4. Testing

bash

# List converted agents
gk agent list

# Test each agent
gk agent spawn --agent researcher --prompt "Test prompt"
gk agent spawn --agent code-executor --prompt "Test prompt"
gk agent spawn --agent tester --prompt "Test prompt"

5. Workflow Migration

bash

# Convert Claude workflows to GemKit plans
gk new plan feature-development
# Manually edit to match your Claude workflow structure

6. Cleanup (Optional)

bash

# Once verified, optionally remove Claude directory
# Keep the backup!
rm -rf .claude/

Best Practices

Always backup first - Create copies before converting
Use dry-run - Preview conversions before committing
Test thoroughly - Verify converted agents work as expected
Customize models - Use --map-model for cost optimization
Version control - Commit conversions to track changes
Document mappings - Keep notes on custom configurations
Gradual migration - Convert and test one agent at a time

Troubleshooting

"Source agent not found"

Verify the source path exists
Check for correct directory structure (should contain CLAUDE.md or agent.md)

"Conversion failed: unsupported format"

Ensure source files use standard Claude or Gemini format
Check for syntax errors in source files
Use --preserve-comments if custom formatting exists

"Model mapping not found"

Specify custom mapping with --map-model
Check supported model list in documentation

"Converted agent behaves differently"

Review generated files manually
Some provider-specific features may not translate perfectly
Adjust prompt engineering for Gemini's style
Consider dual-provider testing to compare

gk new agent - Create new agents from scratch
gk agent - Manage and spawn agents
Claude CLI Integration - Using both providers
Creating Custom Agents - Agent development guide
Configuration Reference - Provider settings

Overview

Supported Conversions

Provider Matrix

Basic Usage

Convert Claude Agent to Gemini

Convert Claude Skill to Gemini Extension

Convert Gemini Agent to Claude

Options

--output / -o

--overwrite / --force

--dry-run

--map-model

--preserve-comments

Practical Examples

Example 1: Complete Claude to Gemini Migration

Example 2: Dual-Provider Setup (Claude + Gemini)

Example 3: Sharing Agents Across Teams

Example 4: Safe Conversion with Verification

Example 5: Custom Model Mapping for Cost Optimization

Conversion Details

Agent Translation

Skill Translation

Tool Mapping

Advanced Usage

Batch Conversion Script

Conversion Validation Script

Migration Guide: Claude to GemKit

Full Migration Process

Best Practices

Troubleshooting

Related Commands