SKILL.md vs .cursorrules: Agent Instruction Formats Compared

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 — how do you codify "this is how we write code here" — 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

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:
1. Run `git diff --staged` to see what's changed
2. Classify the change type (feat, fix, refactor, docs, etc.)
3. Write a one-line summary under 72 characters
4. If the change is non-trivial, add a body explaining the why
5. 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/<name>/SKILL.md — personal skills for Claude Code
• .claude/skills/<name>/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 — but this is 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)

Browse SKILL.md skills

Agensi curates and distributes security-scanned SKILL.md skills that work across all compatible agents. Browse the catalog at agensi.io/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.