Cursor rules vs AGENTS.md vs skills: where each thing goes

Modern AI coding tools read three kinds of context from your repository: a project brief (AGENTS.md), rules (Cursor’s .cursor/rules/), and skills (SKILL.md folders). They overlap just enough that most projects put the right information in the wrong layer — conventions buried in the brief where they don’t bind, procedures stuffed into rules where they always load, briefs rewritten inside every skill.

Each layer has a distinct loading behavior, and the loading behavior tells you what belongs there.

---

The brief: read at the start, sets the map

AGENTS.md is project context, read when the agent starts working. It answers what is this project: stack and versions, folder map, content schemas, the handful of gotchas. It’s the layer with the widest reach and the least enforcement — the agent absorbs it as background, so it shapes everything a little rather than any one thing strongly.

Belongs here: facts about the project an agent would otherwise guess. Doesn’t belong: task procedures, style rules you want enforced, anything the code answers better itself.

Rules: scoped, constant, enforced

Rules are small and conditional. In Cursor, each rule declares when it applies — always, or when files matching a glob are touched — and attaches automatically. That makes rules the enforcement layer: the place for conventions that must hold on every matching edit, phrased as constraints.

The four I ship with every theme are a global rule (import alias, no drive-by refactors, no invented dependencies), and scoped ones for config, content, and pages. Notice what they have in common: none of them explain the project. They police edits. A rule is a linter written in prose.

Belongs here: “always/never” statements tied to a scope. Doesn’t belong: long explanations — a rule that takes 200 lines has smuggled in a skill.

Skills: loaded on demand, teach a competence

Skills are procedural knowledge with a trigger. The agent sees each skill’s one-line description; when the task matches, the full instructions load. That on-demand loading is what lets a skill afford to be long: a design skill with the full typography, color, and spacing system costs nothing until you ask for UI work.

Belongs here: how to do a kind of task in this project — build on the design system, add a collection entry, cut a release. Doesn’t belong: universal constraints (those are rules) and project facts (that’s the brief).

---

The decision rule

Ask when the information should be in front of the agent:

• Every session, as background? Brief.
• Every edit within a scope, as a constraint? Rule.
• Only for a matching kind of task, as a procedure? Skill.

Two corollaries fall out. First, duplication across layers isn’t harmless: if the brief and a rule disagree after a refactor, the agent picks one and you won’t know which. State each fact once, in its layer, and reference it from the others if needed. Second, the layers fail differently — a stale brief misleads quietly, a stale rule blocks loudly, a stale skill produces yesterday’s patterns. That’s an argument for keeping the brief lean (fewer claims to go stale) and pushing specifics down into the narrower layers.

---

A worked example

Take “we use design tokens from colors.css, never raw palette colors”:

• The brief says tokens live in src/styles/colors.css — a fact about the project.
• A rule says “never use raw Tailwind palette colors in class names” — a constraint on every UI edit.
• The design skill documents the actual scales, what each token is for, and the do/don’t list — the competence, loaded when building UI.

Same policy, three layers, no duplication: the fact, the constraint, the craft.

Every Lexington theme ships all three, extracted from the theme’s real code. The posts on each layer: AGENTS.md, the four Cursor rules, and the design skill. The method for building your own set is Making Your Codebase AI-Ready.