Multi-Agent Compatibility: How Skills Work Across Agents

One Format, Many Agents

Skills are based on the SKILL.md format, an open standard that all AI agents can read and interpret. A SKILL.md file is Markdown with YAML frontmatter, and there is nothing agent-specific about it. This means a skill written once can work in any agent that supports the format.

Each agent stores skills in its own directory:

Claude Code: .claude/skills/
Cursor: .cursor/skills/
GitHub Copilot: .github/skills/
Windsurf: .windsurf/skills/
OpenCode: .opencode/skills/
Codex: .codex/skills/

The Skills IL CLI (npx skills-il add) automatically detects which agents are installed and installs the skill to all of them.

Skill Types and Portability

Not all skills are created equal when it comes to portability. The key distinction is between two types:

Workflow Skills

Skills that define a textual sequence of instructions. For example: "Check the file, look for errors, fix them, and check again." These skills are fully portable because every agent can read and follow text instructions.

Examples:

A skill for filing a VAT report (step sequence with checks)
A skill for writing API documentation (template with rules)
A skill for translating code to Hebrew (localization rules)

Capability Skills

Skills that rely on specific tools and capabilities. For example: a skill that runs a Python script, calls an MCP tool, or uses terminal access. The portability of these skills depends on the tools each agent offers.

Examples:

A skill that runs Python scripts for data processing (requires Bash)
A skill that uses MCP to access Bank of Israel data (requires MCP)
A skill that edits files and runs tests (requires edit tools and terminal)

What "Supported" Means Per Agent

When a skill lists supported_agents in its frontmatter, it means:

The skill has been tested and works in that agent
The instructions are compatible with the agent's capabilities
If the skill requires specific tools, they are available in the agent

A skill that does not list supported_agents can still work in any agent, because SKILL.md is a universal format. However, it may not have been tested.

Writing Portable Skills

1. Describe Intents, Not Tools

# Bad - tied to a specific tool
Run \`eslint --fix src/\` to fix linting errors.

# Good - describes intent
Check the source code for linting errors and fix them automatically.
The project uses ESLint; run the linter if available.

When you describe intent, every agent can choose the best way to accomplish the task.

2. Bundle Scripts

If the skill requires complex logic, put it in a script in the scripts/ directory:

your-skill/ ├── SKILL.md └── scripts/ └── validate_invoice.py

## Instructions
Run the validation script to check the invoice:
\`python scripts/validate_invoice.py --input invoice.pdf\`

This way, any agent that can run Python can use the skill, without depending on agent-specific tools.

3. Declare Requirements Explicitly

Use the compatibility field in frontmatter:

compatibility: "Requires terminal access for running Python scripts"

And in the skill body, provide alternatives where possible:

## Prerequisites
- Python 3.8+ (required for validation scripts)
- If terminal access is not available, review the validation
  rules manually in references/validation-rules.md

4. Avoid Agent-Specific Tool Names

# Bad - assumes specific tool
Use the Bash tool to run the command.
Use the Edit tool to modify the file.

# Good - neutral
Run the command in the terminal.
Modify the file with the necessary changes.

5. Provide Fallbacks

When the skill requires a capability not every agent supports, provide an alternative path:

## Step 3: Validate Output
If you can run scripts, execute:
\`python scripts/check_output.py\`

Otherwise, manually verify:
1. Check that all required fields are present
2. Verify date format is DD/MM/YYYY
3. Confirm totals match line items

Per-Agent Notes

Claude Code

Supports all tools: Bash, file read/write, MCP
Runs in the terminal, giving it full access to the development environment
Supports allowed-tools in frontmatter for restricting permissions
Supports local skills (.claude/skills/) and project-level skills
The most capable agent for capability-based skills

Cursor

Supports MCP and multi-file editing
Runs in a visual environment (IDE), not the terminal
Skills are loaded via .cursor/skills/ or Cursor Rules
Excels at skills involving code edits across multiple files
Terminal command execution is available through the built-in terminal

GitHub Copilot

Supports MCP and skills via .github/skills/
Integrates with GitHub workflows (PRs, Issues)
Excels at code completion and short code tasks
Copilot Coding Agent can handle more complex tasks

Windsurf

Supports MCP via config file
IDE interface with smooth transitions between manual and AI work
Skills are loaded via .windsurf/skills/
Supports command execution and file access

OpenCode

Open-source code agent that runs in the terminal
Supports skills via .opencode/skills/
Similar functionality to Claude Code with different models
Supports MCP

Codex

OpenAI's agent that runs in the cloud (sandbox)
Can run code and tests autonomously
Isolated environment, so skills requiring external network access may not work
Excels at tasks requiring autonomous code execution

Portability Checklist

Before publishing a skill, verify:

SKILL.md does not mention agent-specific tool names (Bash tool, Edit tool)
Complex operations are encapsulated in scripts in the scripts/ directory
External requirements are declared in compatibility
Alternative paths exist for operations not every agent supports
supported_agents is up to date and reflects actual testing
The skill describes intents ("check for errors") not commands ("run eslint")

Summary

The power of skills lies in their portability. A well-written skill works in any agent without modification. The principles are simple: describe intents, bundle scripts, declare requirements, and provide fallbacks. The more you adhere to these principles, the more useful your skill will be to more developers in more environments.