Skip to content

girijashankarj/cursor-handbook

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

23 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

npm version node version GitHub stars GitHub forks GitHub last commit GitHub issues License MIT Version 208 Components 30%+ Savings

cursor-handbook

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

cursor-handbook website — browse components, read guidelines, search and copy paths

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.

If cursor-handbook helps you, consider giving it a ⭐ — it helps others discover it.


Table of Contents


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.
Loading

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
Loading
Layer Count What It Does How It's Triggered
Rules 47 Enforces coding standards on every AI interaction Automatically — always on
Agents 62 Specialized assistants for complex tasks On demand — /agent-name
Skills 50 Step-by-step guided workflows with checklists Contextually — when patterns match
Commands 37 Lightweight, token-efficient quick actions On demand — /command
Hooks 12 Automation scripts in the AI loop Event-driven — before/after actions
Templates 9 Scaffolding for handlers, components, tests, etc. Referenced by skills and agents

Quick Start (5 minutes)

graph LR
    A["1. Clone"] --> B["2. Setup"] --> C["3. Restart"] --> D["4. Verify"]

    style A fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px
    style B fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px
    style C fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px
    style D fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:2px
Loading

npm (Recommended)

npm package: npmjs.com/package/cursor-handbook

npx cursor-handbook init

You'll be prompted to either copy all components or select by category (frontend, backend, database, cloud, testing, devops, etc.). To skip the prompt:

npx cursor-handbook init --all    # copy everything

Then:

  1. Edit .cursor/config/project.json — replace {{PLACEHOLDER}} values with your project details
  2. Restart Cursor IDE
  3. Use @cursor-setup-agent to further customize components
  4. Remove the package: npm uninstall cursor-handbook

Or install explicitly, then initialize:

npm install -D cursor-handbook
npx cursor-handbook init
# After setup, remove:
npm uninstall cursor-handbook

Alternative: Clone & copy

git clone https://github.com/girijashankarj/cursor-handbook.git .cursor && make -f .cursor/Makefile init

Then edit .cursor/config/project.json and restart Cursor.

For additional setup methods (curl one-liner, Git submodule for teams), see Quick Start docs.


Using the Cursor Setup Agent

The Cursor Setup Agent is the recommended way to adopt cursor-handbook. Instead of manually choosing which components to copy, the agent does it for you.

How it works

graph LR
    A["1. Clone handbook"] --> B["2. Run @cursor-setup-agent"] --> C["3. Agent scans project"] --> D["4. Copies relevant components"]

    style A fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px
    style B fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px
    style C fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px
    style D fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:2px
Loading
  1. Clone cursor-handbook alongside your project (or into a temp directory)
  2. Open your project in Cursor IDE
  3. Run @cursor-setup-agent in the Cursor chat
  4. The agent will:
  • Detect your language, framework, database, testing, CI/CD, and cloud stack
  • Build a component manifest with only the relevant rules, agents, skills, commands, hooks, and templates
  • Show you a summary table and ask for confirmation before copying anything
  • Generate a tailored project.json, CLAUDE.md, and AGENTS.md
  • Print a post-setup checklist

What it detects

Category Signals
Language tsconfig.json, go.mod, Cargo.toml, requirements.txt, pom.xml, file extensions
Framework Dependencies in package.json / requirements.txt (React, Express, Django, Spring, etc.)
Database ORM configs (prisma/, sequelize, typeorm), .sql files, migration folders
Testing jest.config._, vitest, pytest, cypress/, playwright.config._
Infrastructure Dockerfile, terraform/, cdk.json, serverless.yml, cloud SDK deps
CI/CD .github/workflows/, .gitlab-ci.yml, Jenkinsfile

Example

For a TypeScript + Express + PostgreSQL + Jest + Docker project, the agent would install ~120 targeted components (out of 209) and skip irrelevant ones like react.mdc, angular.mdc, python.mdc, and go.mdc.

Full agent spec: .cursor/agents/cursor-setup-agent.md


Token Savings

