Initial commit

skills/jduncan-rva__skill-porter/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)