The Confusion: Two Files, Two Jobs, One Context Window

If you've opened Cursor recently and stared at two different customization panels — one asking for .mdc rule files, the other for SKILL.md packages — you're not alone. Cursor now offers Rules and Skills as separate mechanisms for shaping agent behavior, and the documentation doesn't spell out when to use which.

The confusion is understandable, but the stakes are real. Rules are not a niche experiment — they're an established, widely studied practice. The first large-scale academic study of developer-authored rule files analyzed 401 open-source repositories and found 1,876 .mdc files, averaging 4.68 per repository. Adoption is remarkably consistent, too: 93.27% of the repositories studied placed their rules in the .cursor directory at the repo root, suggesting the community has already converged on a standard layout.

So what's actually different? Cursor's own framing is the clearest starting point: Rules provide static context included in every conversation, while Skills are loaded dynamically when the agent decides they're relevant. One practitioner captures it memorably — "Skills are invokable verbs; AGENTS.md and rules are ambient adjectives." Rules describe the ambient conditions of your project; Skills perform work on demand.

The distinction matters because context isn't free. The same academic research warns that "excessive or unoptimized context can lead to more complex and less accurate responses, as well as higher costs and latency." Every always-on rule you add taxes every prompt you send, whether or not it's relevant to the task at hand. Skills, by contrast, use progressive disclosure — their resources load only when needed, keeping the context window clean.

Getting the choice wrong has three costs:

• Accuracy degradation from bloated, always-present context competing for the model's attention
• Higher token costs, since always-applied rules ship with every request
• Added latency as the model processes context it never needed

Cursor itself seems to agree the future leans toward Skills — its best-practices guidance recommends Agent Skills as the preferred way to extend agent behavior. But rules aren't going anywhere. Cursor's own migration tool, /migrate-to-skills, deliberately refuses to convert rules with alwaysApply: true or glob patterns, because "they have explicit triggering conditions that differ from skill behavior." Always-on and path-scoped enforcement still requires rules.

There's also a quality dimension worth watching. As Skills become the preferred extension mechanism — and as teams increasingly pull third-party skills rather than writing their own — knowing which packages actually help (and which carry risk) becomes its own problem. That's the gap SkillzBench is being built to address: an independent testing lab that benchmarks agent skills in a sandbox, measures the lift each one delivers, and scores them for security and quality. Because when the difference between a rule and a skill comes down to what loads when, you deserve evidence about what's worth loading at all.

The Core Distinction: Ambient Adjectives vs. Invokable Verbs

Both mechanisms customize how an AI coding agent behaves, but they operate in fundamentally different ways. Rules are persistent, machine-readable directives that Cursor includes at the start of the model context when applied — "large language models don't retain memory between completions," the company explains, so rules provide persistent, reusable context at the prompt level. Skills, by contrast, are portable, version-controlled packages built around a SKILL.md file that load only when the agent decides they're relevant.

Cursor draws the line explicitly: "Unlike Rules which are always included, Skills are loaded dynamically when the agent decides they're relevant. This keeps your context window clean while giving the agent access to specialized capabilities," according to its agent best practices guide. One practitioner framing makes the distinction memorable: "Skills are invokable verbs; AGENTS.md and rules are ambient adjectives."

Rules come in four types — Project Rules (version-controlled .mdc files in .cursor/rules/), User Rules, Team Rules, and AGENTS.md — and four application modes: Always Apply, Apply Intelligently, glob-based file matching, and manual @-mention. These aren't niche conventions. The first large-scale academic study of the practice analyzed 401 open-source repositories and found 1,876 rule files, averaging 4.68 per repo, with 93.27% of repositories placing them in a .cursor directory.

Skills behave differently by design. Each is a folder containing a SKILL.md file with a name and description, plus optional scripts, templates, and references the agent can act on with its tools. They're progressive: resources load on demand rather than sitting in the context window, and they follow an open standard that works across agents — while rules remain Cursor-specific.

• Rules set the ambient context — always-on constraints, path-scoped conventions, project background the agent sees from the start.
• Skills deliver full-depth capability — workflows, executable scripts, and templates triggered by relevance, not by every conversation.
• As one practitioner puts it: "Rules decide when the surface is in play; skills decide what good looks like at full depth."

Cursor's own migration tool proves the boundary. Cursor 2.4's /migrate-to-skills converts dynamic rules and slash commands into Skills, but deliberately refuses rules with alwaysApply: true or glob patterns, "as they have explicit triggering conditions that differ from skill behavior."

The distinction matters beyond semantics. Because Skills can carry executable scripts and are becoming Cursor's preferred extension mechanism, their quality and safety directly affect your agent's behavior — and published research found roughly 26% of skills carry at least one vulnerability. That's the gap SkillzBench is building for: verifying, benchmarking, and scoring skills so teams can adopt the invokable verbs with confidence. Skills, proven — join the waitlist to see which ones actually lift your agents.