cursor-handbook is engineered to cut your AI token costs by 30% or more:

pie title Token Usage Comparison (per operation)
    "Type Check (cursor-handbook)" : 10
    "Saved vs Full Tests" : 90
Loading
Without cursor-handbook With cursor-handbook Tokens Saved
Full test suite: ~100K tokens /type-check: ~10K tokens ~90K (90%)
Full lint run: ~50K tokens /lint-check (read_lints): ~2K tokens ~48K (96%)
Full test suite: ~100K tokens /test-single: ~5K tokens ~95K (95%)
Unfiltered context: ~30K tokens Context layering: ~10K tokens ~20K (67%)
Verbose AI output: ~15K tokens Concise guidelines: ~5K tokens ~10K (67%)

Conservative estimate: A developer making 50 AI interactions/day saves ~200K tokens/day — that's real money at scale.


Customization

cursor-handbook is 100% project-driven. Every component adapts to your project through a single file:

How It Adapts to Your Project

graph TB
    PJ["project.json<br/>Your Configuration"]

    PJ --> R["Rules<br/>{{CONFIG.techStack.language}}<br/>{{CONFIG.testing.coverageMinimum}}"]
    PJ --> A["Agents<br/>{{CONFIG.techStack.framework}}<br/>{{CONFIG.paths.handlerBasePath}}"]
    PJ --> S["Skills<br/>{{CONFIG.patterns.handlerFlow}}<br/>{{CONFIG.fileNames.handlerEntry}}"]
    PJ --> CMD["Commands<br/>{{CONFIG.testing.testCommand}}<br/>{{CONFIG.testing.typeCheckCommand}}"]
    PJ --> H["Hooks<br/>{{CONFIG.project.name}}<br/>{{CONFIG.database.softDeleteField}}"]

    style PJ fill:#f59e0b,stroke:#d97706,color:#000,stroke-width:3px
    style R fill:#3b82f6,stroke:#2563eb,color:#fff
    style A fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style S fill:#22c55e,stroke:#16a34a,color:#fff
    style CMD fill:#ef4444,stroke:#dc2626,color:#fff
    style H fill:#06b6d4,stroke:#0891b2,color:#fff
Loading

What You Can Customize

Section What It Controls Example
project Project identity Name, description, repo URL
techStack Language, framework, tools TypeScript + Express or Python + FastAPI
paths Directory structure Where handlers, services, and common code live
domain Business entities Order, Product, Customer + lifecycle states
patterns Code patterns 7-step handler flow, error handling strategy
testing Quality gates 90% coverage, test/lint/type-check commands
database DB conventions Soft delete field, timestamp columns, naming
packages Internal packages @your-org scope, registry URL
conventions Git and workflow Branch prefixes, commit format, PR templates

Ready-Made Stack Presets

Don't start from scratch — pick your stack:

Stack File Language Framework
TypeScript/Express [examples/typescript-express/](examples/typescript-express/) TypeScript Express.js
TypeScript/NestJS [examples/typescript-nest/](examples/typescript-nest/) TypeScript NestJS
Python/FastAPI [examples/python-fastapi/](examples/python-fastapi/) Python FastAPI
Go/Chi [examples/go-chi/](examples/go-chi/) Go Chi
React SPA [examples/react/](examples/react/) TypeScript React
Next.js [examples/nextjs/](examples/nextjs/) TypeScript Next.js
Rust/Actix [examples/rust-actix/](examples/rust-actix/) Rust Actix Web
Kotlin/Spring [examples/kotlin-spring/](examples/kotlin-spring/) Kotlin Spring Boot
Flutter [examples/flutter/](examples/flutter/) Dart Flutter

Copy a preset and customize: cp examples/typescript-express/project.json .cursor/config/project.json


Component Deep Dive

Rules (47) — Your AI's Permanent Memory

Rules are the backbone. They load on every interaction, every time, with zero effort.

