Cursor Prompts for Codebase Agents: Rules That Stick Across Chats

Cursor prompts that stick across chats live in files, not in your chat history. Project rules in .cursor/rules, AGENTS.md at the repo root or in subfolders, and Agent Skills in .cursor/skills load into new chats without you retyping them. You leave with a map of where each durable instruction belongs, the four rule activation types, templates for an always-on rule, a scoped rule, an AGENTS.md, and a SKILL.md workflow, plus a test loop that proves the agent read them. Per-task briefs for one multi-file job live in a sibling guide, so this page stays on the durable layer. Soft path: https://promptmake.net/skills drafts SKILL.md text you commit yourself.

What cursor prompts for codebase agents need to survive

A new Cursor chat starts with only what Cursor loads for you: rules, AGENTS.md, and skill descriptions. Anything you typed in last Tuesday's chat is gone. If you paste the same "use pnpm, not npm" line into chat five times a week, that line belongs in a file.

Durable prompts split into two jobs. Conventions tell the agent how this repo works: stack, folder layout, test command, naming. Workflows tell the agent how to run a repeatable job, such as adding a migration or writing a changelog entry. Conventions go in rules or AGENTS.md. Workflows go in skills.

Scope note: https://promptmake.net/blog/cursor-ai-prompts-guide tours Chat, Agent, and rules as surfaces. https://promptmake.net/blog/cursor-agent-brief-prompts covers the spec you write for one multi-file task. This page covers the layer under both, the files that make each brief shorter.

Facts here match the Cursor docs as of September 2026. Cursor renames settings often, so open cursor.com/docs/rules before you roll templates out to a team.

Four places a durable Cursor prompt can live

Cursor reads persistent instructions from several sources, and each one has its own scope and trigger. Picking the wrong home explains most rules that seem ignored. A workflow buried in an always-on rule bloats each chat, while a convention hidden in a skill never loads for a quick question. Sort each instruction with two questions. Does it apply to the whole repo or one folder? Does the agent need it on each turn or only for one kind of job? The answers point to one of the four homes below. Commit the project-level files to git so teammates and background agents read the same text you do.

Project rules in .cursor/rules

The .cursor/rules folder holds .mdc files: Markdown with a small YAML frontmatter block of description, globs, and alwaysApply. Cursor's rules system ignores a plain .md file in that folder because it has no frontmatter. Rules live in version control and can target paths, so a rule for app/api stays out of chats about CSS. A legacy .cursorrules file at the repo root still loads in many setups, but new work belongs in .cursor/rules.

AGENTS.md at the root and in subfolders

AGENTS.md is plain Markdown with no frontmatter. Cursor reads it at the project root and in subdirectories, and a nested file applies when the agent works on files in that folder. Other coding agents read AGENTS.md too, which makes it the portable home for repo basics: install, test, and lint commands. Pick it when you want one readable file instead of a folder of scoped rules.

User rules and team rules

User rules sit in Cursor Settings and follow you across projects. Put personal taste there, such as answer tone or explanation length. Team rules live in the Cursor dashboard on paid team plans and apply to the whole org. Keep repo-specific facts out of both, since a teammate on another repo will receive them.

Agent Skills in .cursor/skills

A skill is a folder with a SKILL.md file: a name, a description, and step-by-step instructions. The agent loads the body when the description matches the task, or when you type /skill-name. Cursor also reads .agents/skills and the Claude-compatible .claude/skills folder. Cursor retired the older .cursor/commands slash files in favor of skills, and the built-in /migrate-to-skills command converts them. Existing command files keep loading for now.

Choose the right rule type for each instruction

Each project rule gets one of four activation types from its frontmatter, and the type decides whether the agent sees the rule at all. Always Apply sets alwaysApply to true and loads the rule into each chat. Apply to Specific Files sets globs and loads the rule when matching files enter context. Apply Intelligently leaves globs empty, adds a description, and lets the agent judge relevance from that description. Apply Manually loads only when you @-mention the rule, such as @api-routes. Most repos need one short always-on rule, a handful of glob rules, and few manual ones. Match the type to how often the agent needs the text.

Always Apply: keep it under 30 lines

Reserve always-on for facts that matter in any chat: package manager, test command, language version, and hard bans such as "do not edit generated files in src/gen." Each always-on line costs context in each request. If a line only matters for database work, move it to a glob rule.

Globs and descriptions work as triggers

Globs should match real paths, such as app/api/**/*.ts or prisma/**. For Apply Intelligently rules, the description is the only text the agent reads before it decides, so write it as a trigger: "Use when adding or changing Prisma models or migrations." A vague description like "Database stuff" loads at random or not at all. Cursor's /migrate-to-skills converts Apply Intelligently rules into skills, a hint that description-triggered guidance fits the skill format.

Imperative bodies beat essays

Write rule bodies as short commands: "Use server actions for mutations. Return typed errors. Add a Vitest test next to each new util." Give one small example when the pattern is not obvious from the code. Skip background essays about why the team chose a library. The agent needs the instruction, and you pay context for the history.

Paste-ready rule, AGENTS.md, and skill templates

Copy these into your repo, swap the brackets, and commit. Keep each file on one concern so you can tell which file changed the agent's behavior. The frontmatter lines go between two lines of three dashes at the top of each file. Everything after the closing dashes is the body the agent reads. Start with Template 1 and Template 3 on day one, then add scoped rules and skills when you catch yourself repeating an instruction in chat for the third time. Small, focused files are easier to test and easier to delete when a folder goes away.

Template 1: always-on core rule

File: .cursor/rules/core.mdc. Frontmatter: description: Core conventions for [repo name] and alwaysApply: true.

Body: "Package manager: pnpm. Run pnpm test and pnpm lint before you report a task as done. TypeScript strict mode, no any. Do not edit files in [generated folder]. Ask before adding a dependency. Change only the files the task needs, and list them in your summary."

Template 2: scoped rule for one folder

File: .cursor/rules/api-routes.mdc. Frontmatter: description: Conventions for API route handlers, globs: app/api/**/*.ts, and alwaysApply: false.

