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

Cross-Platform Compatibility Guide

Version: 5.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 v5.0, this includes 14+ platforms across 3 support tiers.

Supported Platforms

Tier 1 — Native SKILL.md Support

These platforms read SKILL.md natively with no conversion needed:

Platform	Type	User-Level Path	Project-Level Path
Claude Code	CLI	~/.claude/skills/	.claude/skills/
GitHub Copilot CLI	CLI	~/.copilot/skills/	.github/skills/
VS Code Copilot	IDE Extension	~/.claude/skills/	.github/skills/
Codex CLI	CLI	~/.agents/skills/	.agents/skills/
Gemini CLI	CLI	~/.gemini/skills/	.gemini/skills/
Kiro	IDE	—	.kiro/skills/
Antigravity	CLI	—	.agents/skills/
Goose	CLI	~/.config/goose/skills/	—
OpenCode	CLI	~/.config/opencode/skills/	—

Tier 2 — SKILL.md via Format Adapter

These platforms use their own rule format. The installer auto-generates the native format from SKILL.md:

Platform	Type	Native Format	Adapter Output	Install Path
Cursor	IDE	.mdc	Auto-generated .mdc with frontmatter	.cursor/rules/
Windsurf	IDE	.md rules	.md rule file or global_rules.md append	.windsurf/rules/ (project) or ~/.codeium/windsurf/memories/global_rules.md (global)
Cline	VS Code Ext	Plain .md	Stripped frontmatter .md	.clinerules/
Roo Code	VS Code Ext	Plain .md	Stripped frontmatter .md	.roo/rules/
Trae	IDE	Plain .md	Stripped frontmatter .md	.trae/rules/

Tier 3 — Manual Configuration

These platforms require manual integration:

Platform	Config File	Instructions
Zed	.rules	Copy SKILL.md body into .rules file
Junie	.junie/guidelines.md	Copy SKILL.md body into guidelines
Aider	CONVENTIONS.md	Copy SKILL.md body into CONVENTIONS.md

The Unifying Standard

All Tier 1 and Tier 2 platforms read from the same SKILL.md source:

---
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 — directly on Tier 1, via auto-adapter on Tier 2.

---

Universal Path: .agents/skills/

The .agents/skills/ directory is an emerging cross-tool convention for agent skill discovery. Multiple tools already read from this path:

• Codex CLI — reads ~/.agents/skills/ and .agents/skills/
• Gemini CLI — discovers skills in ~/.agents/skills/
• Kiro — reads .agents/skills/ (project-level)
• Antigravity — reads .agents/skills/ (project-level)

The installer creates a secondary symlink at ~/.agents/skills/<skill-name> after every install (unless the primary target is already .agents/). This means a skill installed for Claude Code is also discoverable by Codex CLI, Gemini CLI, and other universal-path tools automatically.

# Install for Claude Code — also creates ~/.agents/skills/ symlink
./install.sh --platform claude-code

# Install directly to universal path
./install.sh --platform universal

# Install to ALL detected platforms at once
./install.sh --all

---

Format Adapters

The installer automatically converts SKILL.md to platform-native formats when needed. No separate format files are committed to the skill repo — SKILL.md remains the single source of truth.

Cursor (.mdc)

The adapter generates a .mdc file with Cursor-specific frontmatter:

---
description: <extracted from SKILL.md frontmatter>
globs:
alwaysApply: true
---
<SKILL.md body without YAML frontmatter>

Windsurf (.md rules)

Project-level: Creates a .md file in .windsurf/rules/.

User-level (global): Appends to ~/.codeium/windsurf/memories/global_rules.md with idempotent markers:

<!-- BEGIN skill-name -->
<SKILL.md body>
<!-- END skill-name -->

Re-running the installer replaces the existing block rather than duplicating.

Cline / Roo Code / Trae (plain .md)

The adapter strips YAML frontmatter and outputs plain markdown. These tools read .md files from their respective rule directories.

---

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 (auto-generates .mdc)
./install.sh --platform cursor

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

Best for: Cursor IDE users. The installer auto-generates a .mdc file alongside SKILL.md.

Windsurf

# Using install.sh (project-level — creates .windsurf/rules/ rule)
./install.sh --platform windsurf --project

# Using install.sh (user-level — appends to global_rules.md)
./install.sh --platform windsurf

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.

Codex CLI

# Using install.sh (installs to ~/.agents/skills/)
./install.sh --platform codex

# Manual
cp -r skill-name/ ~/.agents/skills/skill-name/

Best for: OpenAI Codex CLI users. Codex reads from ~/.agents/skills/.

Gemini CLI

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

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

Best for: Gemini CLI users.

Kiro

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

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

Best for: Kiro IDE users (project-level).

Trae

# Using install.sh (auto-generates plain .md)
./install.sh --platform trae

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

Best for: Trae IDE users.

Goose

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

# Manual
cp -r skill-name/ ~/.config/goose/skills/skill-name/

Best for: Goose CLI users.

OpenCode

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

# Manual
cp -r skill-name/ ~/.config/opencode/skills/skill-name/

Best for: OpenCode CLI users.

Roo Code

# Using install.sh (auto-generates plain .md)
./install.sh --platform roo-code

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

Best for: Roo Code extension users in VS Code.

Antigravity

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

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

Best for: Antigravity CLI users.

Universal Path

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

# Manual
cp -r skill-name/ ~/.agents/skills/skill-name/

Best for: Multi-tool users. One install discoverable by Codex CLI, Gemini CLI, Kiro, Antigravity, and other tools that read .agents/skills/.

Install All

# Install to every detected tool at once
./install.sh --all

Alternative: npx

npx skills add <repo-url>
npx skills add ./local-skill-dir

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	Tier 1 Platforms	Tier 2 Platforms	Desktop/Web	Claude API
SKILL.md support	Native	Via adapter	Full	Full
Python scripts	Full	Full	Full	Sandboxed*
References/docs	Full	Full	Full	Full
Assets/templates	Full	Full	Full	Full
install.sh	Full	Full	N/A	N/A
Format adapters	N/A	Auto	N/A	N/A

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

Technical Specifications

Specification	CLI/IDE 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 Codex CLI
cp -r ~/.claude/skills/my-skill/ ~/.agents/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. Use --all for multi-tool users: Install to every detected tool with a single command.
4. Keep SKILL.md lean: Under 500 lines, detailed content in references/.
5. Test activation: Verify the description triggers correctly on your target platform.
6. Include README.md: Document installation instructions for all platforms.
7. No platform hacks: Avoid platform-specific code or configuration. The standard format works everywhere; adapters handle the rest.

---

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