Hooks and skills

Rules only guide the model; hooks enforce behavior, and skills turn repeat prompts into shared tools.

Hooks are scripts Cursor runs at fixed points in the agent's work. Unlike rules, they always run, so they can enforce policy. They are configured in hooks.json: per project in .cursor/hooks.json, per user in ~/.cursor/hooks.json, and organizations can deploy enterprise-level files or team hooks from the dashboard.

Events include sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, beforeShellExecution, afterShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, stop and even Tab-related events. Each event lists commands to run.

Observational hooks like afterFileEdit can't block anything; use them to format code or log activity.
Permission hooks like beforeShellExecution, beforeMCPExecution, beforeReadFile and preToolUse can deny an action. A command hook that exits with code 2 blocks it.
Most other failures fail open (the action proceeds) unless the hook is configured to fail closed.

Typical uses: auto-format after edits, block commands touching production (a script that reads the event JSON on standard input and exits 2 for terraform apply), prevent reads of secret files more strongly than .cursorignore, or audit every shell command. Project hooks also run in Cloud Agents; user-level ones don't. Review hooks in repositories you clone: they run code on your machine.

Skills package instructions for repeated work, such as a release checklist or code-review procedure. Type / in the agent input to invoke one for a single message, or choose Use as Mode (Option/Alt+Enter) to keep it active for every turn as a custom mode. Cursor ships built-in ones too, such as /goal for long-running objectives.

Example

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": "./.cursor/hooks/format.sh" }
    ],
    "beforeShellExecution": [
      { "command": "./.cursor/hooks/block-prod.sh" }
    ]
  }
}

Remember

hooks.json (project or user) runs scripts at agent events
Permission hooks like beforeShellExecution can deny; exit code 2 blocks
Skills are invoked with /; Use as Mode keeps one active every turn

Watch out for

Relying on an observational hook such as afterFileEdit to prevent something; only permission hooks can block.

Check yourself

Which hook can stop a dangerous terminal command before it runs?

Official docs: cursor.com/docs/hooks

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks