an efficient .cursor directory: less context, better agents

how to structure your .cursor directory so agents start with the smallest useful context, spend fewer tokens, and produce faster, more focused results

i spent time recently reorganizing how my repositories load cursor context. the old setup worked, but it was heavy. every agent turn started with a large bundle of rules, duplicated guidance, and inventories the model did not need for most tasks.

the new setup is deliberately smaller. agents still find what they need, but they pay for less context up front. that means lower token cost, less time waiting for the model to "read the room", and answers that stay closer to the task i actually asked for.

if you already have my cursor setup in place, think of this post as the next layer. that post covers the full toolkit. this one covers how to arrange the toolkit so it does not eat your context window before work begins.

quick answer

treat your .cursor directory like a library with a card catalog, not like one giant PDF pasted into every prompt. keep a thin always-on layer for guardrails, route everything else through links, scope detailed rules to the file types they apply to, and load skills on demand. the agent can always open more context when the task requires it, but the default should be the minimum useful baseline.

who this is for

• people who already use cursor rules, skills, or AGENTS.md and notice agents getting slower or noisier over time
• teams whose .cursor folder grew organically and now repeats the same instructions in three places
• builders who care about token cost and want cleaner first responses without giving up deep project knowledge

why this matters

context is not free. every always-on rule, every paragraph in AGENTS.md, and every skill description the system injects up front consumes tokens before the agent writes a single useful line.

that cost shows up in three places:

• money, because larger prompts cost more per turn
• latency, because the model spends time absorbing context you may not have needed for this task
• focus, because a bloated baseline makes it easier for the agent to wander, repeat itself, or "helpfully" expand scope

the counterintuitive part is that less default context often produces better results. when the baseline is tight, the agent has fewer conflicting instructions to reconcile. when it needs sql conventions, it loads sql conventions. when it needs a release checklist skill, it loads that skill. the fetch is intentional instead of accidental.

the problem with a "kitchen sink" .cursor folder

most .cursor directories start sensibly. you add one rule for coding standards. then a skill for your most common workflow. then AGENTS.md grows because you keep answering the same architecture questions. then another rule duplicates half of the first one because you wanted sql-specific guidance.

soon every chat begins like this:

• a long always-on rule with architecture, naming, validation, git policy, and documentation philosophy
• a second always-on rule with overlapping standards
• an AGENTS.md file that restates the same material in prose
• a skill inventory table with fifteen rows, even when you only needed one skill

none of this is wrong in isolation. together it is expensive noise.

the pattern i use now: route, do not restate

the organizing principle is one canonical document per topic, indexes that route rather than restate.

think in layers:

layer 1: a thin AGENTS.md

AGENTS.md should answer two questions quickly:

1. what must never be violated on this repo
2. where do i go next for the task at hand

a useful shape:

# my-repo agent entry

one-paragraph architecture invariant.

## hard constraints

- link to the always-on behavior rule
- link to task-scoped rules
- one line on validation expectations

## route by task

| task                 | canonical source             |
| -------------------- | ---------------------------- |
| local setup          | README                       |
| cursor asset layout  | .cursor/README.md            |
| full skill inventory | .cursor/reference/catalog.md |
| domain architecture  | docs/architecture note       |

what to leave out:

• full skill tables (link to a catalog instead)
• long prose explanations of every layer in your data platform
• step-by-step workflows (those belong in skills)

layer 2: .cursor/README.md as the local index

this file is the map of cursor-native assets. keep it scannable with tables, not essays.

include:

• which rules exist and when they apply
• which skills exist and when to use them
• which subagents wrap parallel work
• where maintenance docs live

tell the agent explicitly when not to load the heavy stuff. a line like "do not open the full catalog unless maintaining assets or the user asks for an inventory" saves tokens repeatedly.

layer 3: split always-on rules from task-scoped rules

this is the highest-leverage change i made.

always-on should mean "behavior and safety", not "every convention in the repository".

my always-on behavior rule covers:

• question before assuming
• prevent scope drift
• keep git user-controlled
• match verification to risk
• documentation philosophy in one short section
• architecture invariants in a few lines

detailed conventions move to glob-scoped rules:

---
description: "sql and model conventions"
globs: "**/*.sql"
alwaysApply: false
---

and:

---
description: "yaml metadata conventions"
globs: "**/*.yml"
alwaysApply: false
---

now a markdown edit does not load sql rules. a yaml edit does not load manuscript rules. the agent gets the right lane without reading every lane at once.

for content-heavy repos, the same idea applies across zones. one rule scoped to website posts, another scoped to book chapters, each with its own glob pattern. the agent loads voice and punctuation rules for the files it is actually touching.

layer 4: skills as on-demand runbooks

skills are powerful because they are procedural and task-bound. that also makes them expensive if you treat them like always-on policy.

keep each skill focused:

• frontmatter description that says when to use it
• required inputs
• ordered steps
• done criteria
• links to canonical reference docs instead of copying them

the agent discovers skills through descriptions and loads the file when the task matches. it should not need the full text of every skill before you say hello.

