gh-jduncan-rva-skill-porter-skill-porter/skills/jduncan-rva__skill-porter

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 (whitelist) ↔ excludeTools (blacklist)
• 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

1. Detect: Analyze source to determine platform
2. Extract: Parse metadata, MCP config, documentation
3. Transform: Convert between platform formats
4. Generate: Create target platform files
5. 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:

1. Converts the skill/extension to target platform
2. Creates a new branch (skill-porter/add-dual-platform-support)
3. Commits changes with detailed commit message
4. Pushes to remote
5. 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:

1. Creates fork directory at specified location
2. Copies or clones the repository
3. Ensures both Claude and Gemini configurations exist
4. Sets up symlinks for Claude Code (if applicable)
5. 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