Initial commit

2025-11-29 18:50:19 +08:00
commit d08086ebc7
41 changed files with 4892 additions and 0 deletions
--- a/skills/jduncan-rva__skill-porter/README.md
+++ b/skills/jduncan-rva__skill-porter/README.md
@@ -0,0 +1,312 @@
+# 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
+
+```bash
+npm install -g skill-porter
+```
+
+Or use directly with npx:
+
+```bash
+npx skill-porter convert ./my-skill --to gemini
+```
+
+## Quick Start
+
+### Convert Claude Skill to Gemini Extension
+
+```bash
+skill-porter convert ./my-claude-skill --to gemini --output ./my-gemini-extension
+```
+
+### Convert Gemini Extension to Claude Skill
+
+```bash
+skill-porter convert ./my-gemini-extension --to claude --output ./my-claude-skill
+```
+
+### Validate Conversion
+
+```bash
+skill-porter validate ./my-converted-skill
+```
+
+## Usage
+
+### As a CLI Tool
+
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+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):
+```bash
+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):
+```bash
+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!
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+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
+
+```bash
+# 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](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](https://modelcontextprotocol.io)
+- Inspired by the universal extension pattern demonstrated in [database-query-helper](https://github.com/jduncan-rva/database-query-helper)
+- Supports [Claude Code](https://code.claude.com) and [Gemini CLI](https://geminicli.com)
+
+## 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