Cursor Repo Optimisation

Audit a repository's Cursor configuration, indexing setup, rules, hooks, documentation, and workflows. Produce a prioritised report of recommendations.

Reference files in this skill:

• references/audit-commands.md

  — Bash commands for each audit area

• references/audit-process.md

  — Parallel and sequential audit workflows

• references/migration-examples.md

  — Migration formats and example recommendations

• scripts/validate-artefacts.sh

  — Validate frontmatter for skills, rules, and subagents

Important: Consult the Cursor Documentation

Cursor evolves rapidly. Always consult these sources for the latest information:

• https://cursor.com/docs/context/rules — Rules configuration
• https://cursor.com/docs/context/skills — Skills configuration
• https://cursor.com/docs/context/subagents — Subagents configuration
• https://cursor.com/docs/agent/hooks — Hooks system
• https://cursor.com/docs/plugins — Plugins and marketplace
• https://cursor.com/changelog — Changelog

Scope

This skill is for audit and recommendation only. Do not make changes to the repository. Present findings as a prioritised report.

For AGENTS.md creation and updates, refer to the deepinit skill.

Verify Before Recommending

CRITICAL: Before including any recommendation in the report, verify that it is actually needed by reading the relevant files.

Common verification failures:

• Recommending a capability that already exists in a different form (e.g., a command that orchestrates something you thought was missing)
• Suggesting migrations for artefacts that are already correctly configured
• Flagging files for indexing exclusion when they're already in

  .cursorindexingignore

• Proposing new workflows without checking if existing skills/commands already implement them

For each potential recommendation:

1. Read the relevant configuration files to confirm the gap exists
2. If recommending changes to commands/skills/rules, read those files first
3. If suggesting new capabilities, check whether they already exist in a different form
4. Cross-reference with existing

   .cursor/

   artefacts to avoid redundant suggestions

Example: Before recommending "add MCP server for Linear", check if Linear integration already exists via

.cursor/mcp.json

Decision Tree: Where Should This Information Live?

Is this information needed on EVERY request?
├─ YES → Is it under ~5 lines?
│   ├─ YES → Root AGENTS.md
│   └─ NO → Always-apply rule (but question whether it truly needs to be always-on)
├─ NO → Is it scoped to specific files or directories?
│   ├─ YES → Glob-scoped rule (e.g., globs: api/**/*.py,api/**/*.md)
│   └─ NO → Does the agent need to decide when it's relevant?
│       ├─ YES → Skill (SKILL.md)
│       └─ NO → Is it triggered by an explicit user action?
│           ├─ YES → Skill with disable-model-invocation: true
│           └─ NO → Subagent (.cursor/agents/) if it needs isolated
│                   context, otherwise skill

Artefact Type Reference

/skill

Legacy Artefact Types

references/

disable-model-invocation: true

Note: Cursor includes a

/migrate-to-skills

The acid test: If it tells the agent how to behave, it's a rule. If it tells the agent how to do something, it's a skill. If it's a prompt you're tired of retyping, it's a skill with

disable-model-invocation: true

Audit Checklist

For bash commands to run for each area, see

references/audit-commands.md

1. Indexing Exclusions

Check

.cursorignore

.cursorindexingignore

.gitignore

• .cursorignore

  — Files invisible to Cursor entirely

• .cursorindexingignore

  — Files excluded from index but manually includable via

  @file

Flag for exclusion: Large reference docs, scraped data, database snapshots, generated code, binary content, build artefacts, vendored dependencies.

2. Rules Configuration

alwaysApply: true

alwaysApply: false

globs: <patterns>

description

@

Anti-patterns: God rules (>500 lines), procedural rules (should be skills), stale rules, conflicting rules, overly broad globs.

Sizing: Individual rules <500 lines, all always-apply rules combined <200 lines.

3. AGENTS.md Documentation

Bloated signs: >100 lines at root, detailed command references, area-specific conventions, procedural instructions.

Too thin signs: No directory map, no tech stack, no build/test commands, no critical constraints.

4. Context Weight Optimisation

Red flags: Root AGENTS.md >200 lines, >3 always-apply rules, single rule >500 lines.

5. Hooks

Check

.cursor/hooks.json

version: 1

{
  "version": 1,
  "hooks": {
    "hookName": [{ "command": "./script.sh", "matcher": "pattern" }]
  }
}

High-value hook patterns:

• sessionStart

  — Inject branch name, ticket, environment context via

  env

  and

  additional_context

  output

• preToolUse

  with

  matcher: "Shell"

  — Validate or transform shell commands

• beforeShellExecution

  — Block dangerous commands (exit code 2 to deny)

• afterFileEdit

  — Run formatters/linters after agent edits

• stop

  — Prompt handoff notes, auto-retry logic via

  followup_message

Available hooks:

sessionStart

sessionEnd

preToolUse

postToolUse

postToolUseFailure

