port-skill
Use when porting a skill, plugin, or slash command from one coding agent platform (Claude Code, Codex, Antigravity, or Gemini CLI) to all ot
Open source Open in the app JSON README (API)
About
Use when porting a skill, plugin, or slash command from one coding agent platform (Claude Code, Codex, Antigravity, or Gemini CLI) to all others. Given a path to a skill directory, generates the necessary files, updates the README with per-platform install instructions, and documents any platform gaps clearly.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- keithmackay
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-08-22T19:20:56Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
keithmackay/port-skill
README
# port-skill
## Description
Port any coding-agent skill to all supported platforms in one pass. Give it a skill directory written for Claude Code, Codex, Antigravity, or Gemini CLI and it generates the missing platform files in-place, updates the README with per-platform install instructions, and documents any features that can't be bridged. Native users of every platform get a first-class experience — no manual reformatting, no guesswork.
## Highlights
- **Four-platform output** — generates Codex manifests, Antigravity-compatible SKILL.md files, Gemini CLI extension files, and per-platform README sections from a single source skill
- **In-place editing** — modifies the target skill directory directly; no intermediate output directory
- **Gap documentation** — surfaces Claude Code-specific features (auto-triggers, plugin namespacing, subagent dispatch) that have no equivalent on other platforms, in both the ported files and the README
- **Legacy support** — detects old-style Claude Code slash command files (`.claude/commands/*.md`) and ports them as skills with a clear explanation
- **Reverse porting** — reads `.codex-plugin/plugin.json` or `gemini-extension.json` and reconstructs a Claude Code `SKILL.md` if the source is a Codex or Gemini CLI skill
- **Dry-run mode** — preview what files would be created and what gaps would be documented before writing anything
- **Self-checking validation** — re-reads all ported files after writing and verifies they meet each platform's requirements
- **Compatibility matrix** — every ported skill gets a README table showing which features work on which platform
## Installation
### From the mackayi marketplace (recommended)
```
/plugin marketplace add keithmackay/mackayi
/plugin install port-skill@mackayi
```
### Claude Code
```bash
cp -r /path/to/port-skill/ ~/.claude/skills/port-skill/
```
Or symlink (recommended for development):
```bash
ln -s /path/to/port-skill/ ~/.claude/skills/port-skill
```
Then invoke with: `/port-skill`
### Codex
Add an entry to your marketplace config:
**`~/.agents/plugins/marketplace.json`** (create if absent):
```json
{
"name": "personal",
"interface": { "displayName": "Personal Plugins" },
"plugins": [
{
"name": "port-skill",
"source": { "source": "local", "path": "/path/to/port-skill/" },
"policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
"category": "Productivity"
}
]
}
```
### Antigravity
**Global install** (all workspaces):
```bash
cp -r /path/to/port-skill/ ~/.gemini/antigravity/skills/port-skill/
```
**Workspace install** (current project only):
```bash
cp -r /path/to/port-skill/ .agents/skills/port-skill/
```
Skills are auto-discovered. You can also say "use the port-skill skill" to activate it explicitly.
### Gemini CLI
```bash
gemini extensions install https://github.com/keithmackay/port-skill
```
To update:
```bash
gemini extensions update port-skill
```
## Usage
```
/port-skill <path-to-skill-directory> [--dry-run]
```
Examples:
```
/port-skill ~/.claude/skills/git-release/
/port-skill ./my-plugins/code-reviewer/
/port-skill ~/.claude/commands/my-old-command.md
/port-skill ~/.claude/skills/my-skill/ --dry-run
```
The porter will:
1. Read the skill at the given path and detect its source platform
2. Generate the files needed for all other platforms (in-place)
3. Update the skill's `README.md` with per-platform install instructions and a compatibility matrix
4. Document any features that can't be ported in both the ported files and the README
5. Validate all ported files before reporting completion
Pass `--dry-run` to preview what would be created without writing any files.
## Validation
After writing all ported files, the porter re-reads each one and verifies it meets the target platform's requirements before reporting completion:
| Check | Platforms |
|-------|-----------|
| `plugin.json` is valid JSON with required fields (`name`, `version`, `description`, `skills`) | Codex |
| `SKILL.md` has YAML frontmatter with `name` and `description` | Codex, Gemini CLI |
| Claude Code-specific frontmatter fields are stripped (`metadata`, `retrieval`, `tags`) | Antigravity, Gemini CLI |
| `gemini-extension.json` is valid JSON with required fields (`name`, `description`, `version`, `contextFileName`) | Gemini CLI |
| `GEMINI.md` contains at least one `@` include pointing to an existing file | Gemini CLI |
| README has `## Installation`, `## Compatibility`, and `## References` sections | All platforms |
Any validation failure is fixed before the run is declared complete.
## Compatibility
| Feature | Claude Code | Codex | Antigravity | Gemini CLI |
|---------|:-----------:|:-----:|:-----------:|:----------:|
| Core skill | ✅ | ✅ | ✅ | ✅ |
| Auto-trigger (`bashPatterns`) | ✅ | ❌ | ❌ | ❌ |
| Auto-trigger (`pathPatterns`) | ✅ | ❌ | ❌ | ❌ |
| Auto-trigger (`promptSignals`) | ✅ | ❌ | ❌ | ❌ |
| Sub-documents (`operations/`) | ✅ | ✅ | ✅ | ✅ |
| Scripts (`scripts/`) | ✅ | ✅ | ✅ | ✅ |
| Plugin namespacing (`plugin:skill`) | ✅ | ❌ | ❌ | ❌ |
| `retrieval.aliases` | ✅ | ❌ | ❌ | ❌ |
| `tags` field | ✅ | ❌ | ❌ | ❌ |
| Subagent dispatch | ✅ | ✅ | ✅ | ❌ |
| Legacy slash command input | ✅ | ✅ | ✅ | ✅ |
| Dry-run mode | ✅ | ✅ | ✅ | ✅ |
Legend: ✅ Supported · ❌ Not supported
## References
- **Claude Code Skills:** https://code.claude.com/docs/en/skills
- **Claude Code Complete Guide (PDF):** https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- **Codex Plugins:** https://developers.openai.com/codex/plugins/build
- **Antigravity Skills:** https://antigravity.google/docs/skills
- **Gemini CLI Extensions:** https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md
- **Agent Skills open standard:** https://agentskills.io/home
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for release history.
## License
[MIT](LICENSE)