AgentSkillsCN

cursor-best-practices

Cursor 的使用最佳实践——包括规则、命令、技能、子代理、忽略文件、代理安全、工作流以及社区资源。在设置 Cursor、初始化或创建 .cursor 文件夹、编写 .cursor/rules 或 AGENTS.md、创建命令或技能、配置 .cursorignore、与代理协作、探索规则或 MCP（例如 cursor.directory）、使代码库兼容 Cursor，或就 Cursor 工作流、TDD、Git 命令以及大型代码库的相关问题进行咨询时，均可灵活运用此技能。

SKILL.md
--- frontmatter
name: cursor-best-practices
description: "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."
license: MIT
compatibility: "Designed for Cursor. Compatible with Agent Skills specification (agentskills.io), skills.sh, and Cursor. References https://cursor.com/docs/, https://agentskills.io/specification, https://skills.sh/docs."
metadata:
  author: HKTITAN
  version: "1.0"
  standards:
    - "https://agentskills.io/specification"
    - "https://skills.sh/docs"
    - "https://cursor.com/docs/context/skills"

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:

TypeWhen to use
Always ApplyMust affect every request (e.g. "No any in TS", "Run tests before done"). Use sparingly.
Apply IntelligentlyGeneral guidance when relevant (e.g. "Prefer functional components").
Apply to Specific FilesUse globs (e.g. **/*.test.ts, **/api/**). Rule loads only when those files are in context.
Apply ManuallyUser 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/):

CommandPurpose
/code-reviewReview for correctness, security, quality, tests. Output: Critical / Suggestion / Nice to have.
/prSummarize changes, propose PR title/description, suggest review checklist.
/run-tests-and-fixRun tests, fix failures, re-run until green; summarize changes.
/security-auditSecurity-focused review (injection, auth, secrets, deps).
/setup-new-featurePropose plan (files, modules, patterns), suggest implementation steps.
/fix-issueFix bug or feature from issue # or description.
/update-depsUpdate deps, run tests, report breaking changes.
/docsGenerate or update docs for @-mentioned code or current feature.
/make-cursor-compatibleMake codebase Cursor compatible: add .cursor folder, .cursorignore, AGENTS.md, rules, commands, indexes.
/lint-and-fixRun linter, auto-fix issues, report remaining issues.
/formatFormat code according to project standards.
/check-coverageCheck test coverage, identify gaps, suggest improvements.
/analyze-depsAnalyze dependency tree, identify unused/duplicate deps, suggest optimizations.
/generate-typesGenerate 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

ModePurposeTools
AgentImplement, refactor, multi-file work.Full (search, read, edit, terminal, MCP).
AskLearning, Q&A, exploration.Search + read only; no edits.
PlanResearch → clarify → plan → you review → "Build".Search + read. Plans in .cursor/plans/; Shift+Tab to switch.
DebugReproducible 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:

  1. •Create: .cursor/rules/, .cursor/commands/, .cursor/skills/, .cursor/agents/.
  2. •Optional .cursorignore: If missing, add minimal (e.g. node_modules/, .env, *.log, dist/). Use .gitignore syntax; adjust for stack.
  3. •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.
  4. •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.

See also