Rules vs AGENTS.md vs Skills
Three mechanisms steer agents in a repo. They overlap in name but not in job: rules set defaults, AGENTS.md is the portable contract, skills are task playbooks.
Last reviewed: June 2026
Loading behavior and file locations change between Cursor, Claude Code, and Copilot releases. Verify in Cursor Rules docs and Agent Skills docs.
At a glance
| Mechanism | Location | Loads when | Carries |
|---|---|---|---|
| AGENTS.md | Repo root | Most agents read it at session start | Stack, commands, conventions, protected paths |
| Cursor rules | .cursor/rules/*.mdc | Cursor sessions; optional glob scoping | Same as AGENTS.md, plus path-specific overrides |
| Skills | .cursor/skills/<name>/SKILL.md | When description matches task or you invoke /name | Repeatable workflows — review, release, migrations |
Rule of thumb: If every session needs it → rules or AGENTS.md. If only some tasks need it → skill. If the agent needs live data → MCP, not a longer rules file.
AGENTS.md
Single markdown file at the repo root. Tool-agnostic instructions any agent can read.
Good for:
- Stack versions and package manager
- Lint, test, build commands
- Naming and file structure conventions
- Paths agents must not touch
Not good for:
- 500-line security review checklists (use a skill)
- API credentials or connection strings (use env + MCP)
- Tool-specific keyboard shortcuts
See Project Rules for a copy-paste template and team rollout.
Cursor rules (.cursor/rules/)
Cursor-specific rules files with optional frontmatter for glob scoping:
---
description: Markdoc content pages
globs: src/pages/**/*.md
---
- YAML frontmatter required on every page
- Register new pages in src/shared/navigation.js
| Feature | AGENTS.md | .cursor/rules/ |
|---|---|---|
| Path scoping | No | Yes, via globs |
| Multiple files | One file | Many .mdc files by concern |
| Copilot / Claude Code | Often read if present | Cursor-only |
| User-level rules | No | Cursor Settings → Rules (all projects) |
When to split rules: One file for global stack, separate files for src/pages/**/*.md, **/*.test.ts, or infra paths. Keeps token load lower than one megabyte AGENTS.md.
Skills (SKILL.md)
Portable workflow packages. See Agent Skills for full authoring.
| vs Rules | Skills |
|---|---|
| Always in context (rules) | Loaded on demand (skills) |
| "Use TypeScript strict" | "Run this 12-step security review on the diff" |
| ~50–200 lines max per rules file | Can include references/ for depth |
Use paths in skill frontmatter to scope file-specific guidance without polluting global rules:
paths: src/pages/**/*.md
Use disable-model-invocation: true for expensive workflows you only want on explicit /skill-name.
Decision matrix
| You need… | Use |
|---|---|
| "We use App Router, not Pages" | AGENTS.md + .cursor/rules/ |
| "Never edit migrations/" | AGENTS.md protected-paths section |
| Markdoc-only rules for content authors | .cursor/rules/markdoc.mdc with globs |
| PR security review checklist | Skill: security-review |
| Release notes from git log | Skill: release-notes |
| Query staging DB for user lookup | MCP server, not rules |
| Copilot in same repo | .github/copilot-instructions.md mirrors AGENTS.md |
How they compose (without duplication)
AGENTS.md → 50 lines: stack, commands, do-not-touch
.cursor/rules/ → path-specific addenda (tests, content, API routes)
.cursor/skills/ → procedural depth on demand
MCP servers → runtime tools and data
Anti-pattern: Pasting the same security checklist into AGENTS.md, a Cursor rule, and a skill. Pick one home — usually the skill — and link it from CONTRIBUTING.md.
Anti-pattern: Putting stack versions only in a skill. Every session needs stack context in AGENTS.md.
Token budget
| Layer | Typical size | Loaded |
|---|---|---|
| AGENTS.md | 500–2,000 tokens | Every session |
| Each Cursor rule (matched globs) | 200–800 tokens | When globs match open files |
| Skill metadata | ~100 tokens per skill | All skills at startup (names + descriptions) |
| Full skill body | 500–5,000 tokens | When triggered |
Keep AGENTS.md lean. Move procedural depth to skills. See Context Engineering and Tokens and Context.
Team rollout
| Step | Action |
|---|---|
| 1 | Publish AGENTS.md template org-wide |
| 2 | Add .cursor/rules/ for repos using Cursor |
| 3 | Add .github/copilot-instructions.md where Copilot is primary |
| 4 | Introduce skills for gated workflows (review, deploy) |
| 5 | CODEOWNERS on AGENTS.md, .cursor/rules/, .cursor/skills/ |
Link Team AI Policy for approved tools and review gates.