Cursor best practices

Skill HKTITAN/cursor-best-practices/cursor-best-practices

make any repo vibe-codeable, agent-ready, and cursor-compatible in minutes

Install

npx -y skills add HKTITAN/cursor-best-practices --skill cursor-best-practices

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Best practices for using Cursor—rules, commands, skills, subagents, ignore files, Agent security, workflows, and community resources. Use when setting up Cursor, initializing or creating the .cursor folder, writing .cursor/rules or AGENTS.md, creating commands or skills, configuring .cursorignore, working with Agent, discovering rules or MCPs (e.g. cursor.directory), making codebases cursor-compatible, or asking about Cursor workflows, TDD, git commands, or large codebases.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

17.0 KB, as published. Nobody here has run it

cursor-best-practices

A structured repository for creating and maintaining Cursor Best Practices optimized for agents and LLMs. This skill provides references/ (on-demand docs) and assets/templates/ (rule, command, and subagent templates) 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)
Ask about plugins, hooks, Cloud Agent, CLI, worktrees, or deeplinks

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. assets/templates/rules/_sections.md | references/templates-index.md | 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. assets/templates/commands/.

Skills and subagents

Skills: Loaded from .agents/skills/, .cursor/skills/, or ~/.cursor/skills/ (and .claude/skills/, .codex/skills/ for compatibility). Each skill is a folder with SKILL.md; optional scripts/, references/, assets/. Frontmatter: name, description (required); optional license, compatibility, metadata, disable-model-invocation (when true, skill only applies when invoked via /skill-name). Agent applies when relevant or via /skill-name. Use /migrate-to-skills (Cursor 2.4+) to convert eligible rules and commands to skills. Subagents: .cursor/agents/ or ~/.cursor/agents/; markdown + YAML name, description, optional model, readonly, background. 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 assets/templates/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: assets/recommended-skills.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. assets/templates/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: Plan Mode, Debug Mode. assets/templates/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: assets/templates/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): assets/templates/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: assets/templates/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 at project root (always included) and nested per directory (included when reviewing files under that path); Team rules from dashboard apply to all repos. Trigger: comment cursor review or bugbot run; use verbose=true for request ID. Autofix spawns a Cloud Agent to fix reported issues (commit to branch or new branch). 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.

Plugins, Hooks, Cloud Agent, CLI, Worktrees, Deeplinks

Plugins: Bundle rules, skills, agents, commands, MCP servers, and hooks in distributable packages. .cursor-plugin/plugin.json manifest; install from Cursor Marketplace or team marketplaces (Teams/Enterprise). See: Plugins.

Hooks: .cursor/hooks.json (project) or ~/.cursor/hooks.json (user). Observe or gate agent loop stages (e.g. beforeShellExecution, afterFileEdit, sessionStart). Command-based (script) or prompt-based (LLM). See: Hooks.

Cloud Agent: Agents run in the cloud; access via API, Linear, GitHub, Slack, Desktop (Cloud in dropdown), or cursor.com/agents (Web/PWA). MCP support; spend limit; "Apply" to bring worktree changes to your branch. See: Cloud Agent.

CLI: agent command for interactive or non-interactive use. Modes: Agent, Plan, Ask. Cloud handoff: & in chat or agent -c "prompt". Sessions: agent ls, agent resume. See: CLI.

Worktrees: Parallel agents run in separate Git worktrees. .cursor/worktrees.json for setup (e.g. setup-worktree, OS-specific). Best-of-N: run same prompt on multiple models; Apply to merge result. See: Worktrees.

Deeplinks: Share prompts, commands, or rules via cursor://anysphere.cursor-deeplink/ or https://cursor.com/link/. Max 8,000 characters. See: Deeplinks.

.cursor layout and setup workflow

Folders: rules/, commands/, skills/, agents/. Optional: hooks.json, worktrees.json. 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 from assets/templates/commands/ → .cursor/commands/ (e.g. code-review.md, lint-and-fix.md, format.md, etc.).
- Agents: Copy from assets/templates/agents/ → .cursor/agents/ (e.g. verifier.md, reviewer.md, linter.md, formatter.md, etc.).
- Rules: Optionally copy from assets/templates/rules/ or add one starter rule or AGENTS.md.
Confirm: List what was created and how to use it (e.g. "Use /code-review in chat," "Add rules to .cursor/rules/").

See: assets/templates/rules/context-setup-cursor-folder.md. references/templates-index.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.