cursor-best-practices

A structured repository for creating and maintaining Cursor Best Practices optimized for agents and LLMs. This skill provides rules/ (atomic practices), commands/ & agents/ (templates), skills/recommended.md, and references/ (deeper dives) covering rules, commands, skills, subagents, ignore files, Agent security, workflows, and community resources.

When to use

Apply this skill when users:

Set up or initialize Cursor, create the .cursor folder, or ask "setup my .cursor folder"
Write or edit .cursor/rules, AGENTS.md, or rule frontmatter
Create or use slash commands, skills, or subagents
Configure .cursorignore or .cursorindexingignore
Work with Agent modes (Agent, Ask, Plan, Debug), semantic search, or @mentions
Ask about TDD, git-style commands, large codebases, or Cursor workflows
Discover rules or MCPs (cursor.directory) or skill recommendations (skills.sh)

Rules

Locations: Project .cursor/rules/ (.md/.mdc), user Cursor Settings → Rules, Team dashboard. Precedence: Team → Project → User.

Types and when to use:

| Type | When to use | |------|-------------| | Always Apply | Must affect every request (e.g. "No any in TS", "Run tests before done"). Use sparingly. | | Apply Intelligently | General guidance when relevant (e.g. "Prefer functional components"). | | Apply to Specific Files | Use globs (e.g. **/*.test.ts, **/api/**). Rule loads only when those files are in context. | | Apply Manually | User invokes with @rule-name when needed (e.g. release process, legacy quirks). |

Frontmatter: description (keyword-rich, helps relevance), globs (file-specific), alwaysApply (use rarely). Keep each rule <500 lines; split by concern, link to references/. AGENTS.md = project-root plain markdown alternative; no frontmatter.

Best practices: Composable rules, concrete examples. Reference—don't copy—long runbooks. Start simple; add rules when the agent keeps making the same mistake. Migrate legacy .cursorrules to Project Rules or AGENTS.md.

See: Rules. rules/_sections.md | rules-keep-under-500-lines | rules-use-globs | rules-write-good-descriptions | references/rules-and-commands.md.

Commands

Locations: Project .cursor/commands/, user ~/.cursor/commands/, Team dashboard. Format: Plain Markdown .md; filename = command name. Trigger with / in chat. Parameters: Text after the command is passed as context (e.g. /fix-issue 123 → "123").

Available templates (copy into .cursor/commands/):

| Command | Purpose | |---------|---------| | /code-review | Review for correctness, security, quality, tests. Output: Critical / Suggestion / Nice to have. | | /pr | Summarize changes, propose PR title/description, suggest review checklist. | | /run-tests-and-fix | Run tests, fix failures, re-run until green; summarize changes. | | /security-audit | Security-focused review (injection, auth, secrets, deps). | | /setup-new-feature | Propose plan (files, modules, patterns), suggest implementation steps. | | /fix-issue | Fix bug or feature from issue # or description. | | /update-deps | Update deps, run tests, report breaking changes. | | /docs | Generate or update docs for @-mentioned code or current feature. | | /make-cursor-compatible | Make codebase Cursor compatible: add .cursor folder, .cursorignore, AGENTS.md, rules, commands, indexes. | | /lint-and-fix | Run linter, auto-fix issues, report remaining issues. | | /format | Format code according to project standards. | | /check-coverage | Check test coverage, identify gaps, suggest improvements. | | /analyze-deps | Analyze dependency tree, identify unused/duplicate deps, suggest optimizations. | | /generate-types | Generate TypeScript/types from schemas, APIs, or JSON. |

See: Commands. commands/.

Skills and subagents

Skills: .cursor/skills/<name>/ with SKILL.md; optional scripts/, references/, assets/. Agent applies when relevant or via /skill-name. Subagents: .cursor/agents/ or ~/.cursor/agents/; markdown + YAML name, description. Foreground vs background; built-ins (Explore, Bash, Browser).

When to use: Subagents — context isolation, parallel work, multi-step specialized tasks (e.g. verifier that only runs tests/lint). Skills — single-purpose, repeatable tasks (changelog, format, domain-specific workflows).

Templates: Copy subagent templates from agents/ → .cursor/agents/. Available subagents:

Read-only (review/analysis):

verifier.md — Runs tests and lint, reports only
reviewer.md — Code review for correctness, security, quality, tests
security-auditor.md — Security-focused review
linter.md — Linting and code style review
architect.md — Architectural pattern and design review

Editable (can modify code):

documenter.md — Generate/update documentation
tester.md — Write and update tests
refactorer.md — Refactor code while maintaining functionality
debugger.md — Investigate and identify bugs
performance-analyzer.md — Analyze performance issues and bottlenecks
accessibility-checker.md — Review code for a11y compliance
migrator.md — Handle code migrations systematically
dependency-manager.md — Review and manage dependencies
formatter.md — Format code according to standards
type-generator.md — Generate types from schemas/APIs

Skill recommendations: skills/recommended.md and skills.sh only; suggest npx skills add <owner/repo>.

See: Skills, Subagents.

Ignore files

.cursorignore: Project root; same syntax as .gitignore. Excluded paths are not used for semantic search, Tab, Agent, Inline Edit, @mentions. Not terminal/MCP. Why: Security (secrets, keys, credentials), performance (large repos). .cursorindexingignore: Indexing only; files still usable if @-mentioned.

Must exclude: .env, .env.*, *.key, *.pem, credentials.json, **/secrets/**. Add project-specific paths. Use ! carefully; parent exclusions limit re-includes.

See: Ignore files. rules/ignore-cursorignore-secrets.md.

Agent and security

Agent: Rules + tools (search, read, edit, terminal, MCP) + your messages. Summarization (/summarize), checkpoints. Queue (Enter) vs Ctrl+Enter (send immediately).

Security: File edits allowed (except protected config); use VCS. Terminal: approval by default; avoid "Run everything". MCP: approve connection + each tool call. Network: GitHub, link fetch, search only. Put secrets in .cursorignore.

See: Agent overview, Agent security. references/agent-and-security.md.

Agent modes

| Mode | Purpose | Tools | |------|---------|-------| | Agent | Implement, refactor, multi-file work. | Full (search, read, edit, terminal, MCP). | | Ask | Learning, Q&A, exploration. | Search + read only; no edits. | | Plan | Research → clarify → plan → you review → "Build". | Search + read. Plans in .cursor/plans/; Shift+Tab to switch. | | Debug | Reproducible bugs; hypotheses → instrument → reproduce → fix → verify. | Full. |

Switch: Mode picker in chat; Ctrl+. to cycle. Best practice: Plan with Ask/Plan, implement with Agent. If Agent builds wrong thing, revert → refine plan → re-run.

See: Modes. rules/modes-plan-then-agent.md. references/modes-context-tools.md.

Workflows and large codebases

TDD: Write tests → run (expect fail) → commit tests → implement → run until pass → commit impl. Run tests before done: rules/workflows-run-tests-before-done.md.

Git-style commands: /pr, /fix-issue, /review, /update-deps, /docs in .cursor/commands/. Codebase understanding: "How does X work?", "How do I add Y?"; broad → narrow. Diagrams: Ask for Mermaid architecture/data-flow. Hooks: .cursor/hooks.json for long-running loops. Design → code: Paste mockups; use Browser for preview.

Large codebases: Domain rules in .cursor/rules with globs; Plan with Ask, implement with Agent. Tab = quick edits; Inline Edit (Ctrl+K) = single-file; Chat/Agent = multi-file. Use @files, @folder, @Code; scope down; new chats when context is noisy.

See: Agent workflows, Large codebases. references/workflows-and-codebases.md.

Semantic search, @mentions, Tab

Semantic search: Meaning-based; natural-language questions. Indexing on workspace open; usable ~80% completion. Use both grep (exact) and semantic (conceptual): rules/context-use-grep-and-semantic.md.

@Files & Folders: Reference by path; drag from sidebar. @Code: Specific snippets (most precise). @Docs: Bundled or Add new doc (URL). /summarize — compress context. Best practice: rules/context-use-at-mentions.md.

Tab: Inline autocomplete; Tab accept, Esc reject, Ctrl+Right partial. Use for speed; Inline Edit or Chat for larger changes.

See: Semantic search, @ Mentions, Tab.

Bugbot, MCP, shortcuts

Bugbot: PR review (bugs, security, quality). .cursor/BUGBOT.md per directory; Team → project → User. MCP: External tools; approve connection + tool calls. cursor.directory for community rules & MCPs. Skills: skills.sh only.

Shortcuts: Ctrl+I Agent | Ctrl+K Inline Edit | Ctrl+. cycle modes | Enter queue, Ctrl+Enter send | Tab accept completion, Esc reject.

See: Bugbot, MCP.

.cursor layout and setup workflow

Folders: rules/, commands/, skills/, agents/. AGENTS.md = simple alternative to rules.

Setup my .cursor folder

When the user asks to set up, initialize, or create the .cursor folder:

Create: .cursor/rules/, .cursor/commands/, .cursor/skills/, .cursor/agents/.
Optional .cursorignore: If missing, add minimal (e.g. node_modules/, .env, *.log, dist/). Use .gitignore syntax; adjust for stack.
Optional templates: Offer to copy from this skill. If user agrees:
- Commands: Copy command templates from commands/ → .cursor/commands/ (e.g. code-review.md, lint-and-fix.md, format.md, etc.).
- Agents: Copy any subagent templates from agents/ → .cursor/agents/ (e.g. verifier.md, reviewer.md, linter.md, formatter.md, etc.).
- Do not copy rules/ practice files into .cursor/rules/ as-is (guidance only). Add one starter rule or AGENTS.md if requested.
Confirm: List what was created and how to use it (e.g. "Use /code-review in chat," "Add rules to .cursor/rules/").

See: rules/context-setup-cursor-folder.md.

Troubleshooting

Rules not applying? Check type (Always / Intelligent / Globs / Manual), description (keywords), and globs (paths match). Request ID: "Get request ID" or cursor review verbose=true when reporting. See: Common issues, Troubleshooting guide. references/modes-context-tools.md.

cursor-best-practices

cursor-best-practices

When to use

Rules

Commands

Skills and subagents

Ignore files

Agent and security

Agent modes

Workflows and large codebases

Semantic search, @mentions, Tab

Bugbot, MCP, shortcuts

.cursor layout and setup workflow

Setup my .cursor folder

Troubleshooting

See also