cursor-best-practices

A structured repository for creating and maintaining Cursor Best Practices optimized for agents and LLMs.

Install in 30 seconds:

npx skills add HKTITAN/cursor-best-practices

📋 Table of Contents

• Overview
• Quick Start
• Why Use This Skill?
• Installation
• What's Included
• Key Features
• Usage Examples
• Standards & Compatibility
• Documentation
• Resources
• Contributing
• FAQ
• Support

🎯 Overview

cursor-best-practices is a structured repository for creating and maintaining Cursor Best Practices optimized for agents and LLMs. It provides comprehensive best practices, patterns, and guidance for using Cursor effectively, whether you're setting up Cursor for the first time, creating rules and commands, or making your codebase Cursor-compatible.

What Makes This Skill Special?

• 📚 250+ Rule Files - Comprehensive coverage of every aspect of Cursor
• 🎯 Context-Aware - Automatically activates when you need Cursor guidance
• ⚡ Ready-to-Use - 14 command templates and 15 subagent templates
• 🔍 Well-Organized - Structured by feature, use case, and workflow
• 🔄 Always Current - Tracks official Cursor documentation
• 💡 Practical - Real-world examples and patterns
• 🎓 Educational - Learn best practices while you work

Perfect For

• New Cursor users setting up their .cursor folder
• Developers writing rules, commands, or skills
• Teams establishing consistent Cursor workflows
• Power users maximizing productivity with advanced features
• Project maintainers onboarding new team members

🚀 Quick Start

Installation

# Install for current project
npx skills add HKTITAN/cursor-best-practices

# Install globally for all projects
npx skills add HKTITAN/cursor-best-practices --global

First Steps

Once installed, the skill activates automatically. Try these:

1. Set up your .cursor folder:

   "Setup my .cursor folder"
   

2. Make your codebase Cursor-compatible:

   "Make this codebase cursor compatible"
   

3. Create your first rule:

   "How do I create a rule for TypeScript best practices?"
   

4. Use a command:

   /code-review @src/components/Button.tsx
   

✨ Why Use This Skill?

Benefit	Description
📚 Comprehensive	250+ rule files covering every aspect of Cursor — from basic setup to advanced workflows
🎯 Context-Aware	Automatically activates when you need help with Cursor-related tasks
⚡ Ready-to-Use	14 command templates and 15 subagent templates you can copy-paste immediately
🔍 Well-Organized	Structured by feature, use case, and workflow for easy discovery
🔄 Always Current	Tracks official Cursor documentation and reflects latest changes
💡 Practical	Real-world examples and patterns you can apply immediately
🎓 Educational	Learn best practices while you work, with detailed explanations
🔒 Standards-Compliant	Follows Agent Skills spec, works with skills.sh and Cursor

📦 Installation

Method 1: CLI Installation (Recommended)

The easiest way to install:

# Install for current project
npx skills add HKTITAN/cursor-best-practices

# Install globally for all projects
npx skills add HKTITAN/cursor-best-practices --global

What happens:

1. Downloads the skill from GitHub
2. Installs to .cursor/skills/cursor-best-practices/ in your project
3. Makes it immediately available to Cursor's AI

Method 2: Manual Installation

If you prefer manual installation:

1. Clone the repository:

   git clone https://github.com/HKTITAN/cursor-best-practices.git
   cd cursor-best-practices

2. Copy the skill folder:

   # Copy the inner cursor-best-practices folder to your project
   cp -r cursor-best-practices/cursor-best-practices /path/to/your/project/.cursor/skills/cursor-best-practices

3. Verify installation:

   • Open Cursor
   • Ask: "What skills are available?"
   • The skill should appear in the list

Installation Troubleshooting

Skill not loading?

Common issues and solutions:

• Wrong folder structure: Ensure folder is at .cursor/skills/cursor-best-practices/ (not nested twice)
• Missing SKILL.md: Check that SKILL.md exists in the skill folder
• Cursor not restarted: Restart Cursor after installation
• Folder structure mismatch: Verify folder structure matches repository structure

