Initial commit

2025-11-29 18:50:16 +08:00
commit b38883ce98
39 changed files with 4530 additions and 0 deletions
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,248 @@
+# 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**:
+```bash
+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**:
+```bash
+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):
+```yaml
+---
+name: code-formatter
+description: Formats code files using prettier and eslint
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+```
+
+**After** (Gemini):
+```json
+{
+  "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):
+```json
+{
+  "name": "api-connector",
+  "version": "2.1.0",
+  "settings": [
+    {
+      "name": "API_KEY",
+      "secret": true,
+      "required": true
+    }
+  ],
+  "excludeTools": ["Bash", "Edit", "Write"]
+}
+```
+
+**After** (Claude):
+```yaml
+---
+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
+
+```bash
+# 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**:
+```bash
+cp -r examples/simple-claude-skill ~/.claude/skills/code-formatter
+```
+
+**Gemini CLI**:
+```bash
+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
+```json
+{
+  "env": {
+    "API_KEY": "${API_KEY}",
+    "API_URL": "${API_URL}"
+  }
+}
+```
+
+**Gemini**: Settings schema
+```json
+{
+  "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
+```json
+{
+  "args": ["mcp-server/index.js"]
+}
+```
+
+**Gemini**: Variable substitution
+```json
+{
+  "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](https://docs.claude.com/en/docs/claude-code/skills)
+- [Gemini CLI Extensions](https://geminicli.com/docs/extensions/)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [skill-porter Repository](https://github.com/jduncan-rva/skill-porter)
--- a/examples/api-connector-gemini/GEMINI.md
+++ b/examples/api-connector-gemini/GEMINI.md
@@ -0,0 +1,37 @@
+# API Connector - Gemini CLI Extension
+
+Connect to REST APIs, manage authentication, and process responses.
+
+## Features
+
+- Make GET, POST, PUT, DELETE requests
+- Automatic authentication header management
+- JSON response parsing
+- Rate limiting and retry logic
+- Response caching
+
+## Configuration
+
+**Required:**
+- `API_KEY`: Your API authentication key
+
+**Optional:**
+- `API_BASE_URL`: Base URL (default: https://api.example.com)
+- `API_TIMEOUT`: Timeout in ms (default: 30000)
+
+## Usage
+
+```
+"Get data from /users endpoint"
+"POST this JSON to /api/create"
+"Check the API status"
+```
+
+## Safety
+
+This extension operates in read-only mode:
+- Cannot execute bash commands
+- Cannot edit local files
+- Cannot write files to disk
+
+Only makes HTTP requests to configured API endpoints.
--- a/examples/api-connector-gemini/gemini-extension.json
+++ b/examples/api-connector-gemini/gemini-extension.json
@@ -0,0 +1,40 @@
+{
+  "name": "api-connector",
+  "version": "2.1.0",
+  "description": "Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.",
+  "contextFileName": "GEMINI.md",
+  "settings": [
+    {
+      "name": "API_BASE_URL",
+      "description": "Base URL for API requests",
+      "default": "https://api.example.com"
+    },
+    {
+      "name": "API_KEY",
+      "description": "API authentication key",
+      "secret": true,
+      "required": true
+    },
+    {
+      "name": "API_TIMEOUT",
+      "description": "Request timeout in milliseconds",
+      "default": "30000"
+    }
+  ],
+  "mcpServers": {
+    "api-client": {
+      "command": "node",
+      "args": ["${extensionPath}/mcp-server/api-client.js"],
+      "env": {
+        "API_BASE_URL": "${API_BASE_URL}",
+        "API_KEY": "${API_KEY}",
+        "API_TIMEOUT": "${API_TIMEOUT}"
+      }
+    }
+  },
+  "excludeTools": [
+    "Bash",
+    "Edit",
+    "Write"
+  ]
+}
--- a/examples/before-after/api-connector-converted/.claude-plugin/marketplace.json
+++ b/examples/before-after/api-connector-converted/.claude-plugin/marketplace.json
@@ -0,0 +1,50 @@
+{
+  "name": "api-connector-marketplace",
+  "owner": {
+    "name": "Skill Porter User",
+    "email": "user@example.com"
+  },
+  "metadata": {
+    "description": "Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.",
+    "version": "2.1.0"
+  },
+  "plugins": [
+    {
+      "name": "api-connector",
+      "description": "Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.",
+      "source": ".",
+      "strict": false,
+      "author": "Converted from Gemini",
+      "repository": {
+        "type": "git",
+        "url": "https://github.com/user/api-connector"
+      },
+      "license": "MIT",
+      "keywords": [
+        "connect",
+        "rest",
+        "apis,",
+        "manage",
+        "authentication,"
+      ],
+      "category": "general",
+      "tags": [],
+      "skills": [
+        "."
+      ],
+      "mcpServers": {
+        "api-client": {
+          "command": "node",
+          "args": [
+            "mcp-server/api-client.js"
+          ],
+          "env": {
+            "API_BASE_URL": "${API_BASE_URL}",
+            "API_KEY": "${API_KEY}",
+            "API_TIMEOUT": "${API_TIMEOUT}"
+          }
+        }
+      }
+    }
+  ]
+}
--- a/examples/before-after/api-connector-converted/GEMINI.md
+++ b/examples/before-after/api-connector-converted/GEMINI.md
@@ -0,0 +1,37 @@
+# API Connector - Gemini CLI Extension
+
+Connect to REST APIs, manage authentication, and process responses.
+
+## Features
+
+- Make GET, POST, PUT, DELETE requests
+- Automatic authentication header management
+- JSON response parsing
+- Rate limiting and retry logic
+- Response caching
+
+## Configuration
+
+**Required:**
+- `API_KEY`: Your API authentication key
+
+**Optional:**
+- `API_BASE_URL`: Base URL (default: https://api.example.com)
+- `API_TIMEOUT`: Timeout in ms (default: 30000)
+
+## Usage
+
+```
+"Get data from /users endpoint"
+"POST this JSON to /api/create"
+"Check the API status"
+```
+
+## Safety
+
+This extension operates in read-only mode:
+- Cannot execute bash commands
+- Cannot edit local files
+- Cannot write files to disk
+
+Only makes HTTP requests to configured API endpoints.
--- a/examples/before-after/api-connector-converted/SKILL.md
+++ b/examples/before-after/api-connector-converted/SKILL.md
@@ -0,0 +1,72 @@
+---
+name: api-connector
+description: Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - WebSearch
+  - TodoWrite
+  - AskUserQuestion
+  - SlashCommand
+  - Skill
+  - NotebookEdit
+  - BashOutput
+  - KillShell
+---
+
+# api-connector - Claude Code Skill
+
+Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.
+
+## Configuration
+
+This skill requires the following environment variables:
+
+- `API_BASE_URL`: Base URL for API requests (default: https://api.example.com)
+- `API_KEY`: API authentication key **(required)**
+- `API_TIMEOUT`: Request timeout in milliseconds (default: 30000)
+
+Set these in your environment or Claude Code configuration.
+
+Connect to REST APIs, manage authentication, and process responses.
+
+## Features
+
+- Make GET, POST, PUT, DELETE requests
+- Automatic authentication header management
+- JSON response parsing
+- Rate limiting and retry logic
+- Response caching
+
+## Configuration
+
+**Required:**
+- `API_KEY`: Your API authentication key
+
+**Optional:**
+- `API_BASE_URL`: Base URL (default: https://api.example.com)
+- `API_TIMEOUT`: Timeout in ms (default: 30000)
+
+## Usage
+
+```
+"Get data from /users endpoint"
+"POST this JSON to /api/create"
+"Check the API status"
+```
+
+## Safety
+
+This extension operates in read-only mode:
+- Cannot execute bash commands
+- Cannot edit local files
+- Cannot write files to disk
+
+Only makes HTTP requests to configured API endpoints.
+
+---
+
+*This skill was converted from a Gemini CLI extension using [skill-porter](https://github.com/jduncan-rva/skill-porter)*
--- a/examples/before-after/api-connector-converted/gemini-extension.json
+++ b/examples/before-after/api-connector-converted/gemini-extension.json
@@ -0,0 +1,40 @@
+{
+  "name": "api-connector",
+  "version": "2.1.0",
+  "description": "Connect to REST APIs, manage authentication, and process responses. Use for API integration tasks.",
+  "contextFileName": "GEMINI.md",
+  "settings": [
+    {
+      "name": "API_BASE_URL",
+      "description": "Base URL for API requests",
+      "default": "https://api.example.com"
+    },
+    {
+      "name": "API_KEY",
+      "description": "API authentication key",
+      "secret": true,
+      "required": true
+    },
+    {
+      "name": "API_TIMEOUT",
+      "description": "Request timeout in milliseconds",
+      "default": "30000"
+    }
+  ],
+  "mcpServers": {
+    "api-client": {
+      "command": "node",
+      "args": ["${extensionPath}/mcp-server/api-client.js"],
+      "env": {
+        "API_BASE_URL": "${API_BASE_URL}",
+        "API_KEY": "${API_KEY}",
+        "API_TIMEOUT": "${API_TIMEOUT}"
+      }
+    }
+  },
+  "excludeTools": [
+    "Bash",
+    "Edit",
+    "Write"
+  ]
+}
--- a/examples/before-after/api-connector-converted/shared/examples.md
+++ b/examples/before-after/api-connector-converted/shared/examples.md
@@ -0,0 +1,3 @@
+# Usage Examples
+
+Comprehensive usage examples and tutorials.
--- a/examples/before-after/api-connector-converted/shared/reference.md
+++ b/examples/before-after/api-connector-converted/shared/reference.md
@@ -0,0 +1,3 @@
+# Technical Reference
+
+Detailed API documentation and technical reference.
--- a/examples/before-after/code-formatter-converted/.claude-plugin/marketplace.json
+++ b/examples/before-after/code-formatter-converted/.claude-plugin/marketplace.json
@@ -0,0 +1,35 @@
+{
+  "name": "code-formatter-marketplace",
+  "owner": {
+    "name": "Example Developer",
+    "email": "dev@example.com"
+  },
+  "metadata": {
+    "description": "Formats code files using prettier and eslint",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "description": "Formats code files using prettier and eslint. Use when the user wants to format code.",
+      "source": ".",
+      "strict": false,
+      "author": "Example Developer",
+      "license": "MIT",
+      "keywords": ["formatting", "prettier", "eslint", "code-quality"],
+      "category": "development",
+      "tags": ["formatting", "tools"],
+      "skills": ["."],
+      "mcpServers": {
+        "formatter-tools": {
+          "command": "node",
+          "args": ["mcp-server/index.js"],
+          "env": {
+            "PRETTIER_CONFIG": "${PRETTIER_CONFIG}",
+            "ESLINT_CONFIG": "${ESLINT_CONFIG}"
+          }
+        }
+      }
+    }
+  ]
+}
--- a/examples/before-after/code-formatter-converted/GEMINI.md
+++ b/examples/before-after/code-formatter-converted/GEMINI.md
@@ -0,0 +1,47 @@
+# code-formatter - Gemini CLI Extension
+
+Formats code files using prettier and eslint. Use when the user wants to format code, fix linting issues, or clean up code style.
+
+## Quick Start
+
+After installation, you can use this extension by asking questions or giving commands naturally.
+
+
+# Code Formatter Skill
+
+Automatically formats code files using industry-standard tools.
+
+## Capabilities
+
+- Format JavaScript/TypeScript with Prettier
+- Fix ESLint issues automatically
+- Format JSON, YAML, and Markdown files
+- Run format checks before commits
+
+## Usage Examples
+
+**Format a single file:**
+```
+"Format the src/index.js file"
+```
+
+**Format entire directory:**
+```
+"Format all files in the src/ directory"
+```
+
+**Check formatting without changes:**
+```
+"Check if files in src/ are properly formatted"
+```
+
+## Configuration
+
+Set these environment variables for custom configuration:
+- `PRETTIER_CONFIG`: Path to prettier config (default: .prettierrc)
+- `ESLINT_CONFIG`: Path to eslint config (default: .eslintrc.js)
+
+
+---
+
+*This extension was converted from a Claude Code skill using [skill-porter](https://github.com/jduncan-rva/skill-porter)*
--- a/examples/before-after/code-formatter-converted/SKILL.md
+++ b/examples/before-after/code-formatter-converted/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: code-formatter
+description: Formats code files using prettier and eslint. Use when the user wants to format code, fix linting issues, or clean up code style.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Code Formatter Skill
+
+Automatically formats code files using industry-standard tools.
+
+## Capabilities
+
+- Format JavaScript/TypeScript with Prettier
+- Fix ESLint issues automatically
+- Format JSON, YAML, and Markdown files
+- Run format checks before commits
+
+## Usage Examples
+
+**Format a single file:**
+```
+"Format the src/index.js file"
+```
+
+**Format entire directory:**
+```
+"Format all files in the src/ directory"
+```
+
+**Check formatting without changes:**
+```
+"Check if files in src/ are properly formatted"
+```
+
+## Configuration
+
+Set these environment variables for custom configuration:
+- `PRETTIER_CONFIG`: Path to prettier config (default: .prettierrc)
+- `ESLINT_CONFIG`: Path to eslint config (default: .eslintrc.js)
--- a/examples/before-after/code-formatter-converted/gemini-extension.json
+++ b/examples/before-after/code-formatter-converted/gemini-extension.json
@@ -0,0 +1,43 @@
+{
+  "name": "code-formatter",
+  "version": "1.0.0",
+  "description": "Formats code files using prettier and eslint. Use when the user wants to format code, fix linting issues, or clean up code style.",
+  "contextFileName": "GEMINI.md",
+  "mcpServers": {
+    "formatter-tools": {
+      "command": "node",
+      "args": [
+        "${extensionPath}/mcp-server/index.js"
+      ],
+      "env": {
+        "PRETTIER_CONFIG": "${PRETTIER_CONFIG}",
+        "ESLINT_CONFIG": "${ESLINT_CONFIG}"
+      }
+    }
+  },
+  "excludeTools": [
+    "Edit",
+    "Glob",
+    "Grep",
+    "Task",
+    "WebFetch",
+    "WebSearch",
+    "TodoWrite",
+    "AskUserQuestion",
+    "SlashCommand",
+    "Skill",
+    "NotebookEdit",
+    "BashOutput",
+    "KillShell"
+  ],
+  "settings": [
+    {
+      "name": "PRETTIER_CONFIG",
+      "description": "Prettier Config"
+    },
+    {
+      "name": "ESLINT_CONFIG",
+      "description": "Eslint Config"
+    }
+  ]
+}
--- a/examples/before-after/code-formatter-converted/shared/examples.md
+++ b/examples/before-after/code-formatter-converted/shared/examples.md
@@ -0,0 +1,3 @@
+# Usage Examples
+
+Comprehensive usage examples and tutorials.
--- a/examples/before-after/code-formatter-converted/shared/reference.md
+++ b/examples/before-after/code-formatter-converted/shared/reference.md
@@ -0,0 +1,3 @@
+# Technical Reference
+
+Detailed API documentation and technical reference.
--- a/examples/simple-claude-skill/.claude-plugin/marketplace.json
+++ b/examples/simple-claude-skill/.claude-plugin/marketplace.json
@@ -0,0 +1,35 @@
+{
+  "name": "code-formatter-marketplace",
+  "owner": {
+    "name": "Example Developer",
+    "email": "dev@example.com"
+  },
+  "metadata": {
+    "description": "Formats code files using prettier and eslint",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "description": "Formats code files using prettier and eslint. Use when the user wants to format code.",
+      "source": ".",
+      "strict": false,
+      "author": "Example Developer",
+      "license": "MIT",
+      "keywords": ["formatting", "prettier", "eslint", "code-quality"],
+      "category": "development",
+      "tags": ["formatting", "tools"],
+      "skills": ["."],
+      "mcpServers": {
+        "formatter-tools": {
+          "command": "node",
+          "args": ["mcp-server/index.js"],
+          "env": {
+            "PRETTIER_CONFIG": "${PRETTIER_CONFIG}",
+            "ESLINT_CONFIG": "${ESLINT_CONFIG}"
+          }
+        }
+      }
+    }
+  ]
+}
--- a/examples/simple-claude-skill/SKILL.md
+++ b/examples/simple-claude-skill/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: code-formatter
+description: A simple example skill for demonstration purposes
+subagents:
+  - name: reviewer
+    description: You are a senior code reviewer.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# Code Formatter Skill
+
+Automatically formats code files using industry-standard tools.
+
+## Capabilities
+
+- Format JavaScript/TypeScript with Prettier
+- Fix ESLint issues automatically
+- Format JSON, YAML, and Markdown files
+- Run format checks before commits
+
+## Usage Examples
+
+**Format a single file:**
+```
+"Format the src/index.js file"
+```
+
+**Format entire directory:**
+```
+"Format all files in the src/ directory"
+```
+
+**Check formatting without changes:**
+```
+"Check if files in src/ are properly formatted"
+```
+
+## Configuration
+
+Set these environment variables for custom configuration:
+- `PRETTIER_CONFIG`: Path to prettier config (default: .prettierrc)
+- `ESLINT_CONFIG`: Path to eslint config (default: .eslintrc.js)