If you're teaching an AI coding agent how to work the way your team works, you're choosing between two formats: SKILL.md (used by Claude Code, Codex CLI, OpenClaw, and others) and Cursor's rules system (.cursorrules and .cursor/rules/*.mdc). Both solve the same core problem, but they take different approaches with real implications for portability and flexibility.
This guide breaks down how each works, where each wins, and which to choose for your team.
The short answer
SKILL.md is a portable open standard. A skill is a folder containing a SKILL.md file with YAML frontmatter (name, description, optional fields) and markdown instructions. Skills are loaded on demand. The agent decides whether a skill applies to the current task based on its description, and only loads the full instructions when relevant.
Cursor rules are Cursor-specific configuration. Two main formats: .cursorrules is a single root-level file that applies to every interaction in the project. .cursor/rules/*.mdc is a newer format supporting YAML frontmatter for scoping rules to specific file types or tasks. Rules can be always-on or conditionally loaded.
Pick SKILL.md if you want portability across multiple AI tools or you're building reusable workflows. Pick Cursor rules if you're committed to Cursor and want native integration.
Worth noting: as of Cursor 2.3+, Cursor can also read SKILL.md files from .cursor/skills/ directories and load them as skills. The lines between the two formats are blurring.
Side-by-side comparison
| Dimension | SKILL.md | Cursor rules |
|---|---|---|
| Supported by | Claude Code, Codex CLI, OpenClaw, Cursor (partial), and others | Cursor only (natively) |
| File location |
~/.claude/skills/<n>/SKILL.md (personal) or .claude/skills/ (project) |
.cursorrules (root) or .cursor/rules/*.mdc (newer) |
| Format | Markdown with YAML frontmatter | Plain text (.cursorrules) or Markdown with frontmatter (.mdc) |
| Loading | On demand, agent decides based on description | Always-on (.cursorrules) or conditional via frontmatter (.mdc) |
| Scoping | Via description (semantic match) | Via frontmatter: alwaysApply, globs, description
|
| Structure | Folder with SKILL.md + optional scripts/, references/, assets/ | Single file (.cursorrules) or folder with multiple .mdc files |
| Ecosystem | Thousands of skills across marketplaces and GitHub | Large community collection, no official marketplace |
| Portability | High (copy file to another agent's directory) | Low (Cursor-specific) |
| Precedence | Skills are agent-decided | Rules win when they conflict with skills in Cursor |
How SKILL.md works
A SKILL.md file has two parts: YAML frontmatter with metadata, and markdown instructions for the agent.
name: commit-message-writer
description: Use when the user asks for a commit message or to commit changes. Writes conventional commit messages based on the staged diff.
When asked to write a commit message:
Run git diff --staged to see what's changed
Classify the change type (feat, fix, refactor, docs, etc.)
Write a one-line summary under 72 characters
If the change is non-trivial, add a body explaining the why
Use present tense, imperative mood ("Add feature" not "Added feature")
The agent doesn't load this skill into every conversation. It loads the metadata at startup, and when a user's message matches the description, the full skill instructions get loaded. This progressive disclosure keeps context windows efficient.
Skills live in well-known directories by convention:
-
~/.claude/skills/<n>/SKILL.md— personal skills for Claude Code -
.claude/skills/<n>/SKILL.md— project-scoped skills, checked into the repo -
~/.openclaw/skills/— OpenClaw -
~/.codex/skills/— Codex CLI -
.cursor/skills/— Cursor (partial support)
A skill you write for one agent generally works on the others by copying the file to the right directory.
How Cursor rules work
Cursor has two rule formats in active use:
.cursorrules (legacy but still widely used) is a single file at the project root. It applies to every interaction in the project. No frontmatter, no conditional loading. Just instructions the agent always follows.
.cursor/rules/*.mdc (newer) supports multiple rules files, each with YAML frontmatter controlling when the rule applies.
description: TypeScript-specific conventions for this project
globs: "/.ts,/.tsx"
alwaysApply: false
Prefer named exports over default exports
Use strict null checks; no non-null assertions
Document exported functions with TSDoc
The globs and alwaysApply fields give you explicit control over when a rule loads. Without them, the agent uses the description to decide if the rule is relevant to the current task. That's less reliable than the explicit frontmatter controls.
Where SKILL.md wins
Portability across tools. If you write a skill for Claude Code, it works on Codex CLI and OpenClaw by copying the file. For teams that use multiple agents or might switch tools in the future, this portability is valuable. Cursor rules are Cursor-specific.
On-demand loading by default. Skills load only when the agent determines the description matches the task. This keeps every conversation's context window clean and focused.
Larger ecosystem. SKILL.md has the largest ecosystem of portable skills today. Anthropic's official marketplace, community marketplaces like Agensi with security scanning and curation, and thousands of skills on GitHub via the filename:SKILL.md search. Cursor rules have a strong community (PatrickJS/awesome-cursorrules is popular) but no centralized marketplace.
Structured skill packages. A skill can be a folder containing scripts, reference docs, and assets alongside the SKILL.md. This makes skills genuinely portable units that include everything the agent needs.
Cross-agent investment. Time invested in writing SKILL.md skills compounds across any compatible agent. If your team uses Claude Code today and Codex tomorrow, skills follow.
Where Cursor rules win
Native Cursor integration. Rules are built into Cursor from the ground up. They're tightly integrated with the agent's decision loop and the IDE's workflow. SKILL.md support in Cursor exists but is less mature.
Simple always-on application. For "this is how we write code in this project" instructions that should apply to every interaction, .cursorrules at the project root is the simplest possible format. Write instructions, save the file, done.
Explicit scoping control. The newer .mdc format gives you explicit control: alwaysApply: true for must-apply rules, globs: "*.tsx" for file-type-specific rules. This is more reliable than SKILL.md's semantic description matching for rules you need the agent to follow consistently.
Better for project conventions. Rules are ideal for encoding team-wide conventions that apply across all work in a project — coding standards, architectural patterns, documentation requirements. These don't benefit from on-demand loading because they apply universally.
The real distinction: rules vs skills
Testing by the community has surfaced a useful mental model for when to use which:
Rules are for always-on conventions. "Use early returns." "Prefer named exports." "Write tests for all new functions." These are instructions the agent should always follow. Rules (especially with alwaysApply: true) guarantee this.
Skills are for on-demand workflows. "When asked for a commit message, do X." "When reviewing a PR, check Y." "When diagnosing environment issues, run Z." These are procedures that apply to specific tasks, not to every interaction.
If you're working in Cursor and have a team convention that should apply always, use a rule. If you have a procedure that should run when invoked, use a skill. Or both — Cursor supports both.
For teams not committed to Cursor, SKILL.md gives you portability for the procedures, and you can encode conventions in a project-scoped SKILL.md that's always-on-by-description.
When rules and skills conflict
If you have a rule and a skill that give contradictory instructions, community testing has shown rules win in Cursor. The agent cites the rule file and ignores the skill. Don't encode the same instruction in both formats with different content — you'll confuse the agent.
When to pick which
Pick SKILL.md if you:
- Use Claude Code, Codex CLI, or OpenClaw as your primary agent
- Want portability across multiple AI tools
- Are building task-specific workflows (commit messages, code review, migrations)
- Want access to existing marketplaces (Agensi, Anthropic's official marketplace, community GitHub repos)
- Need to package scripts or reference docs alongside instructions
Pick Cursor rules if you:
- Use Cursor as your primary (or only) AI coding tool
- Need always-on team-wide conventions
- Want explicit control over when rules load (via
globs,alwaysApply) - Value native integration over portability
Use both if you:
- Use Cursor but want to benefit from the SKILL.md ecosystem (Cursor reads SKILL.md from
.cursor/skills/) - Have project conventions (rules) plus task-specific workflows (skills)
The verdict
SKILL.md is the portable open standard. Cursor rules are a native, Cursor-specific system with excellent always-on behavior. If portability matters, SKILL.md wins. If you're committed to Cursor and want maximum native integration, rules win. Many teams end up using both — rules for conventions, skills for workflows.
The good news: with Cursor now reading SKILL.md files from .cursor/skills/, the choice isn't permanent. You can start with rules and add SKILL.md skills as you build out your workflow automation, keeping the portability door open.
Browse curated SKILL.md skills at Agensi. All skills work across Claude Code, OpenClaw, Cursor, Codex CLI, and other compatible agents.
Top comments (0)