cursor-best-practices

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

View on skills.sh · Install in 30 seconds:

npx skills add https://github.com/hktitan/cursor-best-practices --skill cursor-best-practices

Short form: 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?

• 📚 References + templates - references/ (on-demand docs) and assets/templates/ (curated rule, command, and subagent templates)
• 🎯 Context-Aware - Automatically activates when you need Cursor guidance
• ⚡ Ready-to-Use - 14 command templates and 15 subagent templates in assets/templates/
• 🔍 Well-Organized - Skill layout follows Agent Skills spec (SKILL.md, references/, assets/)
• 🔄 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

# Recommended: full URL with skill name
npx skills add https://github.com/hktitan/cursor-best-practices --skill cursor-best-practices

# Short form (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 | references/ (on-demand docs) and assets/templates/ (curated rules, commands, subagents) plus Cursor docs | | 🎯 Context-Aware | Automatically activates when you need help with Cursor-related tasks | | ⚡ Ready-to-Use | 14 command templates and 15 subagent templates in assets/templates/ you can copy-paste immediately | | 🔍 Well-Organized | Skill layout: SKILL.md, references/, assets/templates/ (rules, commands, agents) | | 🔄 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:

# Recommended: full URL with skill name
npx skills add https://github.com/hktitan/cursor-best-practices --skill cursor-best-practices

# Short form (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: The skill folder contains SKILL.md, references/, and assets/ (with assets/templates/commands, assets/templates/agents, assets/templates/rules).

   # 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

<details> <summary><strong>Skill not loading?</strong></summary>

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
├── references/
└── assets/
    ├── templates/
    │   ├── commands/
    │   ├── agents/
    │   └── rules/
    └── recommended-skills.md

</details> <details> <summary><strong>Permission errors?</strong></summary>

• 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

</details> <details> <summary><strong>Skill not activating?</strong></summary>

• 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

</details>

📖 What's Included

📝 Rules (curated templates)

10 curated rule templates in assets/templates/rules/ — copy into .cursor/rules/ or use as examples. Topics: rule structure, setup (.cursor folder), modes/workflows, ignore (.cursorignore). See assets/templates/rules/_sections.md for the full list. For broader rule patterns, see Cursor docs — Rules and this skill's references/.

🎮 Commands (14 templates)

Ready-to-use command templates in assets/templates/commands/ — 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 in assets/templates/agents/ — 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 (deep-dive guides)

references/ — 5 deep-dive guides; references/templates-index.md lists all templates. Guides:

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,