agent-skill-creator/references/cross-platform-guide.md

Cross-Platform Compatibility Guide

Version: 4.0 Purpose: Complete compatibility matrix for Agent Skills across all platforms supporting the Agent Skills Open Standard

---

Overview

Skills created by agent-skill-creator are compliant with the Agent Skills Open Standard and work across all platforms that support the SKILL.md format. As of v4.0, this includes 8+ major platforms.

Supported Platforms

Platform	Type	SKILL.md Location
Claude Code	CLI	~/.claude/skills/ or .claude/skills/
GitHub Copilot CLI	CLI	.github/skills/
VS Code Copilot	IDE Extension	.github/skills/
Cursor	IDE	.cursor/rules/
Windsurf	IDE	.windsurf/skills/
Cline	VS Code Extension	.clinerules/
OpenAI Codex CLI	CLI	.codex/skills/
Gemini CLI	CLI	.gemini/skills/
Claude Desktop	Desktop App	.zip upload
claude.ai	Web	.zip upload
Claude API	API	Programmatic upload

The Unifying Standard

All these platforms read the same SKILL.md format:

---
name: skill-name
description: What the skill does and when to activate it
license: MIT
metadata:
  author: Author Name
  version: 1.0.0
---
# Skill content here...

A skill created once works everywhere without modification.

---

Installation by Platform

Claude Code

# Using install.sh (recommended)
./install.sh

# Manual: User-level
cp -r skill-name/ ~/.claude/skills/skill-name/

# Manual: Project-level
cp -r skill-name/ .claude/skills/skill-name/

Best for: Developers, power users, teams with git workflows.

GitHub Copilot

# Using install.sh
./install.sh --platform copilot

# Manual: Project-level
cp -r skill-name/ .github/skills/skill-name/

Best for: GitHub-integrated workflows, VS Code users.

Cursor

# Using install.sh
./install.sh --platform cursor

# Manual
cp -r skill-name/ .cursor/rules/skill-name/

Best for: Cursor IDE users. Cursor reads SKILL.md natively alongside its .mdc rules.

Windsurf

# Using install.sh
./install.sh --platform windsurf

# Manual
cp -r skill-name/ .windsurf/skills/skill-name/

Best for: Windsurf IDE users.

Cline

# Using install.sh
./install.sh --platform cline

# Manual
cp -r skill-name/ .clinerules/skill-name/

Best for: Cline extension users in VS Code.

OpenAI Codex CLI

# Using install.sh
./install.sh --platform codex

# Manual
cp -r skill-name/ .codex/skills/skill-name/

Best for: Codex CLI users.

Gemini CLI

# Using install.sh
./install.sh --platform gemini

# Manual
cp -r skill-name/ .gemini/skills/skill-name/

Best for: Gemini CLI users.

Claude Desktop / claude.ai (Web)

These platforms use .zip upload instead of directory copying:

1. Export: python scripts/export_utils.py ./skill-name --variant desktop
2. Open Claude Desktop or claude.ai
3. Go to Settings > Skills > Upload skill
4. Select the .zip file

Claude API

import anthropic

client = anthropic.Anthropic()

with open('skill-name-api-v1.0.0.zip', 'rb') as f:
    skill = client.skills.create(file=f, name="skill-name")

response = client.messages.create(
    model="claude-sonnet-4",
    messages=[{"role": "user", "content": "Your query here"}],
    container={"type": "custom_skill", "skill_id": skill.id},
    betas=["code-execution-2025-08-25", "skills-2025-10-02"]
)

---

Compatibility Matrix

Core Functionality

Feature	CLI Platforms	Desktop/Web	Claude API
SKILL.md support	Full	Full	Full
Python scripts	Full	Full	Sandboxed*
References/docs	Full	Full	Full
Assets/templates	Full	Full	Full
install.sh	Full	N/A	N/A

* API: No network access, no pip install at runtime

Technical Specifications

Specification	CLI Platforms	Desktop/Web	Claude API
Max skill size	No limit	~10MB	8MB hard limit
Network access	Yes	Yes	No
Package install	Yes	Yes	No
File system	Full	Full	Limited
Updates	git pull	Re-upload	API upload

---

Platform-Specific Notes

marketplace.json

• Required by: Claude Code (for plugin marketplace distribution only)
• Not needed by: All other platforms
• Recommendation: For simple skills, do not include marketplace.json. Only add it for complex skill suites that need Claude Code plugin distribution.
• Format: If included, use ONLY official fields: name, plugins[].name, plugins[].description, plugins[].source, plugins[].skills

Skill Activation

All platforms that support the SKILL.md standard use the description field in frontmatter as the primary activation mechanism. The description should contain:

• Clear explanation of when to use the skill
• Domain-specific keywords
• Example trigger phrases

No platform-specific activation configuration is needed.

File Structure

The standard skill directory works on all platforms:

skill-name/
├── SKILL.md          # Required - primary skill definition
├── scripts/          # Optional - executable code
├── references/       # Optional - detailed documentation
├── assets/           # Optional - templates, schemas, data
├── install.sh        # Optional - cross-platform installer
└── README.md         # Recommended - install instructions

---

Migration Between Platforms

CLI Platform to CLI Platform

Skills are directly portable. Just copy the directory to the target platform's skill location:

# From Claude Code to Copilot
cp -r ~/.claude/skills/my-skill/ .github/skills/my-skill/

# From Cursor to Cline
cp -r .cursor/rules/my-skill/ .clinerules/my-skill/

CLI Platform to Desktop/Web

Export as .zip:

python scripts/export_utils.py ./my-skill --variant desktop
# Output: exports/my-skill-desktop-v1.0.0.zip

CLI Platform to API

Export as optimized .zip:

python scripts/export_utils.py ./my-skill --variant api
# Output: exports/my-skill-api-v1.0.0.zip (< 8MB)

---

Best Practices

1. Develop once, deploy everywhere: Create and test in your preferred CLI tool, then install on other platforms.
2. Use install.sh: Include the cross-platform installer for easy deployment.
3. Keep SKILL.md lean: Under 500 lines, detailed content in references/.
4. Test activation: Verify the description triggers correctly on your target platform.
5. Include README.md: Document installation instructions for all platforms.
6. No platform hacks: Avoid platform-specific code or configuration. The standard format works everywhere.

---

Generated by: agent-skill-creator v4.0 Standard: Agent Skills Open Standard (agentskills.io/specification)