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:

1. The skill has been tested and works in that agent
2. The instructions are compatible with the agent's capabilities
3. 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.

Further Reading

• The Complete Guide to Building a Skill - Structure, frontmatter, and instructions
• Testing & Distributing Skills - How to test and distribute skills
• Getting Started - Installation and first use