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.mdand notice agents getting slower or noisier over time - teams whose
.cursorfolder 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.mdfile 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 | job | load profile |
|---|---|---|
AGENTS.md |
entry point, hard constraints, route-by-task table | small, always present |
.cursor/README.md |
local index of rules, skills, and subagents | small, linked from entry |
.cursor/rules/*.mdc |
enforceable standards | thin always-on + glob-scoped detail |
.cursor/skills/*/SKILL.md |
procedural runbooks | on demand when task matches |
.cursor/reference/*.md |
catalogs, contracts, long inventories | only when maintaining or choosing |
layer 1: a thin AGENTS.md
AGENTS.md should answer two questions quickly:
- what must never be violated on this repo
- 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
descriptionthat 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:
-
.gitignorefor generated output and dependencies -
.cursorignorefor 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:
-
@Filesand@Folderswhen 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.