Verify structure:

.cursor/
└── skills/
    └── cursor-best-practices/
        ├── SKILL.md
        ├── rules/
        ├── commands/
        └── ...

Permission errors?

• Ensure write permissions to .cursor directory
• Create .cursor/skills/ first if it doesn't exist
• Check file system permissions
• On Windows, ensure you have proper access rights

Skill not activating?

• Try being more specific in your questions
• Use keywords like "setup", "rule", "command", "cursor"
• Example: "How do I create a rule?" instead of "help"
• The skill activates based on keywords and context

📖 What's Included

📝 Rules (250+ files)

Comprehensive best practices organized by category. Each rule file includes keyword-rich frontmatter, Do/Don't patterns, related queries, and links to related content.

Category	Files	Key Topics
Agent Modes	8	Agent, Ask, Plan, Debug modes — when and how to use each
Agent Patterns	14	Scoping, reviewing, mentions, workflow patterns
Agent Use Cases	12	Bug fixing, feature development, refactoring
Features	32	Tab, Inline Edit, Bugbot, CLI, Cloud, Transcripts
Integrations	30	GitHub, Slack, GitLab, Linear, Git, Deeplinks
Configuration	29	Extensions, ignore files, languages, shell, shortcuts, themes
Context	45	Rules, commands, MCP, skills, subagents, semantic search, mentions
Cookbook	13	Examples, patterns, workflows
Troubleshooting	7	Common issues and solutions
Get Started	5	Quickstart, concepts, models, pricing, making codebase compatible

Rule File Structure:

• ✅ Keyword-rich frontmatter (description, tags, optional globs)
• ✅ Do/Don't patterns with examples
• ✅ Related queries section
• ✅ Links to related rules and documentation
• ✅ Kept under ~500 lines

🎮 Commands (14 templates)

Ready-to-use command templates — copy to .cursor/commands/ and use immediately:

Command	Purpose	Example Usage
/code-review	Review code for correctness, security, quality, tests	/code-review @src/components/Button.tsx
/pr	Generate PR title, description, and review checklist	/pr
/run-tests-and-fix	Run tests, fix failures, re-run until green	/run-tests-and-fix
/security-audit	Security-focused review (injection, auth, secrets, deps)	/security-audit @src/auth/
/setup-new-feature	Propose plan with files, modules, and patterns	/setup-new-feature "User auth with OAuth"
/fix-issue	Fix bug or feature from issue # or description	/fix-issue #123
/update-deps	Update dependencies, run tests, report breaking changes	/update-deps
/docs	Generate or update documentation	/docs @src/utils/helpers.ts
/make-cursor-compatible	Make codebase Cursor-compatible (setup .cursor, rules, indexes)	/make-cursor-compatible
/lint-and-fix	Run linter, auto-fix issues, report remaining	/lint-and-fix
/format	Format code according to project standards	/format @src/**/*.ts
/check-coverage	Check test coverage, identify gaps	/check-coverage
/analyze-deps	Analyze dependencies, find unused/duplicates	/analyze-deps
/generate-types	Generate types from schemas/APIs	/generate-types @openapi.yaml

Command Features:

• Clear step-by-step instructions
• Usage examples
• Output format specifications
• Checklist or structured format

🤖 Subagents (15 templates)

Ready-to-use subagent templates — copy to .cursor/agents/ and invoke with @subagent-name:

Read-only subagents (review/analysis):

Subagent	Purpose
verifier.md	Runs tests and lint, reports pass/fail
reviewer.md	Code review for correctness, security, quality, tests
security-auditor.md	Security-focused review (injection, auth, secrets, deps)
linter.md	Linting and code style review
architect.md	Architectural pattern and design review

Editable subagents (can modify code):

Subagent	Purpose
documenter.md	Generate/update documentation (API docs, README, inline comments)
tester.md	Write and update tests for code changes
refactorer.md	Refactor code while maintaining functionality
debugger.md	Investigate and identify bugs in code
performance-analyzer.md	Analyze code for performance issues and bottlenecks
accessibility-checker.md	Review code for accessibility (a11y) compliance
migrator.md	Handle code migrations (framework upgrades, API changes)
dependency-manager.md	Review and manage dependencies (updates, security, compatibility)
formatter.md	Format code according to project standards
type-generator.md	Generate types from schemas, APIs, or data structures