if you want a template for tightening skill structure, see starter templates for ai rules, skills, and commands.

layer 5: reference files for inventories and contracts

some material is too long to inline but still valuable. put it in .cursor/reference/ and link to it.

good candidates:

• full skill and subagent catalogs
• model or schema contracts
• maintaining-assets runbooks
• shared prose contracts used by multiple rules

each reference file should say at the top when to load it. catalogs especially should warn against opening them on every task.

duplication is the silent token tax

the fastest audit you can run is a duplication pass.

search for the same ideas repeated across:

• AGENTS.md
• always-on rules
• skills
• README files inside .cursor/

common duplicates:

• git policy stated in three places
• architecture overview copied into every rule
• validation commands listed in both a skill and a rule
• full directory trees pasted into prompts

pick one canonical home for each topic. everywhere else, replace the copy with a link.

this also makes maintenance easier. when validation changes, you update one file instead of hunting for stale copies the agent may still believe.

indexing hygiene still matters

token efficiency is not only about rules and skills. it is also about what cursor indexes from the repo.

keep using:

• .gitignore for generated output and dependencies
• .cursorignore for extra exclusions such as build artifacts, minified bundles, and local secrets

less junk in the index means less irrelevant material during semantic search and fewer wrong-file detours.

i covered the basics in my cursor setup under context hygiene. the .cursor directory optimization and indexing optimization work together.

let the agent fetch, but make fetching intentional

a lean baseline does not mean a ignorant agent. it means the agent starts focused and expands deliberately.

patterns that work well:

• @Files and @Folders when you already know where the answer lives
• task-scoped rules that attach automatically when the agent edits matching files
• skills the agent opens because the task description matches the skill's description
• reference catalogs opened for maintenance, inventory questions, or ambiguous workflow choice

patterns that waste tokens:

• pasting entire directories into always-on instructions
• writing "read all docs before doing anything" into a rule
• creating five always-on rules because you could not decide which one was canonical

the model is good at retrieval when you give it a map. it is worse when you give it the whole encyclopedia and ask it to find page one.

a practical migration path

you do not need a weekend rewrite. this sequence worked for me:

1) inventory what loads every turn

list:

• rules with alwaysApply: true
• large sections of AGENTS.md
• any skill or subagent list inlined in an always-on file

ask for each item: "did i need this on a generic question about yesterday's pull request?"

2) rewrite AGENTS.md as a router

keep hard constraints and a route-by-task table. move everything else behind links.

3) collapse always-on behavior into one thin rule

merge overlapping guardrails. link out to collaboration preferences or behavioral skills instead of copying them.

4) extract task-scoped rules with globs

sql, yaml, typescript, website markdown, book markdown, ci workflows. each gets its own scoped rule if the guidance is non-trivial.

5) move inventories to reference files

catalogs, contracts, and maintenance guides live under .cursor/reference/. add a "when to load" note at the top.

6) dedupe and delete

if two files say the same thing, pick a winner and remove the loser. stale duplicates are worse than missing docs because they look authoritative.

7) test with three prompts

run these after the refactor:

• a generic task outside your specialty rules (should stay fast and focused)
• a file-type-specific task (should pull the right scoped rule without you mentioning it)
• a maintenance task such as "add a new skill" (should route to the catalog or maintaining doc)

what improved after the refactor

the differences are subtle per turn but add up quickly:

• first responses arrive with less preamble and less repeated policy quoting
• sql tasks stop inheriting markdown voice rules and vice versa
• token spend on routine edits dropped because the baseline shrank
• when an agent does expand scope, it is usually because the task actually required more context, not because the repo forced it

this is the same philosophy behind cursor automations for housekeeping and hygiene, where the automation prompt stays short because the repo already contains the playbook. efficient .cursor layout makes both interactive agents and background automations cheaper to run.

closing

you do not need a perfect .cursor directory on day one. you need one that grows without accumulating duplicate authority.

start small, route aggressively, scope rules to the files they govern, and treat catalogs as reference material rather than default context. the agent will still go look when it needs to. that is the point. you are just stopping it from carrying the whole library into every conversation.

faq

how small should my always-on layer be?

small enough that you can read it in under a minute and still trust the agent on safety and scope. if your always-on material needs scrolling, move detail into glob-scoped rules or skills.

will lean context make the agent miss project conventions?

only if you removed the canonical source entirely. routing fixes that. the conventions still exist, they just load when relevant. if you see misses, tighten the skill description, adjust globs, or add one line in AGENTS.md pointing to the canonical doc.

should i optimize tokens or optimize for "the agent always knows everything"?

optimize for intentional loading. "always knows everything" sounds safe but usually means "always reads everything", which is slower, costlier, and often muddier. give the agent a map and let retrieval do its job.

references

• rules in cursor
• skills in cursor
• ignore files

related reading

• my cursor setup: settings, rules, skills, and mcp
• starter templates for ai rules, skills, and commands
• how to use ai to create ai rules, skills, and commands
• cursor automations for housekeeping and hygiene
• cursor series