How to write an agent skill that works across Claude Code, Codex, and Cursor
A skill is the simplest way to give a coding agent a repeatable capability: a folder with a SKILL.md file that tells the agent how to do one specific job. Deploy steps, a review checklist, a repo's own conventions. The agent loads the instructions when the task matches, and follows them instead of improvising.
The format is consolidating across harnesses. The same skill folder is starting to work in Claude Code, Codex, Cursor, and other agents, which means a skill you write once can move with you. A skill is a harness-level capability, not a model one, which is why the same folder can ride from one agent to the next. This is a short guide to writing one that actually ports, rather than one that quietly depends on a single tool.
What a skill is
At minimum, a skill is a directory containing a SKILL.md:
my-skill/
SKILL.md
SKILL.md opens with frontmatter and then the instructions:
---
name: deploy-staging
description: Use when deploying the web app to the staging environment
---
Run the staging deploy in this order.
1. `make build` and confirm it exits clean.
2. `make deploy-staging`.
3. Poll the health check until it returns 200, then report the version.
The description is the part the agent reads to decide whether the skill applies. Write it as a trigger ("Use when..."), not a summary. A vague description means the skill never loads when it should.
Why portability breaks
A skill stops being portable the moment it assumes one harness's specifics. The common leaks:
- Tool names. One agent calls its shell tool
Bash, another calls it something else. Instructions that say "use the Bash tool" break where that name does not exist. Say "run the command," and let the agent map it to its own tool. - File paths that only exist in one setup. Absolute paths to a home directory, or a scratch location one harness provides and another does not. Keep paths relative to the repo.
- Slash commands and UI affordances. "Open the command palette and run X" is not an instruction an agent in a terminal can follow. Describe the action, not the button.
- Model assumptions. A skill that only works on one model's quirks is not a skill, it is a workaround. Write for the capability, not the vendor.
How to write one that ports
Keep the skill about the job, not the tool. Four rules cover most of it.
Describe actions, not tools. "Run the test suite and read the failures" ports. "Invoke the test-runner tool with these arguments" does not.
Keep everything in the folder. If the skill needs a script, a template, or a checklist, put it in the skill directory and reference it by relative path. A skill that reaches outside its folder is a skill that breaks on someone else's machine.
State the trigger precisely. The description is the whole routing logic. "Use when the user asks to cut a release" loads at the right time. "Release helper" does not.
Leave one check behind. If the skill does something non-trivial, end it with the smallest way to confirm it worked: a command whose output shows success, a file that should now exist. An agent that can check its own work is worth more than one that reports success.
Test the move
The only real test of portability is running the skill under a second harness. Load it in the agent you wrote it for, confirm it fires and completes. Then load the same folder in a different agent and run the same task. What breaks on the second run is exactly the harness-specific assumption you did not notice on the first.
Common questions
What is the difference between a skill and a prompt? A prompt is a single instruction you type. A skill is a saved folder the agent loads on its own when the task matches its trigger. That makes the capability reusable and shared, not retyped each time.
How is a skill different from an MCP server? An MCP server gives an agent a new tool (a live capability it can call). A skill gives it instructions for using the tools it already has. They compose: a skill can tell the agent when and how to call an MCP tool.
Where do skills live in a repo? Commonly in a skills/ directory, one folder per skill, each with its own SKILL.md. Keeping them in the repo means they are versioned with the code they operate on.
Do skills work across different coding agents? Increasingly, yes, if you write them to the job rather than the harness. Avoid tool-specific names, keep everything in the folder, and test the skill under a second agent before you rely on it.