Use cases:

• Read-only subagents — Parallel review/validation while main agent implements
• Editable subagents — Specialized tasks with context isolation
• Perfect for — Pre-commit checks, CI/CD, quality gates, parallel workflows

📚 References (5 deep-dive guides)

Comprehensive guides for complex topics:

1. rules-and-commands.md — Complete guide to rules and commands

   • Rule types and when to use each
   • Frontmatter structure and best practices
   • Using globs for file-specific rules
   • Command structure and parameters
   • Examples and patterns

2. agent-and-security.md — Agent tools, workflows, and security

   • Available tools and when to use them
   • Security defaults and settings
   • .cursorignore checklist
   • Terminal and MCP security
   • Network access controls

3. workflows-and-codebases.md — TDD, git commands, large codebases

   • TDD workflow step-by-step
   • Git-style command patterns
   • Codebase understanding strategies
   • Hooks and automation
   • Large repository tips

4. modes-context-tools.md — Agent modes, semantic search, @mentions

   • Modes comparison table
   • Plan mode detailed workflow
   • Semantic search best practices
   • @Mentions types and usage
   • Tab features and shortcuts

5. quick-reference.md — Quick reference guide

   • Keyboard shortcuts
   • Mode selection guide
   • Commands and subagents quick reference
   • Common workflows
   • @Mentions guide

🔍 Indexes (8 navigation indexes)

Quick discovery of relevant content:

Index	Purpose
query-index.md	Maps common user queries to relevant rules
setup-workflows-index.md	Framework and project setup guides
feature-index.md	Feature-based organization
integration-index.md	Integration guides (GitHub, Slack, etc.)
configuration-index.md	Configuration guides
troubleshooting-index.md	Troubleshooting solutions
pattern-index.md	Coding patterns
use-case-index.md	Use case organization

🎓 Skills Recommendations

• recommended.md — Curated list from skills.sh
  • Organized by category (Cursor & workflows, Frontend & React, Mobile & Expo, Backend & data, Creating skills, Docs & testing)
  • Each includes: name, description, when to use, installation command
  • Links to skills.sh for more details

🎯 Key Features

1. Make Your Codebase Cursor-Compatible

Transform any codebase into a Cursor-optimized workspace with a single command:

"Make this codebase cursor compatible"

What it does:

• ✅ Creates .cursor/ folder structure (rules, commands, agents, skills)
• ✅ Generates .cursorignore with best practices
• ✅ Creates AGENTS.md comprehensive codebase guide
• ✅ Adds project-specific rules (codebase-structure, architecture, content-patterns)
• ✅ Sets up useful commands
• ✅ Creates navigation indexes
• ✅ Documents architecture

Result: Your codebase becomes fully indexed and understandable by Cursor's AI at the deepest level.

2. Comprehensive Rule Coverage

250+ rules covering:

• Agent Modes — When and how to use Agent, Ask, Plan, Debug modes
• Context Management — Semantic search, @mentions, Tab, Inline Edit
• Workflows — TDD, git-style commands, large codebases
• Integrations — GitHub, Slack, GitLab, Linear, Git, Deeplinks
• Configuration — Extensions, ignore files, languages, shell, shortcuts, themes
• Features — Tab, Inline Edit, Bugbot, CLI, Cloud, Transcripts

3. Ready-to-Use Templates

Copy-paste templates for:

• Commands (14 templates) — Code review, PR, tests, security, docs, linting, formatting, coverage, dependency analysis, type generation
• Subagents (15 templates) — Verifier, reviewer, security-auditor, linter, architect, documenter, tester, refactorer, debugger, performance-analyzer, accessibility-checker, migrator, dependency-manager, formatter, type-generator
• Skills — Recommendations from skills.sh

4. Best Practices Guide