Proof in the Migration Tool: Where Cursor Draws the Line

If you want to know where Cursor truly draws the line between Rules and Skills, don't read the marketing — read the migration tool. Cursor 2.4's built-in /migrate-to-skills command converts dynamic rules and slash commands into Skills, but it deliberately refuses to migrate rules with alwaysApply: true or glob patterns. The reason Cursor gives is telling: "they have explicit triggering conditions that differ from skill behavior."

That's the vendor itself confirming the boundary. Skills are loaded dynamically when the agent decides they're relevant, keeping the context window clean; rules with always-on or glob-based triggering are a fundamentally different mechanism that Skills cannot replicate. The migration tool's refusals aren't a limitation — they're a precise map of what each construct is for.

This creates a genuine strategic tension. Cursor's agent best practices guide officially recommends Agent Skills as the preferred way to extend agent behavior, yet the same company ships a tool that won't touch always-on and path-scoped rules — because those rules remain necessary. If you need a constraint enforced on every conversation, or auto-attached whenever a matching file is edited, a Skill's description-triggered loading simply won't do.

In practice, the two coexist as complementary layers rather than rivals. A common pattern, described by practitioners, uses a rust.mdc glob rule that matches **/*.rs files and links to a rust/SKILL.md holding the full criteria. As one practitioner puts it: "Rules decide when the surface is in play; skills decide what good looks like at full depth." The rule handles triggering; the Skill carries the depth. It's the same division captured in the memorable framing that "Skills are invokable verbs; AGENTS.md and rules are ambient adjectives."

The wider ecosystem reinforces this layered view:

• AGENTS.md provides ambient project context, adopted by 20,000+ open-source repositories and backed by OpenAI Codex, Cursor, Aider, Zed, and 20+ other tools.
• Skills supply invokable, portable workflows — an open standard that works across Claude Code, Codex, Cursor, and Gemini CLI.
• MCP handles live data access, connecting agents to external systems.

As the practitioner analysis concludes, these are "three layers, not three competitors."

The layering matters for quality, too. As Skills become the preferred extension mechanism — and as they can carry executable scripts — the risk surface grows. Published research found that roughly 26% of agent skills carry at least one vulnerability, which is why independent verification and benchmarking of skills is becoming essential infrastructure. That's the gap SkillzBench is building to close: pinning every skill version to a commit SHA, security-scanning, and benchmarking each skill in a sandbox to measure its Lift — so teams can adopt the Skills era with confidence. Skills, proven.

Putting It to Work: Rules for Guardrails, Skills for Capabilities — and Why Provenance Matters

Knowing the rules-vs-skills distinction is one thing; putting it to work is where most teams stumble. The good news is that Cursor's own guidance is refreshingly pragmatic: start simple, and only add structure when reality demands it.

Cursor's official best practices are direct: keep rules under 500 lines, start with a minimal setup, and add a rule only when the agent makes the same mistake repeatedly (per Cursor's agent best practices). Reference files by path instead of pasting their contents into context, since the first large-scale study of rule files warns that excessive, unoptimized context produces more complex, less accurate responses — plus higher costs and latency.

Trigger.dev's field lessons add practitioner depth. When they explicitly pinned SDK versions in their rules, the agent stopped generating code for older versions. Complete task examples outperformed isolated snippets, and explaining the why behind a pattern helped the agent adapt to edge cases rather than parrot syntax (see their writeup on Cursor rules).

A quick checklist for teams starting out:

• Keep always-on rules lean — under 500 lines, per Cursor's docs
• Add a rule only after the agent repeats the same mistake
• Pin SDK versions explicitly to prevent stale code generation
• Prefer complete task examples over isolated snippets
• Reference files by path instead of copying contents into context

Here's the tension, though: Cursor now recommends Skills as the preferred way to extend agent behavior — and Skills can carry executable scripts, not just instructions. That shifts the risk surface. Published research found roughly 26% of agent skills carry at least one vulnerability, and Cursor itself cautions that AI guidance should never be your only security control.

That's why provenance matters. SkillzBench is being built as an independent testing lab for exactly this problem: verifying every skill version against a pinned commit SHA, security-scanning and license-checking each package, and benchmarking skills in a sandbox — testing the same model with and without the skill, then publishing the Lift in percentage points. Its per-agent loadouts mean an agent only sees the skills and tools you've explicitly toggled on, and upstream changes get tracked, re-scanned, and flagged as they happen.

The result is a simple division of labor: rules for guardrails, skills for capabilities — and evidence, not guesswork, deciding which skills earn a spot in your loadout.