Cursor Rules vs Skills
Pick what you need. Standing conventions belong in Rules. Repeatable workflows belong in Skills. Long reference text stays in local Markdown you `@`-mention. Simple project notes can live in AGENTS.md.
Cursor docs checked 2026-09-15.
Replacing @Docs? See What happened to @Docs in Cursor?
What are you trying to encode?
Use Rules
Rules are for persistent instructions that should apply Always or on path globs every session.
Do now: Add a short `.cursor/rules/*.mdc` rule. Prefer Always Apply or globs. Keep it under a few hundred lines; point at files instead of pasting whole style guides.
Example: “Never commit `.env`. Use named exports in `src/components/**`.”
Side-by-side
| Mechanism | Purpose | Where | When it applies |
|---|---|---|---|
| Rules | Persistent instructions the Agent includes when the rule applies. | Project `.cursor/rules/*.mdc`, User rules, Team rules | Always, by glob, or manually — depending on the rule type |
| AGENTS.md / CLAUDE.md | Plain markdown project instructions without rule frontmatter. | Repo root (and nested folders); CLAUDE.md documented for Cursor CLI | Loaded as agent instructions; more specific nested files win |
| Skills | Portable packages (`SKILL.md`) for domain workflows the agent loads when relevant or via `/skill-name`. | Skill folders with `SKILL.md`, optional `scripts/`, `references/`, `assets/` | When relevant, or when you invoke `/skill-name` |
| Local Markdown | Reference files in the repo you `@`-mention or let the agent open — not a separate Cursor product surface. | `docs/`, guides, OpenAPI dumps, design notes | On demand when mentioned or opened — not always-on context |
- Rules example: Always use named exports under `src/components/**` (glob rule).
- AGENTS.md / CLAUDE.md example: How to run and debug the three main services in this monorepo.
- Skills example: Deploy to staging with `scripts/deploy.sh` and a when-to-use description.
- Local Markdown example: Keep the API reference in `docs/api.md` and `@docs/api.md` when changing endpoints.
Sources
- Cursor docs — Rules
- Cursor docs — Skills
- Cursor docs — Customize
- Cursor docs — AGENTS.md
- Cursor docs — CLI using (CLAUDE.md)
Local Markdown is workspace files plus `@` mentions — not a separate Cursor product page. Commands are a different Customize surface and are out of scope here.