Learn:

• How to write effective rules
• When to use commands vs skills vs subagents
• How to structure your .cursor folder
• Security best practices
• Performance optimization
• Making codebases Cursor-compatible

💬 Usage Examples

Example 1: Initial Setup

User: "Setup my .cursor folder"
AI: [Creates folder structure, suggests .cursorignore, offers command templates]

Result: Complete .cursor/ folder setup with optional templates.

Example 2: Making Codebase Compatible

User: "Make this codebase cursor compatible"
AI: [Sets up full Cursor compatibility with indexing and documentation]

Result: Fully indexed codebase with AGENTS.md, rules, commands, indexes, and architecture docs.

Example 3: Creating a Rule

User: "How do I create a rule for TypeScript best practices?"
AI: [Explains rule structure, frontmatter, globs, provides examples]

Result: Step-by-step guidance on creating effective rules.

Example 4: Using Commands

User: "/code-review @src/components/Button.tsx"
AI: [Reviews code using the code-review command template]

Result: Comprehensive code review with categorized feedback.

Example 5: Understanding Agent Modes

User: "When should I use Plan mode vs Agent mode?"
AI: [Explains differences, use cases, when to switch]

Result: Clear guidance on mode selection.

View more examples

Creating file-specific rules:

User: "Create a rule that only applies to test files"
AI: [Shows how to use globs for file-specific rules]

Using semantic search:

User: "How does semantic search work in Cursor?"
AI: [Explains semantic search, when to use it, best practices]

Working with @mentions:

User: "How do I use @mentions effectively?"
AI: [Explains different mention types and when to use each]

Debug mode:

User: "How do I use Debug mode for a runtime bug?"
AI: [Explains Debug mode workflow and best practices]

Security:

User: "What should I put in .cursorignore for security?"
AI: [Explains secrets, credentials, and security best practices]

✅ Standards & Compatibility

This skill follows three standards:

Standard	Status	Description	Link
Agent Skills Specification	✅ Supported	Official open standard for agent skills	agentskills.io/specification
skills.sh	✅ Supported	Skill discovery and installation platform	skills.sh/docs
Cursor Skills	✅ Supported	Cursor's skill system	cursor.com/docs/context/skills

Standards Support:

• Proper SKILL.md frontmatter (name, description, license, compatibility, metadata)
• Correct directory structure
• Standards-compliant format
• Installable via npx skills add
• Works with Cursor's skill discovery
• References all three standards in documentation

📚 Documentation

Repository Documentation

• README.md — This file — comprehensive overview and guide
• CODEBASE.md — High-level codebase overview
• CHANGELOG.md — Version history and notable changes
• CONTRIBUTING.md — Contribution guidelines
• LICENSE — MIT license

Skill Documentation

• SKILL.md — Main skill file with overview
• rules/_sections.md — Complete rules index
• rules/_template.md — Template for new rules

Deep Codebase Understanding

For contributors and maintainers:

• .cursor/AGENTS.md — Comprehensive codebase guide (400+ lines)
• .cursor/ARCHITECTURE.md — System and content architecture
• .cursor/rules/architecture-and-design.md — Design decisions
• .cursor/rules/content-patterns.md — Writing conventions
• .cursor/rules/skill-maintenance.md — Maintenance guidelines
• .cursor/indexes/codebase-index.md — Quick navigation reference

🔗 Resources

Official Documentation

• Cursor Documentation — Complete official documentation
• Agent Skills Specification — Official skill specification
• Cursor Blog — Latest updates and announcements

Community Resources

• cursor.directory — Community rules & MCPs
• skills.sh — Skill recommendations & leaderboard
• Cursor Discord — Community support and discussions

Related Projects

• Agent Skills — Official agent skills repository
• React Best Practices — Example skill structure

🤝 Contributing

We welcome contributions! This skill tracks Cursor docs and keeps up to date with product changes.

How to Contribute

Found outdated or wrong info?

1. Open an issue or pull request
2. Include the Cursor docs link
3. Provide the suggested fix
4. Reference the specific file/section

