Skill Porter

Universal tool to convert Claude Code skills to Gemini CLI extensions and vice versa.

Overview

Skill Porter automates the conversion between Claude Code skills and Gemini CLI extensions, enabling developers to write once and deploy to both platforms with minimal effort.

Key Features

Bidirectional Conversion: Claude → Gemini and Gemini → Claude
Smart Analysis: Automatically detects source platform and structure
Metadata Transformation: YAML frontmatter ↔ JSON manifest conversion
MCP Integration: Preserves Model Context Protocol server configurations
Configuration Mapping: Converts between environment variables and settings schemas
Tool Restriction Conversion: Transforms allowed-tools (allowlist) ↔ excludeTools (denylist)
Validation: Ensures output meets platform requirements
Optional Features: PR generation, fork setup, migration tools

Installation

npm install -g skill-porter

Or use directly with npx:

npx skill-porter convert ./my-skill --to gemini

Quick Start

Convert Claude Skill to Gemini Extension

skill-porter convert ./my-claude-skill --to gemini --output ./my-gemini-extension

Convert Gemini Extension to Claude Skill

skill-porter convert ./my-gemini-extension --to claude --output ./my-claude-skill

Validate Conversion

skill-porter validate ./my-converted-skill

Usage

As a CLI Tool

# Basic conversion
skill-porter convert <source-path> --to <claude|gemini>

# With output directory
skill-porter convert ./source --to gemini --output ./destination

# Analyze without converting
skill-porter analyze ./skill-or-extension

# Validate existing skill/extension
skill-porter validate ./path

# Make universal (works on both platforms)
skill-porter universal ./my-skill

# Create PR to add dual-platform support
skill-porter create-pr ./my-skill --to gemini

# Fork with dual-platform setup
skill-porter fork ./my-skill --location ~/my-forks/skill-name

As a Universal Skill/Extension

skill-porter itself works on both platforms!

Claude Code:

# Install as skill
git clone https://github.com/jduncan-rva/skill-porter ~/.claude/skills/skill-porter
cd ~/.claude/skills/skill-porter
npm install

Then in Claude Code:

"Convert my skill at ./my-skill to Gemini extension"
"Make this Claude skill compatible with Gemini CLI"

Gemini CLI:

gemini extensions install https://github.com/jduncan-rva/skill-porter

Then in Gemini:

"Port this skill to work with Claude Code"
"Create a universal version of this extension"

Architecture

Skill Porter leverages the fact that both platforms use the Model Context Protocol (MCP), achieving ~85% code reuse:

Shared Components (85%):
├── MCP Server (100% reusable)
├── Documentation (85% reusable)
├── Scripts & Dependencies (100% reusable)

Platform-Specific (15%):
├── Claude: SKILL.md + .claude-plugin/marketplace.json
└── Gemini: GEMINI.md + gemini-extension.json

Conversion Process

Detect: Analyze source to determine platform
Extract: Parse metadata, MCP config, documentation
Transform: Convert between platform formats
Generate: Create target platform files
Validate: Ensure output meets requirements

Platform Mapping

Claude Code	Gemini CLI	Transformation
`SKILL.md` frontmatter	`gemini-extension.json`	YAML → JSON
`allowed-tools` (whitelist)	`excludeTools` (blacklist)	Logic inversion
`.claude-plugin/marketplace.json`	`gemini-extension.json`	JSON merge
Environment variables	`settings[]` schema	Inference
`SKILL.md` content	`GEMINI.md`	Content adaptation

Examples

See the examples/ directory for complete working examples with before/after comparisons.

Example 1: Code Formatter (Claude → Gemini)

Before (Claude skill):

SKILL.md with YAML frontmatter
Allowed tools: Read, Write, Bash
MCP server with environment variables

After (Gemini extension):

skill-porter convert examples/simple-claude-skill --to gemini

gemini-extension.json with manifest
Excluded tools: All except Read, Write, Bash
Settings schema inferred from env vars
MCP paths use ${extensionPath}

Example 2: API Connector (Gemini → Claude)

Before (Gemini extension):

gemini-extension.json with settings
Excluded tools: Bash, Edit, Write
Secret settings for API keys

After (Claude skill):

skill-porter convert examples/api-connector-gemini --to claude

SKILL.md with YAML frontmatter
Allowed tools: All except Bash, Edit, Write
Environment variable documentation generated
.claude-plugin/marketplace.json created

Example 3: Universal Conversion

skill-porter itself is universal - it converted itself!

cd skill-porter
skill-porter analyze .
# Result: Platform: universal (high confidence)

See examples/README.md for detailed before/after comparisons and conversion explanations.

Optional Features

Generate Pull Request

Automatically create a PR to add dual-platform support to a repository:

# Convert and create PR in one step
skill-porter create-pr ./my-skill --to gemini

# Options
skill-porter create-pr ./my-skill \
  --to gemini \
  --base main \
  --remote origin \
  --draft  # Create as draft PR

What it does:

Converts the skill/extension to target platform
Creates a new branch (skill-porter/add-dual-platform-support)
Commits changes with detailed commit message
Pushes to remote
Creates PR with comprehensive description

Requirements:

GitHub CLI (gh) installed and authenticated
Git repository with remote configured

PR includes:

✅ Complete description of changes
✅ Benefits explanation
✅ Testing checklist
✅ Installation instructions for both platforms
✅ Link to skill-porter documentation

Fork and Setup

Create a fork with dual-platform configuration ready for development:

skill-porter fork ./my-skill --location ~/my-forks/skill-name

What it does:

Creates fork directory at specified location
Copies or clones the repository
Ensures both Claude and Gemini configurations exist
Sets up symlinks for Claude Code (if applicable)
Provides installation instructions for Gemini CLI

Use cases:

Maintain separate development fork
Test on both platforms simultaneously
Contribute dual-platform support to external repos

Development

# Clone repository
git clone https://github.com/jduncan-rva/skill-porter
cd skill-porter

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Project Structure

skill-porter/
├── src/
│   ├── index.js              # Main entry point
│   ├── cli.js                # CLI interface
│   ├── analyzers/
│   │   ├── detector.js       # Platform detection
│   │   └── validator.js      # Output validation
│   ├── converters/
│   │   ├── claude-to-gemini.js
│   │   ├── gemini-to-claude.js
│   │   └── shared.js         # Shared conversion logic
│   ├── templates/
│   │   ├── skill.template.md
│   │   ├── gemini.template.md
│   │   └── manifests.js      # Manifest templates
│   └── utils/
│       ├── file-utils.js
│       ├── metadata-parser.js
│       └── mcp-transformer.js
├── tests/
├── examples/
├── SKILL.md                  # Claude Code skill interface
├── package.json
└── README.md

License

MIT

Acknowledgments

Built on the Model Context Protocol
Inspired by the universal extension pattern demonstrated in database-query-helper
Supports Claude Code and Gemini CLI

Support

Issues: https://github.com/jduncan-rva/skill-porter/issues
Discussions: https://github.com/jduncan-rva/skill-porter/discussions

Made with ❤️ for the Claude Code and Gemini CLI communities

api-connector