Cursor rules, commands, skills, and hooks: a complete guide

Your AI coding assistant is only as good as the context you give it. Cursor offers four ways to shape that context: rules, commands, skills, and hooks. Each serves a different purpose, and picking the right one stops you from repeating the same instructions, prompts, and checklists in every chat.

This guide breaks down what each feature does, when to use it, and how they work together.

If you only remember one thing:

• Rule: Always-on constraints (or file-scoped standards via globs).
• Command: A workflow you intentionally trigger with /.
• Skill: A playbook you want available, but only when the task calls for it.
• Hook: Automation and guardrails that run on events, without you prompting it.

Here’s a concrete example to make the difference stick. If the agent keeps reformatting files in a way you hate, add a rule. If you only want a checklist when you’re deploying, make it a skill. If you want formatting to run automatically after edits, use a hook.

Rules: your always-on guardrails

Rules are persistent instructions that shape how Cursor’s agent behaves. Think of them as your coding standards, architectural decisions, and project conventions bundled into markdown files.

When applied, rule contents appear at the start of the model’s context. This gives the AI consistent guidance for every interaction.

Types of rules

Cursor supports four rule types:

Where rules live

• Project rules: .cursor/rules/ directory, version-controlled with your codebase
• User rules: Cursor Settings → Rules, global to your environment
• Team rules: Dashboard-managed, available on Team and Enterprise plans
• AGENTS.md: Simple markdown file in project root as an alternative

A practical example

Here’s a rule that enforces TypeScript conventions:

1
---
2
description: TypeScript standards for all .ts and .tsx files
3
globs: ["*.ts", "*.tsx"]
4
---
5

6
# TypeScript standards
7

8
- Use strict typing. Never use `any`.
9
- Prefer `unknown` over `any` when type is uncertain.
10
- Use explicit return types for all functions.
11
- Prefer interfaces over type aliases for object shapes.
12
- Use discriminated unions instead of enums.

This rule only loads when you’re working with TypeScript files, keeping context clean for other work.

What makes a good rule

Good rules are focused, actionable, and scoped:

• Reference files instead of copying contents. This keeps rules short and prevents staleness.
• Be specific. “Use camelCase for variables” beats “follow good naming conventions.”
• Keep rules under 500 lines. If you need more, split into multiple composable rules.
• Avoid duplicating what’s in your codebase. Point to canonical examples.

Start simple. Add rules only when you notice the agent making the same mistake repeatedly. Don’t over-optimize before you understand your patterns.

Commands: your explicit workflows

Commands are reusable prompts triggered by typing / in chat. You define them, you invoke them, and the agent executes them.

Unlike rules that apply automatically, commands represent your explicit intent. You type /review because you want a code review right now.

Where commands live

• Project: .cursor/commands/ directory
• Global: ~/.cursor/commands/ directory
• Team: Dashboard-managed, synced to all team members

Creating a command

Create a markdown file with a descriptive name:

.cursor/
└── commands/
    ├── code-review.md
    ├── create-pr.md
    └── run-tests.md

Here’s what code-review.md might look like:

1
# Code review
2

3
Review the current changes with these criteria:
4

5
## Security
6
- Check for hardcoded secrets or credentials
7
- Verify input validation on user data
8
- Look for SQL injection or XSS vulnerabilities
9

10
## Performance
11
- Identify unnecessary re-renders in React components
12
- Check for N+1 query patterns
13
- Look for missing memoization
14

15
## Maintainability
16
- Verify functions are under 50 lines
17
- Check for duplicated logic
18
- Ensure error handling is consistent
19

20
Provide specific line numbers and code suggestions for each issue found.

Type /code-review in chat, and Cursor injects this prompt.

Adding parameters

Commands accept additional context. Anything after the command name gets included:

1
/commit and /pr these changes to fix DX-523

This chains multiple commands and adds context about the ticket number.

Skills: your on-demand expertise

Skills are portable packages that teach agents how to perform domain-specific tasks. The key difference from rules: the agent decides when to load them based on relevance.

Think of skills as lazy-loaded context. Cursor scans skill descriptions at startup but only loads the full content when the task demands it. This keeps your prompts short while still making deep, task-specific guidance available.

How skills work

When you start a conversation, Cursor presents available skills to the agent. The agent reads the name and description, then loads the full skill content only when it determines relevance.

You can also invoke skills manually by typing /skill-name in chat.

Skill structure

Skills live in specific directories:

.cursor/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   └── deploy.sh
        └── references/
            └── env-setup.md

Here’s the SKILL.md format:

1
---
2
name: deploy-app
3
description: Deploy the application to staging or production. Use when deploying code or discussing releases and environments.
4
---
5

6
# Deploy app
7

8
Deploy using the provided scripts.
9