Want to add new content?

1. Suggest via issue first
2. Get feedback on approach
3. Submit PR with updates to SKILL.md, rules/, or references/
4. Follow existing patterns and structure

Rule files:

• Use rules/_template.md as template
• Add the new rule to rules/_sections.md
• Include frontmatter with description and tags
• Add "Related Queries" section
• Link to related rules in "See Also"

See CONTRIBUTING.md for detailed guidelines.

❓ FAQ

Do I need to configure anything after installation?

No! The skill works automatically. Just install and start asking Cursor questions about best practices. The skill activates based on keywords and context in your questions.

Will this slow down Cursor?

No. Skills load on demand and only activate when relevant to your questions. The skill is optimized for performance and doesn't impact Cursor's speed.

Can I use this in multiple projects?

Yes! Install globally with --global flag for all projects, or install per-project. Each project can have its own installation. Global installation makes it available across all your projects.

How do I update the skill?

Run npx skills add HKTITAN/cursor-best-practices again to get the latest version. Or pull the latest from GitHub if installed manually. The skill will update to the latest version.

How many rules should I create for my project?

Start with a few essential rules. Add more as you identify patterns where the agent needs guidance. Quality over quantity — better to have a few well-written rules than many poorly written ones.

Can I modify the rules in this skill?

The skill's rules are for reference. Create your own rules in .cursor/rules/ based on these patterns. Don't modify the skill's rules directly — they're templates and examples.

What's the difference between AGENTS.md and rules folder?

AGENTS.md is a simple alternative at project root (plain markdown, no frontmatter). Rules folder offers more organization, file-specific rules with globs, and better structure for larger projects. Use AGENTS.md for simple projects, rules folder for complex ones.

The skill isn't activating when I ask questions.

Try being more specific. For example:

• ✅ "How do I create a rule?"
• ✅ "Setup my .cursor folder"
• ✅ "When should I use Plan mode?"
• ❌ "help with rules" (too vague)

The skill activates based on keywords and context. Use Cursor-related terms in your questions.

How do I make my codebase Cursor-compatible?

Use the /make-cursor-compatible command or ask "Make this codebase cursor compatible". This will:

• Create .cursor/ folder structure
• Generate .cursorignore
• Create AGENTS.md codebase guide
• Add project-specific rules
• Set up commands and indexes
• Document architecture

See the make-codebase-cursor-compatible rule for details.

What file types does this skill support?

This skill provides guidance for working with any file type in Cursor. The rules and commands are language-agnostic, though some examples may use specific languages. The skill helps you set up Cursor for any project type.

💬 Support

Getting Help

• GitHub Issues: Open an issue for bugs or questions
• Discussions: Use GitHub Discussions for general questions
• Cursor Discord: Join the Cursor Discord community

Reporting Issues

When reporting issues, please include:

• Cursor version
• Skill version
• Steps to reproduce
• Expected vs actual behavior
• Relevant error messages

Feature Requests

We welcome feature requests! Open an issue with:

• Use case description
• Proposed solution
• Benefits

📝 Changelog

See CHANGELOG.md for complete version history.

Recent highlights:

• v1.0.0 (2026-01-24): Initial public release with 250+ rules, 14 commands, 15 subagents, comprehensive coverage

👤 Author

HKTITAN (GitHub)

Maintainer of cursor-best-practices skill. Contributions welcome!

📄 License

MIT — see LICENSE for details.

You are free to:

• ✅ Use in any project (commercial or personal)
• ✅ Modify and adapt for your needs
• ✅ Share with your team
• ✅ Contribute improvements
• ✅ Fork and create derivatives

🙏 Acknowledgments

• Cursor Team — For creating an amazing AI coding assistant
• Agent Skills Community — For the open standard and ecosystem
• skills.sh — For skill discovery and recommendations
• Contributors — Everyone who helps improve this skill

---

Made with ❤️ for the Cursor community

If you find this helpful, consider giving it a ⭐ on GitHub!

Star this repo ⭐ | Report issues 🐛 | Request features 💡 | Contribute 🤝