<p align="center"> <a href="https://www.npmjs.com/package/cursor-handbook"><img src="https://img.shields.io/npm/v/cursor-handbook?color=cb3837&logo=npm" alt="npm version" /></a> <a href="https://www.npmjs.com/package/cursor-handbook"><img src="https://img.shields.io/node/v/cursor-handbook?color=339933&logo=node.js&logoColor=white" alt="node version" /></a> <a href="https://github.com/girijashankarj/cursor-handbook/stargazers"><img src="https://img.shields.io/github/stars/girijashankarj/cursor-handbook?color=yellow&logo=github" alt="GitHub stars" /></a> <a href="https://github.com/girijashankarj/cursor-handbook/fork"><img src="https://img.shields.io/github/forks/girijashankarj/cursor-handbook?color=blue&logo=github" alt="GitHub forks" /></a> <a href="https://github.com/girijashankarj/cursor-handbook/commits/main"><img src="https://img.shields.io/github/last-commit/girijashankarj/cursor-handbook" alt="GitHub last commit" /></a> <a href="https://github.com/girijashankarj/cursor-handbook/issues"><img src="https://img.shields.io/github/issues/girijashankarj/cursor-handbook" alt="GitHub issues" /></a> <a href="https://github.com/girijashankarj/cursor-handbook/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License MIT" /></a> <img src="https://img.shields.io/badge/version-1.5.1-blue" alt="Version" /> <img src="https://img.shields.io/badge/Components-208-green" alt="208 Components" /> <img src="https://img.shields.io/badge/Token%20Savings-30%25%2B-green?style=for-the-badge" alt="30%+ Savings" /> </p>

cursor-handbook

🌐 Live handbook: https://girijashankarj.github.io/cursor-handbook/

<p align="center"> <a href="https://girijashankarj.github.io/cursor-handbook/"> <img src="docs/snaps/handbook-website-preview.png" alt="cursor-handbook website — browse components, read guidelines, search and copy paths" width="800" /> </a> </p>

The open-source rules engine for Cursor IDE — 208 components (rules, agents, skills, commands, hooks) that turn your AI into a senior engineer who follows your standards, knows your codebase, and never wastes a token.

Stop teaching your AI the same things every session. cursor-handbook gives Cursor permanent memory of your standards, security policies, and workflows — across every project, every team member, every prompt.

<p align="center"> <strong>If cursor-handbook helps you, consider giving it a ⭐ — it helps others discover it.</strong> </p>

---

Table of Contents

• Ways to use
• Use as a Cursor Plugin
• The Problem
• Before vs After
• Who is this for?
• How It Works
• What's Inside
• Quick Start
• Cursor Setup Agent
• Component Deep Dive
• Documentation

---

Ways to use cursor-handbook

Pick the option that fits your workflow:

Recommended: Run npx cursor-handbook init — it copies the .cursor/ folder into your project. Then use @cursor-setup-agent in Cursor to keep only the components you need.

| Option | Best for | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. npm ⭐ | Fastest approach. Run npx cursor-handbook init, use @cursor-setup-agent to keep only what you need, then npm uninstall cursor-handbook. See Quick Start. | | 2. Cursor Setup Agent | Smartest approach. Clone this repo, open your project in Cursor, then run @cursor-setup-agent. The agent scans your codebase, detects your language/framework/database/CI stack, selects only relevant components, generates project.json, and copies everything into .cursor/ — in one step. See how it works. | | 3. Clone & copy | Use the full rules engine in your repo. Clone this repo, copy the .cursor folder into your project, then edit project.json and tailor rules/agents/skills to your stack. | | 4. Add from GitHub (Cursor UI) | Use rules, skills, or agents without cloning. In Cursor IDE go to Settings → Rules / Skills / Agents, click Add new → Add from GitHub, and paste this repo’s clone URL. Add only what you need. | | 5. Fork or pick & choose | Fork this repo for your team, or download only the individual components you need and drop them into your existing .cursor setup. | | 6. Handbook website | Browse components or read Guidelines (Cursor IDE topics) in the browser — GitHub Pages. |

Improvements welcome. See CONTRIBUTING.md to add or improve rules, skills, hooks, agents, or commands.

---

Use as a Cursor Plugin

This repository also works as a Cursor plugin. A plugin packages rules, skills, agents, commands, MCP servers, and hooks so they can be installed and reused across projects without copying files manually.

Local use (no publishing required)

1. Ensure this repo contains .cursor-plugin/plugin.json.
2. Symlink it into Cursor local plugins: ln -s /path/to/cursor-handbook ~/.cursor/plugins/local/cursor-handbook
3. Reload Cursor (Developer: Reload Window).
4. Open any project and enable/use the plugin components in Settings.

Use in another project

• Open the other project in Cursor.
• Install/select cursor-handbook from local plugins.
• Toggle rules/skills as needed for that project.

Public discovery in Cursor Marketplace

For public marketplace listing, submit this plugin for review at cursor.com/marketplace/publish. Marketplace listing requires review and approval.

For the complete guide (beginner + team/admin workflows), see Plugins guide.

---

The Problem

Every time you open Cursor IDE, your AI assistant starts from zero. It doesn't know your:

• Code conventions and architecture patterns
• Security policies (and happily hardcodes your API keys)
• Testing thresholds (and runs the full 100K-token test suite when you just wanted a type check)
• Handler patterns, naming conventions, or folder structure

You end up repeating yourself, burning tokens, and fixing the same mistakes. cursor-handbook fixes this permanently.

---

Before vs After

| Before cursor-handbook | After cursor-handbook | | -------------------------------------- | ------------------------------------------- | | AI hardcodes API keys | Security rules block it | | AI runs full test suite (~100K tokens) | Uses type-check (~10K) or single-file tests | | You repeat conventions every session | Rules remember them — always on | | Inconsistent code across team | One rules engine, one standard | | No guardrails on expensive ops | Hooks warn or block dangerous commands |

---

Who is this for?

| Audience | Benefit | | ------------------- | ------------------------------------------------------------------- | | Solo developers | Consistent AI behavior without repeating yourself every session | | Teams | Shared standards; everyone gets the same guardrails and conventions | | Enterprises | Security, compliance, and token efficiency built in from day one |

---

How It Works

sequenceDiagram
    actor Dev as Developer
    participant C as Cursor IDE
    participant H as Hooks
    participant R as Rules (47)
    participant A as Agents/Skills
    participant Code as Codebase

    Dev->>C: Types prompt or command
    C->>H: beforeSubmitPrompt
    H->>H: Enrich with project context
    H->>H: Guard against expensive ops
    H->>R: Pass enriched prompt
    R->>R: Apply 47 always-on rules
    Note over R: Token efficiency<br/>Security guardrails<br/>Code standards<br/>Architecture patterns
    R->>A: Route to agent/skill/command
    A->>Code: Generate or modify code
    Code->>H: afterFileEdit
    H->>H: Post-edit checks
    H->>H: Auto-format
    H->>H: Secret scan
    H-->>Dev: Clean, standards-compliant code

    Note over Dev,Code: Every interaction is governed by your rules.<br/>No exceptions. No token waste.

Layer 1 — Pre-Processing: Hooks inject project context and block dangerous commands before your prompt reaches the AI. Layer 2 — Rules Engine: 47 always-on rules enforce token efficiency, security, architecture, code standards, database conventions, and testing thresholds. Layer 3 — Specialized Processing: The right component activates — an agent, skill, or command — based on your prompt. Layer 4 — Post-Processing: Hooks validate output, auto-format, scan for secrets, and verify coverage.

Typical Workflows

| What You Want | What You Type | What Happens | | -------------------- | -------------------------------- | -------------------------------------------------------------- | | Build a new endpoint | "Create a POST /orders endpoint" | Skill triggers full handler scaffolding (9 files, 7-step flow) | | Review code | /code-reviewer | Agent checks security, performance, correctness, tests | | Fix broken tests | /testing-agent fix these tests | Skill diagnoses failures, fixes mocks, verifies coverage | | Quick validation | /type-check | Runs type check (~10K tokens) instead of full tests (~100K) | | Deploy safely | /deployment-agent | Agent generates deployment checklist with rollback plan | | Optimize a query | /query-opt-agent | Agent runs EXPLAIN ANALYZE, rewrites query, adds indexes |

---

What's Inside

graph TD
    ROOT["cursor-handbook<br/>208 Components"]

    ROOT --- RULES["📏 Rules — 47"]
    ROOT --- AGENTS["🤖 Agents — 62"]
    ROOT --- SKILLS["🛠️ Skills — 50"]
    ROOT --- COMMANDS["⚡ Commands — 37"]
    ROOT --- HOOKS["🔗 Hooks — 12"]
    ROOT --- TEMPLATES["📄 Templates — 9"]

    style ROOT fill:#1a1a2e,stroke:#e94560,color:#fff,stroke-width:3px
    style RULES fill:#3b82f6,stroke:#2563eb,color:#fff
    style AGENTS fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style SKILLS fill:#22c55e,stroke:#16a34a,color:#fff
    style COMMANDS fill:#ef4444,stroke:#dc2626,color:#fff
    style HOOKS fill:#06b6d4,stroke:#0891b2,color:#fff
    style TEMPLATES fill:#f59e0b,stroke:#d97706,color:#000

| Layer | Count | What It Does | How It's Triggered | | ------------- | ----- | -----------------