10
## When to use
11
- User mentions "deploy", "release", or "ship"
12
- Changes are ready for staging or production
13
- User asks about environment configuration
14

15
## Workflow
16
1. Run validation: `python scripts/validate.py`
17
2. Deploy: `scripts/deploy.sh <environment>`
18
3. Verify deployment succeeded
19
4. Report back with the deployed URL
20

21
## Environments
22
- `staging`: Pre-production testing
23
- `production`: Live environment, requires extra confirmation

Skills vs rules: the mental model

The distinction matters:

• Rules apply automatically based on triggers you define
• Skills are loaded when the agent determines they’re relevant

Use this test: Would you want this instruction to apply even when you’re not thinking about it?

Yes → Rule. No → Skill.

Some examples:

Disabling automatic invocation

Set disable-model-invocation: true in the frontmatter to make a skill behave like a command. The agent won’t auto-load it; you must explicitly type /skill-name.

Hooks: your programmatic control

Hooks let you observe, control, and extend the agent loop using custom scripts. They run before or after specific events and can block, modify, or audit agent behavior.

This is the most powerful feature, and the most complex.

When to use hooks

Hooks shine for:

• Running formatters after edits
• Scanning for secrets or PII before commits
• Blocking risky operations (e.g., SQL writes to production)
• Adding analytics for agent actions
• Injecting context at session start

Hook events

Hooks fire at specific points in the agent lifecycle:

A simple example

Create .cursor/hooks.json:

1
{
2
  "version": 1,
3
  "hooks": {
4
    "afterFileEdit": [
5
      {
6
        "command": ".cursor/hooks/format.sh"
7
      }
8
    ]
9
  }
10
}

Create the script at .cursor/hooks/format.sh:

1
#!/bin/bash
2
# Read the input JSON
3
input=$(cat)
4
file_path=$(echo "$input" | jq -r '.file_path')
5

6
# Run prettier on the edited file
7
npx prettier --write "$file_path" 2>/dev/null
8

9
exit 0

Now every file edit triggers automatic formatting.

Blocking dangerous commands

Here’s a hook that prevents destructive git commands:

1
{
2
  "version": 1,
3
  "hooks": {
4
    "beforeShellExecution": [
5
      {
6
        "command": ".cursor/hooks/block-dangerous-git.sh",
7
        "matcher": "git"
8
      }
9
    ]
10
  }
11
}

1
#!/bin/bash
2
input=$(cat)
3
command=$(echo "$input" | jq -r '.command')
4

5
# Block force pushes and hard resets
6
if echo "$command" | grep -qE '(push.*--force|reset.*--hard|clean.*-fd)'; then
7
  echo '{"permission": "deny", "user_message": "Blocked: destructive git command"}'
8
  exit 0
9
fi
10

11
echo '{"permission": "allow"}'
12
exit 0

The matcher field filters which commands trigger the hook, so this only runs for git commands.

Prompt-based hooks

You can also use natural language instead of scripts:

1
{
2
  "hooks": {
3
    "beforeShellExecution": [
4
      {
5
        "type": "prompt",
6
        "prompt": "Is this command safe? Only allow read-only operations.",
7
        "timeout": 10
8
      }
9
    ]
10
  }
11
}

The LLM evaluates the condition and returns a structured response.

Choosing the right tool

Here’s a decision tree:

Does this apply to EVERY conversation?
├── Yes → Rule (alwaysApply: true)
└── No
    ├── Should it apply based on file patterns?
    │   └── Yes → Rule (globs)
    └── No
        ├── Is it a specific workflow you trigger?
        │   └── Yes → Command
        └── No
            ├── Should the agent decide when it's relevant?
            │   └── Yes → Skill
            └── No
                ├── Do you need to block/modify agent actions?
                │   └── Yes → Hook
                └── Otherwise → Manual rule (@-mention)

Quick reference table

Putting it all together

A well-configured project might look like this:

.cursor/
├── rules/
│   ├── typescript.mdc          # Always: coding standards
│   ├── testing.mdc             # Globs: *.test.ts files
│   └── security.mdc            # Always: security constraints
├── commands/
│   ├── review.md               # Trigger: /review
│   └── pr.md                   # Trigger: /pr
├── skills/
│   └── deploy/
│       ├── SKILL.md            # Agent-loaded when relevant
│       └── scripts/
│           └── deploy.sh
└── hooks.json                  # Automated formatting, security checks

Start with rules for your non-negotiables. Add commands for workflows you repeat. Introduce skills for domain expertise the agent should access on demand. Use hooks when you need programmatic control.

The goal isn’t to use every feature; it’s to give the agent the right context at the right time without polluting every conversation with information it doesn’t need.

References

• Cursor Rules documentation
• Cursor Commands documentation
• Cursor Skills documentation
• Cursor Hooks documentation
• Agent Skills standard