Claude Code Skills vs Cursor Rules vs Codex Skills
All three major AI coding tools let you customize agent behavior, but they do it differently. Here's how SKILL.md skills, .cursorrules, and Codex skills compare.
Three names, two formats. Claude Code Skills and Codex Skills are the same open standard under different branding, while Cursor Rules is a Cursor-only file that predates it. This comparison covers what each one is, how they load, when to pick which, and how to move between them.
Quick Answer: Claude Code Skills and Codex Skills both use the SKILL.md open standard: one portable file with YAML frontmatter that also runs in Cursor, OpenCode, and OpenClaw. Cursor Rules (
.cursorrules) is a Cursor-only, always-on prompt at the repo root. If you want portability, versioning, and on-demand loading, write SKILL.md. If you only need "always do X in this repo" inside Cursor,.cursorrulesis fine.
Feature comparison
| Feature | SKILL.md (Claude Code / Codex) | .cursorrules |
|---|---|---|
| Portable across agents | Yes (20+ agents) | No, Cursor only |
| YAML frontmatter with triggers | Yes | No |
| Loaded on demand | Yes, by trigger | Always on |
| Versioned distribution | Yes, via marketplaces | No |
| Reference files | Yes | No |
| Package as zip / install | Yes | No |
| Multiple skills side by side | Yes, one folder each | One file per repo |
| Team sharing | Commit .claude/skills/ or install from a marketplace | Commit the file |
What exactly is a Claude Code skill?
A folder containing a SKILL.md file with YAML frontmatter (name, description, plus optional fields) and a markdown body holding the instructions. It lives in ~/.claude/skills/ for personal use or .claude/skills/ inside a repo for a team. Claude reads the descriptions at session start and pulls a skill's body into context only when your request matches it. That on-demand loading is the important part: ten skills cost you almost nothing in context until one is actually relevant.
What are Codex Skills?
The same thing. OpenAI's Codex CLI reads SKILL.md files from ~/.codex/skills/ and .codex/skills/, and it can additionally read an optional openai.yaml alongside the SKILL.md for Codex-specific metadata such as UI hints or MCP tool dependencies. Other agents ignore that extra file, and skills work fine without it. Codex also supports explicit invocation with a $ prefix ($code-reviewer review this PR) on top of automatic triggering.
What are Cursor Rules?
.cursorrules is a single plain-text file at the root of a repository containing standing instructions for Cursor. There is no frontmatter, no trigger metadata, and no packaging. The content is prepended to the model's context for that project, always, whether it is relevant to the current task or not. It cannot be split into multiple named units, versioned independently, or shipped to another agent.
Cursor has since added support for reading SKILL.md-style skills at .cursor/skills/, which means you no longer have to choose Cursor's own format to work in Cursor.
How does loading differ in practice?
An always-on rules file competes for context with your actual code. As it grows past a few hundred lines, two things happen: the model starts to weight parts of it unevenly, and you lose the ability to reason about which instruction applied to which task. SKILL.md avoids both by splitting behaviour into named units with descriptions, so only the relevant unit enters context, and you can tell from the session which skill fired.
When should I pick each?
- SKILL.md (Claude Code / Codex): you want the same behaviour across several agents, you want to distribute the skill to a team or customers, you want more than one behaviour without them all being loaded at once, or you want to install ready-made skills from a marketplace like Agensi.
.cursorrules: you want a one-file, always-on system prompt for a single Cursor repository and you have no plans to use another agent.- Codex Skills: identical to SKILL.md; use
openai.yamlonly when you specifically want Codex-only metadata.
If you maintain both today, keep SKILL.md as the source of truth and let the rules file shrink to a pointer.
How do I migrate .cursorrules to SKILL.md?
Split the rules file by topic, not by line. A typical .cursorrules mixes stack conventions, review standards, and testing rules into one blob; each of those becomes its own skill with a description that says when it applies. Then delete the migrated sections from the rules file so the two can't drift apart. The step-by-step version, including a worked example, is in How to migrate Cursor rules to SKILL.md.
Do the same skills really run everywhere?
Yes, with two caveats: agent-specific slash commands and agent-specific execution settings (like Claude Code's subagent forking) don't carry over, and helper scripts bundled with a skill may need adjusting per platform. Plain-markdown instruction skills are fully portable. These three run identically in Claude Code, Codex CLI, Cursor, OpenCode, and OpenClaw:
Where do I go next?
- Every field the format supports: SKILL.md format reference
- All four config formats side by side, including AGENTS.md and CLAUDE.md: AGENTS.md vs SKILL.md vs CLAUDE.md vs .cursorrules
- Installing what you pick: Claude Code, Codex CLI
Browse security-scanned, portable SKILL.md skills on Agensi.
Frequently asked questions
Can I use both .cursorrules and SKILL.md in the same repo? Yes. Cursor reads both. Keep the rules file for a couple of genuinely always-on lines and put everything task-specific in skills, otherwise the two sets of instructions will contradict each other eventually.
Do Codex Skills need openai.yaml? No. SKILL.md alone is enough; the yaml file only adds optional Codex-specific metadata.
Does a .cursorrules file work in Claude Code? No. Nothing outside Cursor reads it, which is the main argument for migrating.
Is one format faster? On-demand skills keep the prompt smaller than a large always-on rules file, which usually means cheaper and more focused responses.