Cross-platform skills: Claude, Cursor, and beyond

A SKILL.md file has no vendor lock-in built into it. It’s YAML frontmatter and a Markdown body. Any agent that can read a text file and parse a couple of fields can load one. That’s the whole reason a skill written for Claude Code can also run in Cursor, Codex, Windsurf, or OpenCode without a rewrite.

This post covers why it’s worth writing skills that way on purpose, where each agent actually looks for them, how to install to more than one agent at once, and what to check before you publish something you expect other people to install.

Why write agent-agnostic in the first place

The default temptation is to write a skill for whatever you’re using today and fix it later if it breaks somewhere else. That’s backwards for two reasons.

First, the format doesn’t cost you anything to keep portable. There’s no Claude-specific frontmatter field or Cursor-only Markdown extension you’re giving up by staying plain. name, description, and an optional license, then a Markdown body. Writing it any other way is extra effort, not less.

Second, you don’t control which agent the next reader is running. If you publish a skill, the person installing it might be on Cursor while you wrote and tested it on Claude Code. If you’re writing one for your own team, someone on that team is on a different agent than you, guaranteed, the moment the team has more than two people. Write once, reuse everywhere isn’t an aspiration here, it’s the default behavior of the format as long as you don’t work against it.

Where each agent stores skills

Every agent that reads SKILL.md files keeps them in its own directory, and a skill installs as <directory>/<skill-name>/SKILL.md:

• claude-code -> .claude/skills
• cursor -> .cursor/skills
• codex -> .codex/skills
• windsurf -> .windsurf/skills
• opencode -> .opencode/skills

So the same pdf-extract skill lands at .claude/skills/pdf-extract/SKILL.md for Claude Code and .cursor/skills/pdf-extract/SKILL.md for Cursor. Same file, same name, different parent folder. Nothing about the file itself changes between agents, only where it sits on disk.

If you want the setup instructions for a specific agent, each one has a dedicated guide at https://skillmd.com/agents/<id>.txt, for example https://skillmd.com/agents/cursor.txt.

Installing to specific agents

The skillmd CLI knows this directory map already, so it handles placement for you instead of you copying files by hand.

npm i -g skillmds
skillmd add anthropic/docx

Run without flags, skillmd add detects which agents are set up in the current project and installs into each of their directories. If you want control over exactly which agents get the skill, name them with -a:

skillmd add anthropic/docx -a claude-code cursor

That writes into .claude/skills and .cursor/skills only, even if the project also has a .codex directory sitting there from a different tool. Add -g to install into your home directory instead of the current project, which makes the skill available to that agent everywhere rather than just this repo:

skillmd add anthropic/docx -g -a claude-code

If you’d rather skip the CLI, the raw file is fetchable directly and you can place it yourself:

mkdir -p .windsurf/skills/docx
curl -s https://api.skillmd.com/api/skills/anthropic/docx/raw -o .windsurf/skills/docx/SKILL.md

Useful when you’re scripting a fresh environment and already know exactly which agent and path you’re targeting.

Testing across a couple of agents before you publish

A skill that works perfectly in the agent you wrote it in can still fail somewhere else, not because the format is broken, but because your instructions quietly assumed things about that one agent. Before you publish, install the same skill into at least two agents and actually run it.

A few things to check on the second agent:

• Does the description alone make sense to someone who hasn’t read your first draft? It’s the only thing an agent sees before deciding to load the body.
• Do the steps assume a tool, keybinding, or terminal behavior that’s specific to one agent’s environment?
• Does the skill reference file paths relative to a project layout that one agent’s default project structure has but another doesn’t?

None of this needs a large test matrix. Installing into two agents you actually use, Claude Code and Cursor, or Claude Code and Codex, and walking through the skill’s steps once in each is usually enough to catch the assumptions that don’t generalize.

Keeping instructions portable

The format won’t stop you from writing something agent-specific inside the body, since the body is just Markdown and Markdown doesn’t enforce anything. A few habits keep the instructions themselves portable:

Describe the outcome, not the UI. “Open the command palette and run the formatter” assumes a command palette exists and works the same way everywhere. “Run the project’s formatter on the changed files” describes what needs to happen and lets each agent do it however it does things.

Avoid hardcoding one agent’s config file. If your skill needs settings, reference a plain config file in the project rather than an agent-specific settings location. A .claude/settings.json reference does nothing for someone running Windsurf.

Write shell commands, not agent shortcuts. A bash or curl command runs the same everywhere. A built-in slash command or keybinding is agent-specific by definition, so if you mention one, say so explicitly rather than assuming everyone has it.

Keep the description generic about environment. “For use in Claude Code” in your description narrows who installs it and contradicts the point of writing it portably in the first place, unless the skill genuinely only makes sense in one agent’s context.

Publishing once, running everywhere

Every skill on the registry goes through a safety review before it’s visible in search, regardless of which agent someone ends up installing it into. That review happens once, at publish time, not per agent. The portability is what makes that single pass worth it: write the skill, pass review, and it’s immediately usable by anyone on any of the supported agents, not just the one you happened to test in first.

If you’re setting up a new agent and want the exact install path and directory conventions for it, check https://skillmd.com/agents/<id>.txt for that agent’s id before you start copying files by hand.