#Rules and Skills

Rules inject persistent instructions into Agent context. Skills are portable task packs (instructions plus optional scripts / references). Manage both from Customize, or keep them in the repo for the team. Official pages: Rules and Agent Skills.

#Four kinds of rules

Rules are not memory between completions—when they apply, their text is prepended to the model context. Officially: rules do not affect Tab, and user rules do not apply to inline edit (Ctrl+K / Cmd+K), only to Agent (Chat).

Precedence on conflict: Team Rules → Project Rules → User Rules. Compatible rules are merged.

#Project Rules: .mdc, not a random .md

Only .mdc files with frontmatter in .cursor/rules are recognized. A plain .md is ignored (no description / globs / alwaysApply). Prefer AGENTS.md for unstructured markdown.

.cursor/rules/
  react-patterns.mdc
  api-guidelines.md          # ignored (wrong extension)
  frontend/
    components.mdc

Create them with:

• /create-rule in Agent, then describe the rule
• Customize → Rules → Add Rule

---
alwaysApply: true
---

- When unsure, read the relevant source before editing
- Never modify generated files under `dist/` or `build/`

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Named exports only; no default exports
- Extract a sibling component when a file exceeds 200 lines

---
description: RPC service conventions for the backend
alwaysApply: false
---

- One service file under `src/services/`
- Validate at the boundary; return `{ code, message }` errors

Comma-separate globs: docs/**/*.md, docs/**/*.mdx. Point at canonical examples with @filename.ts instead of pasting a whole style guide.

Official guidance: keep a rule under ~500 lines; split large ones; add a rule only after Agent repeats a mistake. Check rules into Git.

#User rules and AGENTS.md

User rules are short, cross-project preferences:

Reply in concise English. No filler. Prefer libraries already in the repo.

AGENTS.md at the repo root is enough. Nested files stack, with more specific winning:

# Project instructions

- TypeScript for new files
- Business logic stays in the service layer

You can import remote .mdc files from GitHub (Customize → Add Rule → Remote Rule). They usually land under .cursor/rules/imported/.

#Skills: a folder plus SKILL.md

A skill is an Agent Skills folder: one SKILL.md, optional scripts/, references/, assets/. Cursor discovers them at startup. Agent applies them from the description, or you type / and search by name. A / invoke attaches to that message; keep it for the whole session with Opt+Enter (macOS) or Alt+Enter (Windows) as a Custom Mode.

In a monorepo, a skill closer to a package is scoped like paths.

---
name: my-skill
description: Short description of what this skill does and when to use it.
---

# My Skill

When to use:

- ...

Instructions:

- ...

name must match the parent folder (lowercase, digits, hyphens). Optional: paths (file scope), disable-model-invocation: true (only when you type /skill-name).

Marketplace / plugin skills install from Customize; teams can distribute from the Dashboard. Built-in skills change—trust the / menu (/create-rule, /create-skill, /loop, /review, …).

#Align with CLAUDE.md and AGENTS.md

If teammates also use Claude Code or Codex:

Put shared conventions (test commands, folder bounds, bans) in root AGENTS.md. Keep Cursor-only glob / alwaysApply behavior in .mdc. Cursor reads Claude / Codex skill directories; the reverse is not a full guarantee—keep one source of truth for repeated “oral rules.”

#Minimal committable example

# repo root
New-Item -ItemType Directory -Force -Path .cursor\rules, .cursor\skills\pr-checklist | Out-Null

mkdir -p .cursor/rules .cursor/skills/pr-checklist

Save the alwaysApply rule as .cursor/rules/repo.mdc and a SKILL.md under .cursor/skills/pr-checklist/ (name: pr-checklist). Commit, then tell Agent: Follow the pr-checklist skill before you edit.

#Next

• MCP
• Workflow with CLI Agents
• Agent