graph LR
    M[main-rules] --> ARCH["Architecture (3)"]
    M --> BE["Backend (12)"]
    M --> FE["Frontend (8)"]
    M --> SEC["Security (3)"]
    M --> DB["Database (4)"]
    M --> CLD["Cloud (5)"]
    M --> TST["Testing (5)"]
    M --> OPS["DevOps (6)"]
Loading

Agents (62) — Your On-Demand Specialists

Domain Agent Invocation Best For
Architecture Design Agent /design-agent System design, trade-off analysis
Backend Code Reviewer /code-reviewer PR reviews, security checks
Frontend UI Component Agent /ui-component-agent Accessible components
Testing Testing Agent /testing-agent Write comprehensive tests
Database Query Opt Agent /query-opt-agent Query performance tuning
Security Security Audit Agent /security-audit-agent Comprehensive security audit
Cloud Deployment Agent /deployment-agent Zero-downtime deployments
DevOps CI/CD Agent /ci-cd-agent Pipeline design
Business Requirements Agent /requirements-agent User stories, specs
AI/ML Prompt Agent /prompt-agent Prompt engineering
Docs Docs Agent /docs-agent Technical documentation
Platform DX Agent /dx-agent Developer experience

See COMPONENT_INDEX.md for all 62 agents.

Commands (37) — Token-Efficient Quick Actions

graph LR
    TC["/type-check<br/>~10K tokens"] ---|saves 90K vs| FT["Full Tests<br/>~100K tokens"]
    TS["/test-single<br/>~5K tokens"] ---|saves 95K vs| FT
    LC["/lint-check<br/>~2K tokens"] ---|saves 48K vs| FL["Full Lint<br/>~50K tokens"]

    style TC fill:#22c55e,stroke:#16a34a,color:#fff
    style TS fill:#22c55e,stroke:#16a34a,color:#fff
    style LC fill:#22c55e,stroke:#16a34a,color:#fff
    style FT fill:#ef4444,stroke:#dc2626,color:#fff
    style FL fill:#ef4444,stroke:#dc2626,color:#fff
Loading
Command What It Does Why It's Better
/type-check TypeScript type validation 10K tokens vs 100K for full tests
/lint-check Use read_lints tool 2K tokens vs 50K for full lint
/generate-handler Scaffold API handler Full 9-file handler in seconds
/test-single Test one file only 5K tokens vs 100K for full suite
/audit-deps Vulnerability scan Catch CVEs before shipping
/check-secrets Secret detection Find leaked keys before commit

See COMPONENT_INDEX.md for all 37 commands.


Sharing & Team Adoption

cursor-handbook is designed to scale from solo developer to enterprise teams:

graph TD
    subgraph SOLO ["Solo Developer"]
        S1[Clone cursor-handbook<br/>into .cursor/]
        S2[Customize project.json]
        S3[Commit to your project]
    end

    subgraph TEAM ["Team Sharing"]
        T1[Fork cursor-handbook]
        T2[Add team-specific rules]
        T3[Share as Git submodule<br/>in all team repos]
    end

    subgraph ORG ["Organization-Wide"]
        O1[Maintain internal fork]
        O2[Add org standards<br/>& compliance rules]
        O3[Distribute via<br/>internal package registry]
    end

    subgraph OSS ["Open Source"]
        OS1[Contribute rules & agents<br/>back to cursor-handbook]
        OS2[Share stack-specific<br/>examples]
        OS3[Build community<br/>components]
    end

    SOLO --> TEAM --> ORG
    SOLO --> OSS
    TEAM --> OSS

    style SOLO fill:#22c55e,stroke:#16a34a,color:#fff
    style TEAM fill:#3b82f6,stroke:#2563eb,color:#fff
    style ORG fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style OSS fill:#f59e0b,stroke:#d97706,color:#000
Loading

Adoption Hierarchy

Level Method Best For
Personal Clone directly into .cursor/ Solo developers, personal projects
Team Git submodule in shared repos Small teams (2-10 developers)
Organization Internal fork with org-specific rules Companies with coding standards
Community PR contributions to this repo Open source stack-specific configs

Team Setup (Git Submodule)

