SKILL.md Cross-Agent Compatibility: Tested Across 6 Agents (2026)
SKILL.md is supposed to be portable. Write once, use everywhere. But does that actually hold up? We installed the same 10 skills across Claude Code, Codex CLI, Gemini CLI, Cursor, GitHub Copilot (agent mode), and OpenClaw, and tested whether each skill triggered correctly and produced the expected output. Here are the results.
Quick Answer: Core SKILL.md skills (standard frontmatter, plain markdown instructions) work across all 6 major agents without modification. In our test of 10 skills, 8 worked identically everywhere. Two skills that used agent-specific features (Claude Code's
allowed-toolsandcontext: fork) needed minor edits for full compatibility. The most reliable approach: stick toname,description,when_to_usein your frontmatter, and write instructions in plain markdown. Avoid agent-specific fields unless you're building exclusively for one platform.
The test setup
We selected 10 skills that cover common developer workflows. All are publicly available on Agensi and use the standard SKILL.md format.
The skills tested:
- commit-writer — writes conventional commit messages from staged changes
- code-reviewer — reviews code for security, logic, and style issues
- readme-generator — generates project documentation from source code
- test-scaffold — creates test files matching existing project conventions
- pr-description-writer — writes pull request descriptions from branch diffs
- env-doctor — diagnoses environment and dependency issues
- seo-optimizer — analyzes and improves web page SEO
- humanize-writing — rewrites AI-sounding text in natural voice
- deep-research-team — multi-agent research with source citations
- content-writer — generates long-form content following a brief
Each skill was installed in the correct directory for each agent and tested with 3 prompts designed to trigger it, plus 1 prompt that should not trigger it.
The agents tested:
- Claude Code (Anthropic) — terminal agent,
~/.claude/skills/ - Codex CLI (OpenAI) — terminal agent,
~/.codex/skills/ - Gemini CLI (Google) — terminal agent,
~/.gemini/skills/ - Cursor (Anysphere) — IDE agent,
.cursor/skills/ - GitHub Copilot agent mode (Microsoft) — IDE agent,
.github/skills/ - OpenClaw — open-source terminal agent,
~/.openclaw/skills/
Results summary
| Skill | Claude Code | Codex CLI | Gemini CLI | Cursor | Copilot | OpenClaw |
|---|---|---|---|---|---|---|
| commit-writer | Pass | Pass | Pass | Pass | Pass | Pass |
| code-reviewer | Pass | Pass | Pass | Pass | Pass | Pass |
| readme-generator | Pass | Pass | Pass | Pass | Pass | Pass |
| test-scaffold | Pass | Pass | Pass | Pass | Pass | Pass |
| pr-description-writer | Pass | Pass | Pass | Pass | Pass | Pass |
| env-doctor | Pass | Pass | Pass | Partial | Pass | Pass |
| seo-optimizer | Pass | Pass | Pass | Pass | Pass | Pass |
| humanize-writing | Pass | Pass | Pass | Pass | Pass | Pass |
| deep-research-team | Pass | Partial | Partial | Partial | Partial | Pass |
| content-writer | Pass | Pass | Pass | Pass | Pass | Pass |
8 out of 10 skills worked perfectly across all 6 agents. Two skills had partial results on some agents due to agent-specific features.
What worked everywhere
The 8 skills that passed everywhere share a common pattern: standard YAML frontmatter with name and description, plain markdown instructions, no agent-specific fields, and no reliance on subagent spawning or tool permissions.
This is the portable core of SKILL.md. If you stick to these elements, your skill works across every agent that supports the format.
Example of a universally compatible frontmatter:
---
name: commit-writer
description: Writes conventional commit messages from staged git changes. Use when the user asks to write a commit message, commit changes, or says "commit this."
---
The instructions below the frontmatter are plain markdown: numbered steps, examples, output format descriptions. Every agent tested was able to parse this and follow the instructions reliably.
What caused partial results
deep-research-team
This skill uses Claude Code's subagent spawning to run parallel research threads. Claude Code and OpenClaw handled this correctly because both support the agent field and subagent orchestration. Codex CLI, Gemini CLI, Cursor, and Copilot don't support subagent spawning, so they ran the skill as a single-threaded workflow. The output was still useful (research was conducted, sources were cited) but it wasn't parallelized. The skill didn't break. It just fell back to sequential execution.
Takeaway: Skills that use multi-agent features work best in Claude Code and OpenClaw but degrade gracefully in other agents. They don't fail, they just run linearly.
env-doctor
This skill uses the allowed-tools frontmatter field to restrict which tools it can invoke (specifically limiting to read-only filesystem and shell commands). Claude Code, Codex CLI, Gemini CLI, Copilot, and OpenClaw respected or safely ignored this field. Cursor had a partial result because it doesn't parse allowed-tools, so the skill ran without tool restrictions, which is a wider permission scope than intended. The output was correct, but the safety constraint wasn't enforced.
Takeaway: Tool permission fields are agent-specific. If security constraints matter, test on each target agent individually.
Agent-specific quirks we found
Skill directory locations
Every agent has its own skills directory. This is the most common source of "my skill doesn't work" reports. The skill file is identical, but it needs to be in the right place:
| Agent | Personal skills | Project skills |
|---|---|---|
| Claude Code | ~/.claude/skills/ |
.claude/skills/ |
| Codex CLI | ~/.codex/skills/ |
.codex/skills/ |
| Gemini CLI | ~/.gemini/skills/ |
.gemini/skills/ |
| Cursor | n/a (project only) | .cursor/skills/ |
| Copilot | ~/.config/github-copilot/skills/ |
.github/skills/ |
| OpenClaw | ~/.openclaw/skills/ |
.openclaw/skills/ |
Note that Cursor doesn't have a personal (global) skills directory. Skills are project-scoped only. If you want the same skill in every Cursor project, you need to copy it into each project's .cursor/skills/ folder. Agensi's one-liner curl installer (curl -sL agensi.io/api/install/<slug> | tar xz -C .cursor/skills/) makes this a single command per project.
For full path details, see the dedicated guides: Claude Code, Codex CLI, Gemini CLI, Cursor.
Trigger reliability
All agents use the description field to decide when to load a skill, but they differ in how aggressively they match. In our tests:
Claude Code was the most reliable at triggering. It matched descriptions accurately and the when_to_use field provided additional matching context.
OpenClaw matched closely to Claude Code's behavior, which makes sense since it follows the same SKILL.md specification closely.
Codex CLI triggered reliably but occasionally needed slightly more explicit prompts. "Review this code" sometimes didn't trigger the code-reviewer skill unless the description was very specific.
Gemini CLI triggered well for skills with clear descriptions. Vague descriptions caused more missed triggers than Claude Code.
Cursor required a window reload after installing new skills. Without the reload, skills didn't appear. After reload, triggering was reliable.
Copilot agent mode was the newest implementation (April 2026) and the most conservative about triggering. Some skills needed prompts that very closely matched the description wording.
Frontmatter field support
Not every agent supports every frontmatter field. Here's what's safe to use everywhere versus what's agent-specific:
Universally supported: name, description
Widely supported (4+ agents): when_to_use, argument-hint, arguments
Agent-specific: allowed-tools (Claude Code, OpenClaw), context (Claude Code), agent (Claude Code, OpenClaw), hooks (Claude Code), model (Claude Code), disable-model-invocation (Claude Code, OpenClaw)
If you're building for cross-agent use, stick to the universally and widely supported fields. Agent-specific fields won't cause errors in other agents. They'll be silently ignored.
How to write maximally portable skills
Based on these test results, here are the guidelines for writing skills that work everywhere:
Use only name, description, and optionally when_to_use in frontmatter. These are parsed by every agent.
Write instructions in plain markdown. Numbered steps, headers, code examples, tables. Every agent handles these.
Don't assume subagent support. If your skill benefits from parallel execution, design it so the instructions also make sense as a linear workflow. Agents that support subagents will use them. Others will run sequentially.
Don't rely on tool permissions. If security matters, note in the instructions what the skill should and should not do, but don't depend on allowed-tools being enforced.
Test the description. The description is the single most important field for portability. If it's clear and specific, every agent can match it. If it's vague, you'll get inconsistent triggering. Use the skill-creator's trigger optimization to refine it.
Include examples in the instructions. Agents differ in how they interpret ambiguous instructions. Concrete examples reduce variance. Show the expected output format, include sample inputs, demonstrate edge cases.