subagentStart

subagentStop

beforeShellExecution

afterShellExecution

beforeMCPExecution

afterMCPExecution

beforeReadFile

afterFileEdit

beforeSubmitPrompt

preCompact

stop

afterAgentResponse

afterAgentThought

beforeTabFileRead

afterTabFileEdit

6. Generated and Binary Files

Flag: Auto-generated types (OpenAPI/protobuf), compiled output, SQL dumps, LFS-tracked paths, large test fixtures.

7. Codebase Indexing Settings

UI settings to verify (Cursor Settings > Features):

• Codebase Indexing enabled
• Include Project Structure enabled
• Indexing status shows fully indexed

8. Skills

Skills are the preferred format for:

• Multi-step procedural workflows
• Domain-specific expertise that benefits from

  references/

  subdirectories
• User-invoked prompts (with

  disable-model-invocation: true

  )

Check: Does

.cursor/skills/

references/

Note: Cursor includes a built-in

/migrate-to-skills

9. Artefact Validation

IMPORTANT: Read each artefact file to verify correct structure. Don't just check existence.

Run

scripts/validate-artefacts.sh

Skill Frontmatter (Required)

---
name: skill-name
description: What this skill does and when to use it
---

Optional fields:

• disable-model-invocation: true

  — For user-invoked-only skills (replacement for commands)

Common errors:

• Missing frontmatter entirely (no

  ---

  block)
• Missing

  name

  field
• Missing

  description

  field (agent won't discover the skill)
• Empty or placeholder description

Rule Frontmatter

alwaysApply: true

alwaysApply: false

globs: <patterns>

alwaysApply

globs

description

Common errors:

• globs:

  present but empty
• Both

  alwaysApply: true

  AND

  globs

  (redundant — always-apply ignores globs)

Note:

alwaysApply: false

globs

description

Subagent Frontmatter

All fields are optional but recommended for discoverability:

---
name: subagent-name          # Defaults to filename without extension
description: What this subagent does and when to use it
model: inherit               # Options: fast, inherit, or specific model ID
readonly: true               # For read-only subagents
is_background: false         # Run asynchronously without blocking parent
---

Best practices:

• Include

  description

  for automatic delegation (agent reads this to decide when to use the subagent)
• Use

  readonly: true

  for review/audit subagents
• Use

  is_background: true

  for long-running tasks that don't need to block
• Include "use proactively" in description to encourage automatic delegation

10. Commands (Legacy)

Commands in

.cursor/commands/

disable-model-invocation: true

/migrate-to-skills

references/migration-examples.md

11. Subagents

Check

.cursor/agents/

model

inherit

High-value patterns: debugger, security auditor, test writer, documentation specialist, code reviewer.

12. MCP Server Configuration

Check

.cursor/mcp.json

mcp.json

13. Plugins and Marketplace

Plugins are installed from the Cursor Marketplace and bundle rules, skills, agents, commands, MCP servers, and hooks. Check Cursor Settings > Rules for installed plugins.

For creating plugins: requires

.cursor-plugin/plugin.json

14. Sandbox Configuration

Check

sandbox.json

Audit Process

See

references/audit-process.md

Quick summary:

1. Read config files (.cursorignore, .cursorindexingignore, .gitignore, .cursorrules, hooks.json, mcp.json, sandbox.json, AGENTS.md)
2. List

   .cursor/

   directory contents
3. Identify legacy artefacts that may benefit from migration (apply-intelligently rules, commands)
4. Check for index pollution (large directories, generated code, binary files)
5. Measure context weight
6. Check Cursor documentation for new features
7. Verify each recommendation — read relevant files to confirm gaps exist before including in report

Output Format

Present findings as a prioritised report:

## Cursor Optimisation Report

### P0 — Critical (high impact, low effort)
[Recommendations that significantly improve indexing, search quality, or context efficiency]

### P1 — Important (high impact, moderate effort)
[Recommendations that improve developer experience or reduce repetitive work]

### P2 — Recommended (moderate impact)
[Recommendations that would improve the setup but are not urgent]

### P3 — Nice to Have (lower impact or beta features)
[Recommendations for newer or experimental features]

### Already Well Configured
[Areas that are already set up correctly — acknowledge good practices]

### Settings to Verify Manually
[UI-only settings the user should check in Cursor Settings]

For each recommendation, include:

• What to change
• Why it matters
• Specific file contents or changes to make

See

references/migration-examples.md

After the Report

Once the prioritised report is complete:

1. List every actionable recommendation as a numbered summary (one line each, referencing the priority level, e.g.

   [P0] Exclude backend/vector_db/public_documents/ from indexing

   )

2. Ask the user which items they would like implemented:

   Which of these would you like me to implement? You can specify by number (e.g. "1, 3, 5"), a priority level (e.g. "all P0 and P1"), or say "all".

3. Wait for the user's response, then implement only the selected items.