git submodule add https://github.com/your-org/cursor-handbook.git .cursor
git commit -m "feat: add cursor-handbook for team standards" && git push

# Other team members
git pull && git submodule update --init && make init

Project Structure

cursor-handbook/
├── .cursor/
│   ├── config/            # project.json, schema, templates
│   ├── rules/             # 47 always-applied and scoped rules
│   ├── agents/            # 62 specialized AI agents
│   ├── skills/            # 50 guided workflows
│   ├── commands/          # 37 quick actions
│   ├── hooks/             # 12 automation scripts
│   ├── templates/         # 9 code templates
│   └── settings/          # IDE settings
├── docs/                  # Full documentation
├── examples/              # 9 stack-specific presets
├── scripts/               # Setup scripts
├── AGENTS.md              # Agent instructions
├── CLAUDE.md              # Claude-specific instructions
├── CONTRIBUTING.md        # Contribution guide
├── COMPONENT_INDEX.md     # Full component reference
├── LICENSE                # MIT License
└── README.md              # You are here

Why You Should Use This

Audience Key Benefits
Individual 30%+ token savings, stop repeating standards, security guardrails, instant scaffolding
Teams Consistent AI behavior, day-one onboarding, codified patterns, compounding cost savings
Organizations Always-on compliance, same standards across 1,000 projects, central governance, measurable ROI

By The Numbers

Metric Value
Components 208
Supported tech stacks 9
Token savings per operation 67-96%
Setup time ~5 minutes
Files to customize 1 (project.json)
Lines to edit ~50
Price Free (MIT License)

Contributing

See CONTRIBUTING.md for guidelines.

graph LR
    A[Fork] --> B[Branch] --> C[Build] --> D[Test in Cursor] --> E[PR]

    style A fill:#22c55e,stroke:#16a34a,color:#fff
    style B fill:#3b82f6,stroke:#2563eb,color:#fff
    style C fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style D fill:#f59e0b,stroke:#d97706,color:#000
    style E fill:#ef4444,stroke:#dc2626,color:#fff
Loading

High-impact areas for contribution:

  • New stack-specific examples (Vue, Django, Rails, Spring, etc.)
  • Specialized agents for niche domains (ML pipelines, game dev, embedded)
  • Translations of documentation
  • Performance benchmarks and case studies

Documentation

Document Description
Architecture System design, data flow, extension points
Quick Start Get running in 5 minutes
Plugins guide Use this repository as a plugin locally, across projects, and in the marketplace
Project Setup Customize rules to your stack
Component Overview How components work together
Best Practices Get the most out of cursor-handbook
Security Guide Security features and policies
Schema Reference Full project.json schema
Component Picker Find the right components for your project type
Component Index Complete list of all 208 components
Handbook website Browse components, read guidelines, search and copy paths
Cursor guidelines Settings, rules, skills, agents, hooks, token efficiency, security, MCP, comparisons, workflows
Non-technical guide Using cursor-handbook without writing code
Contributing How to contribute

Handbook website (GitHub Pages): girijashankarj.github.io/cursor-handbook is built from main by [.github/workflows/pages.yml](.github/workflows/pages.yml). In the repository Settings → Pages, set Source to GitHub Actions once so deployments appear.


Acknowledgments

Built for Cursor IDE — thanks to the Cursor team for building the AI-first code editor that makes projects like this possible. cursor-handbook exists because Cursor's rules, agents, skills, and hooks architecture gives developers real control over their AI workflows.


License

MIT License — use freely in personal and commercial projects. No attribution required (but appreciated).


Stop teaching your AI the same things twice.
Clone cursor-handbook, set your project once, and let 208 components work for you — every prompt, every project, every day.

Get Started  •  npm Package  •  Browse Components  •  Contribute  •  Documentation

About

Open-source rules engine for Cursor IDE — 110 rules, agents, skills, commands that give AI permanent memory of your standards. Demo: 30%+ token savings, blocks hardcoded secrets, type-check instead of 100K-token test runs, consistent code across team.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

Packages

 
 
 

Contributors