What we learned moving one skill across hosts

We took one skill folder, explain-error, with nothing but standard name and description frontmatter, and copied it byte-for-byte into a Claude Code project path and two Codex project paths, with no per-host edits. The plain folder installed and validated identically everywhere we tried it, and Codex loaded and used it without changes. That’s a narrower claim than “this skill is portable”: we didn’t test Cursor, and we didn’t test any of the host-specific features that make a skill richer but less portable.

What we moved

explain-error/SKILL.md uses only the two fields the Agent Skills specification requires:

name: explain-error
description: Explains a pasted error message or stack trace and suggests one concrete fix. Use when someone shares an error, exception, stack trace, or traceback and asks what is wrong or how to fix it.

Its body is plain instructions with no host-specific tool names or slash commands, plus one supporting file, references/checklist.md, that the instructions tell the agent to read.

What traveled cleanly

We copied the identical folder to:

• .agents/skills/explain-error/ (Codex, current path)
• .codex/skills/explain-error/ (Codex, older path)
• .claude/skills/explain-error/ (Claude Code)

npx skills-ref validate passed on the source folder before we copied it anywhere, because the format check only looks at frontmatter shape and is host-independent; since the copies were byte-for-byte identical, we didn’t re-run validate against each installed copy separately. npx skills add -a codex -y and npx skills add -a claude-code -y each installed a full copy (not a symlink) at the expected path (.agents/skills/ and .claude/skills/ respectively; the installer doesn’t target .codex/skills/, which we reached only by hand-copy), with a skills-lock.json recording the source. On Codex, both project paths loaded the skill: the trace showed SKILL.md and references/checklist.md both being read, and the answer carried the marker line, file/line, cause, and single fix the instructions asked for. Claude Code accepted the same folder at its project path; we could not test live loading there in this pass. See where agent skills live for the full per-host breakdown.

What doesn’t travel: documented incompatibilities

Moving the plain core cleanly doesn’t mean every feature does. From the hosts’ own documentation:

Extra frontmatter is host-specific. Claude Code documents context: fork, invocation controls, paths, and dynamic !command“ injection in a skill’s body. Cursor documents its own paths, disable-model-invocation, icon, color, and metadata fields. OpenAI’s optional agents/openai.yaml handles Codex- and ChatGPT-specific presentation. None of these are part of the core spec, and a skill that relies on one will behave differently, or not at all, on a host that doesn’t read it.

Tool names and runtimes are also host-specific. A skill that tells the agent to call a Claude-only tool, use a host-specific slash command, or assume a particular shell is not portable without adaptation. The shared instructions should describe the action and prerequisites in plain terms; each host still needs its own check that the tool or script it names actually exists there.

Plugin packaging is a second, separate layer. The Agent Plugins 1.0.0 specification defines a portable root plugin.json with a standard skills/ folder and optional mcp.json. Codex and Cursor document support for that portable format; Claude Code documents its own .claude-plugin/plugin.json and .claude-plugin/marketplace.json instead. Copying one plugin manifest between all three hosts is not established as a working install route.

One concrete, documented plugin failure: the Agent Plugins spec defines ${PLUGIN_ROOT} and ${PLUGIN_DATA} placeholder expansion for MCP configuration fields. Cursor’s own docs say it does not expand those placeholders in mcp.json, and directs authors to a Cursor-specific ${CURSOR_PLUGIN_ROOT} instead. A portable SKILL.md folder does not resolve this; it’s a plugin-level incompatibility, not a skill-level one.

A broken reference file fails silently, and we’ve only confirmed this on one host. When we deliberately renamed references/checklist.md on the Codex copy, the tool trace showed the failed read, but Codex’s final answer gave no sign anything was missing; it fell back on instructions already in SKILL.md. skills-ref validate didn’t catch it either, since it only checks frontmatter. We have not repeated this specific test on Claude Code or Cursor, so treat “silent failure on a broken reference” as confirmed for Codex only, and worth checking again on any host before you rely on a reference file being followed.

What we checked

Format

The identical folder validated with skills-ref v0.1.5, with no per-host changes, checked September 27, 2026.

Installs

The identical folder installed correctly at both Codex project paths and the Claude Code project path by hand-copy. npx skills add additionally confirmed for .agents/skills/ (Codex) and .claude/skills/ (Claude Code); it doesn’t write .codex/skills/.

Loads

Confirmed on Codex, on both project paths, on codex-cli 0.157.1. Not confirmed on Claude Code (a test-setup authentication issue) or Cursor (not installed).

What we didn’t check: any host-specific frontmatter field, plugin packaging in any of the three native formats, the ${PLUGIN_ROOT}/${CURSOR_PLUGIN_ROOT} difference against a real plugin install, and whether a broken reference fails silently on Claude Code or Cursor the way it did on Codex.

Sources

• Agent Skills specification
• Agent Plugins specification
• Claude Code: Skills
• OpenAI Docs: Build skills
• Cursor: Plugins