Body: "Validate input with zod at the top of each handler. Return JSON errors as { error: string, code: string }. Read the session with getSession from lib/auth, never from headers. Add a test in tests/api for each new route."

Template 3: AGENTS.md for the repo root

"# [Repo name]. Setup: pnpm install. Test: pnpm test. Lint: pnpm lint. Layout: app holds routes, lib holds shared logic, db holds schema and migrations. Conventions: named exports, one component per file, tests next to source. Off limits: .env files, db/migrations that already shipped, anything under vendor."

Nested example for packages/billing/AGENTS.md: "This package talks to the payment provider. Use the client in billing/client.ts. Amounts are integers in cents. Do not call live endpoints in tests; use the fixtures in billing/fixtures."

Template 4: SKILL.md for a repeatable workflow

File: .cursor/skills/add-migration/SKILL.md. Frontmatter: name: add-migration and description: Use when the user asks to add or change a database table, column, or index.

Body: "1. Edit prisma/schema.prisma. 2. Run pnpm prisma migrate dev --name [short-name]. 3. Update the matching types in lib/db. 4. Run pnpm test. 5. Stop and report the new migration file path. Do not run migrate reset or edit migrations that already shipped."

Test that the agent reads your rules

Rules fail without warning. The agent does not tell you it skipped a file, so you need a short check each time you add or change one.

1. Open a new chat. Old chats keep the context they started with.
2. Ask a question the rule answers: "Which command runs the tests here?" The agent should answer from core.mdc or AGENTS.md.
3. Hover the context indicator in the chat input to see which rules loaded. Glob rules appear once a matching file enters context.
4. Give a small task that tempts a violation, such as "add lodash to format dates." A working rule makes the agent ask first.
5. When a rule misses, fix the trigger before you add words. Most misses trace back to a wrong glob or a vague description.

Review rules each month or after a big refactor. Delete lines that describe folders you removed. The agent trusts stale rules, so an outdated path in core.mdc sends it to the wrong place with confidence.

Common mistakes with cursor rules and prompts

• Writing one 400-line always-on rule. Split it into a short core rule and scoped files.
• Saving rules as plain .md files inside .cursor/rules. Use .mdc with frontmatter, or move the text to AGENTS.md.
• Copying the same fact into AGENTS.md, core.mdc, and user rules. The copies drift apart after the first edit.
• Putting sprint work in rules. "Refactor checkout this week" belongs in a task brief, covered in cursor-agent-brief-prompts.
• Pasting API keys or customer data into rules. Rules get committed to git and sent to the model.
• Expecting rules to steer Tab completions. Rules shape Agent chats; Tab runs on its own.
• Keeping legacy .cursor/commands files forever. Run /migrate-to-skills and review the skills it writes.

Draft skill and rule text with PromptMake /skills

Describe the workflow in plain words: what triggers it, which files it touches, which command proves it worked, and where it must stop. Paste that into https://promptmake.net/skills. The generator returns a SKILL.md with a trigger-rich description and an imperative body. It targets Claude Agent Skills, Custom GPTs, and Gemini Gems, and Cursor reads the same SKILL.md format from .cursor/skills. Commit the output as a skill, or lift the body into an .mdc rule when you want glob scoping.

PromptMake generates text only. It does not open Cursor, read your repo, or upload anything. As of September 2026, guests get about three free generations per day per tool and registered free accounts about five. For a one-off task brief, https://promptmake.net/text fits better than the skills tool.

FAQ

What are cursor prompts for codebase agents?

They are instructions stored in files that Cursor loads into new chats: project rules, AGENTS.md, and Agent Skills. They carry repo conventions and repeatable workflows so you stop retyping them. Chat messages hold the task of the moment. Files hold what stays true across tasks.

Should I use .cursor/rules or AGENTS.md?

Use AGENTS.md for repo basics that other coding agents should read too, such as setup and test commands. Use .cursor/rules when you need glob scoping or description-based loading for one part of the codebase. Many teams keep both: a short AGENTS.md plus a few scoped .mdc rules. Avoid copying the same fact into both files.

Why does Cursor ignore my rule?

Check the file extension first, since .cursor/rules expects .mdc files with frontmatter. Then check the glob against real paths and read the description as the agent would. Open a new chat, because old chats do not reload rules. If the rule is long, trim it; a short rule with a clear trigger loads more reliably than an essay.

What happened to .cursor/commands?

Cursor moved reusable slash workflows to Agent Skills. The built-in /migrate-to-skills command converts old command files into skills that you still trigger by typing a slash name. Existing command files keep loading for now. Write new workflows as SKILL.md folders in .cursor/skills.

How long should a Cursor rule be?

Keep an always-on rule under about 30 lines and a scoped rule under about 50. Cursor's own guidance favors short, focused rules with one concern each. Long rules cost context on each request and bury the lines that matter. Split by folder or job when a file grows.

Can PromptMake write Cursor rules for me?

Yes, as text. https://promptmake.net/skills drafts SKILL.md files, and you can reuse the body in an .mdc rule or AGENTS.md. You review the output, save it in your repo, and commit it yourself. PromptMake never connects to Cursor or your codebase.

How is this different from cursor-agent-brief-prompts?

Cursor-agent-brief-prompts covers the one-time spec you write for a multi-file task: goal, fence, verify, and stop. This page covers the durable layer that loads before any brief. Good rules make briefs shorter because the brief no longer repeats stack and test commands. Use both together.