gh-jduncan-rva-skill-porter/examples

Skill Porter - Examples

This directory contains example skills and extensions showing conversion between Claude Code and Gemini CLI formats.

Examples Included

1. Simple Claude Skill: code-formatter

Source: simple-claude-skill/ Type: Claude Code Skill Features: File formatting using Prettier and ESLint

Files:

• SKILL.md - Skill definition with YAML frontmatter
• .claude-plugin/marketplace.json - Claude marketplace configuration

Conversion:

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

Result: See before-after/code-formatter-converted/

• Generates gemini-extension.json
• Creates GEMINI.md context file
• Transforms MCP server config with ${extensionPath}
• Converts allowed-tools to excludeTools
• Infers settings from environment variables

---

2. Gemini Extension: api-connector

Source: api-connector-gemini/ Type: Gemini CLI Extension Features: REST API client with authentication

Files:

• gemini-extension.json - Gemini manifest with settings
• GEMINI.md - Context file with documentation

Conversion:

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

Result: See before-after/api-connector-converted/

• Generates SKILL.md with YAML frontmatter
• Creates .claude-plugin/marketplace.json
• Converts settings to environment variable docs
• Transforms excludeTools to allowed-tools
• Removes ${extensionPath} variables

---

Before/After Comparisons

Code Formatter (Claude → Gemini)

Before (Claude):

---
name: code-formatter
description: Formats code files using prettier and eslint
allowed-tools:
  - Read
  - Write
  - Bash
---

After (Gemini):

{
  "name": "code-formatter",
  "version": "1.0.0",
  "description": "Formats code files using prettier and eslint",
  "excludeTools": ["Edit", "Glob", "Grep", "Task", ...]
}

Key Transformations:

• ✅ YAML frontmatter → JSON manifest
• ✅ Whitelist (allowed-tools) → Blacklist (excludeTools)
• ✅ MCP paths: mcp-server/index.js → ${extensionPath}/mcp-server/index.js
• ✅ Environment variables → Settings schema

---

API Connector (Gemini → Claude)

Before (Gemini):

{
  "name": "api-connector",
  "version": "2.1.0",
  "settings": [
    {
      "name": "API_KEY",
      "secret": true,
      "required": true
    }
  ],
  "excludeTools": ["Bash", "Edit", "Write"]
}

After (Claude):

---
name: api-connector
description: Connect to REST APIs...
allowed-tools:
  - Read
  - Glob
  - Grep
  - Task
  - WebFetch
  - WebSearch
  # (all tools except Bash, Edit, Write)
---

## Configuration
- `API_KEY`: API authentication key **(required)**

Key Transformations:

• ✅ JSON manifest → YAML frontmatter
• ✅ Blacklist (excludeTools) → Whitelist (allowed-tools)
• ✅ Settings schema → Environment variable documentation
• ✅ MCP paths: ${extensionPath}/... → relative paths

---

Running the Examples

Test Conversion

# Analyze an example
skill-porter analyze examples/simple-claude-skill

# Convert Claude → Gemini
skill-porter convert examples/simple-claude-skill --to gemini

# Convert Gemini → Claude
skill-porter convert examples/api-connector-gemini --to claude

# Validate converted output
skill-porter validate examples/before-after/code-formatter-converted --platform gemini

Install Examples

Claude Code:

cp -r examples/simple-claude-skill ~/.claude/skills/code-formatter

Gemini CLI:

gemini extensions install examples/api-connector-gemini

---

Understanding the Conversions

Tool Restrictions

Claude uses a whitelist approach:

• Only listed tools are allowed
• Explicit permission model
• Field: allowed-tools (array)

Gemini uses a blacklist approach:

• All tools allowed except listed ones
• Exclusion model
• Field: excludeTools (array)

Conversion Logic:

• Claude → Gemini: Calculate excluded tools (all tools - allowed)
• Gemini → Claude: Calculate allowed tools (all tools - excluded)

Configuration Patterns

Claude: Environment variables

{
  "env": {
    "API_KEY": "${API_KEY}",
    "API_URL": "${API_URL}"
  }
}

Gemini: Settings schema

{
  "settings": [
    {
      "name": "API_KEY",
      "description": "API key",
      "secret": true,
      "required": true
    },
    {
      "name": "API_URL",
      "description": "API endpoint",
      "default": "https://api.example.com"
    }
  ]
}

MCP Server Paths

Claude: Relative paths

{
  "args": ["mcp-server/index.js"]
}

Gemini: Variable substitution

{
  "args": ["${extensionPath}/mcp-server/index.js"]
}

---

Tips for Creating Universal Skills

1. Start with shared functionality: Put logic in MCP server
2. Use environment variables: Both platforms support them
3. Document thoroughly: Both platforms load context files
4. Test on both platforms: Use skill-porter to validate
5. Keep it simple: Complex restrictions may need manual review

---

Additional Resources

• Claude Code Skills Documentation
• Gemini CLI Extensions
• Model Context Protocol
• skill-porter Repository