Cursor

## When to Use

User wants to operate Cursor as a real coding environment instead of a vague AI editor: choose the right surface, shape repo context, set rules correctly, use `cursor-agent`, run Background Agents, review with Bugbot, or decide whether MCP and remote execution are acceptable.

Use this skill when the hard part is not "write code" but "make Cursor behave predictably" across editor chat, Agent or Ask flows, CLI runs, project rules, repo indexing, remote agents, GitHub integration, and privacy-sensitive work.

## Architecture

Memory lives in `~/cursor/`. If `~/cursor/` does not exist, run `setup.md`. See `memory-template.md` for structure.

```text
~/cursor/
|-- memory.md            # Durable activation boundaries and workflow defaults
|-- repo-profiles.md     # Per-repo conventions, trust posture, and verification expectations
|-- rules-notes.md       # Project-rule strategy, legacy rule cleanup, and instruction hierarchy notes
|-- privacy.md           # Indexing, ignore, remote execution, and data-handling defaults
|-- remote-workflows.md  # Background Agent, Bugbot, and GitHub integration decisions
`-- incidents.md         # Repeated failures, wrong-surface runs, and recovery patterns
```

## Quick Reference

Load only the smallest file needed for the current blocker.

| Topic | File |
|-------|------|
| Setup guide | `setup.md` |
| Memory template | `memory-template.md` |
| Install and choose the right Cursor surface | `install-and-surfaces.md` |
| Rules, context hierarchy, and mode choice | `rules-and-context.md` |
| `cursor-agent`, non-interactive runs, and MCP boundaries | `cli-and-mcp.md` |
| Background Agents, Bugbot, and GitHub-connected workflows | `background-agents-and-bugbot.md` |
| Privacy mode, indexing, and ignore files | `privacy-and-indexing.md` |
| Recovery playbooks for auth, bad context, and remote-run mistakes | `troubleshooting.md` |

## Requirements

- Cursor installed and usable on the target machine, or permission to guide installation.
- `cursor-agent` available when the task depends on CLI or automation workflows.
- `git` available for repo-aware work, diff review, branch handling, Background Agents, or Bugbot.
- Explicit user approval before enabling Background Agents, granting GitHub app write access, using remote MCP servers, or running high-trust non-interactive commands.
- Treat model names, mode behavior, CLI flags, and remote-workflow features as live product surface: verify against official Cursor docs or current CLI help instead of assuming stale behavior.

## Operating Coverage

This skill treats Cursor as an operational coding system, not as generic editor advice. It covers:
- editor-side usage across Agent, Ask, Manual, and custom mode patterns
- project rules through `.cursor/rules`, user rules, and repo-level agent guidance, with `.cursorrules` treated as legacy
- context shaping through repo boundaries, indexing, and ignore files
- local and non-interactive `cursor-agent` workflows, including resume and MCP-aware execution
- Background Agents and Bugbot when work shifts from local interaction to remote GitHub-connected execution
- privacy, data exposure, and review discipline when Cursor features move code or prompts off the local machine

## Data Storage

Keep only durable Cursor operating context in `~/cursor/`:
- which repos, teams, or task types are approved for Cursor use
- preferred surface by task type: editor, CLI, Background Agent, or Bugbot
- rule hierarchy decisions and recurring `.cursor/rules` patterns that worked
- privacy and trust defaults around indexing, ignore files, GitHub integration, and remote MCP
- repeated failures such as wrong repo scope, ignored rules, unsafe non-interactive runs, or remote review noise

## Core Rules

### 1. Lock the Cursor Surface First
- Name the active surface before doing anything else: editor Agent, Ask, Manual, custom mode, `cursor-agent`, Background Agent, or Bugbot.
- Each surface changes permissions, context loading, and review expectations.
- Advice that ignores the surface usually causes the wrong workflow or trust level.

### 2. Establish the Instruction Hierarchy Before Prompting
- Check for project rules in `.cursor/rules`, repo agent guidance, and any team-level user rules before asking Cursor to act.
- Treat `.cursorrules` as a legacy format that may still exist but should not be your default design target.
- If rules conflict or are too broad, fix the rule layout before expanding the prompt.

### 3. Shape Context Deliberately
- Control what Cursor sees through repo selection, indexing posture, and ignore files instead of assuming it "just knows the repo."
- Use `.cursorignore` and `.cursorindexingignore` for context control, but never treat them as perfect secret barriers.
- When a task is narrow, reduce context first instead of adding more instructions later.

### 4. Separate Local Work From Remote Work
- Editor Agent and local CLI use are different from Background Agents and Bugbot.
- Remote GitHub-connected runs can execute commands, fetch code, and generate review output outside the local machine.
- Escalate to remote workflows only when the value is clear and the trust story is explicit.

### 5. Treat Non-Interactive CLI and MCP as High-Trust Modes
- `cursor-agent` is powerful, and non-interactive usage does not deserve casual assumptions about safety.
- Review MCP server scope, host, and side effects before turning it on.
- If a workflow depends on unattended writes, record the exact repo, command goal, and verification path first.

### 6. Make Privacy and Data Flow Explicit
- Cursor requests, indexing, and remote workflows may send code or prompts to Cursor services, GitHub, or user-approved MCP hosts.
- Privacy Mode changes expectations, but it does not make remote features equivalent to local-only execution.
- The user should know what leaves the machine before you enable higher-trust features.

### 7. End With Reviewable Evidence
- A good Cursor run ends with a diff, a check result, or a clear checkpoint, not just "the agent handled it."
- For Background Agents and Bugbot, inspect the output before merging or applying anything locally.
- Leave a concise handoff trail so the next operator can resume without guessing which surface ran what.

## Cursor Traps

- Treating every Cursor feature as local-only -> remote execution and GitHub-connected workflows get approved without real review.
- Dumping instructions into chat before checking `.cursor/rules` or repo agent guidance -> the repo's own guidance loses to prompt churn.
- Assuming `.cursorignore` blocks every possible data path -> terminal and MCP tool calls can still touch things you did not intend.
- Using Background Agents because they are convenient -> remote command execution happens before the trust boundary is discussed.
- Treating `cursor-agent` automation as if it had interactive approvals -> non-interactive runs can widen scope quickly.
- Mixing Bugbot, editor Agent, and local git state without naming ownership -> review noise and duplicated work pile up.
- Assuming an API key means direct provider execution -> Cursor still mediates product behavior and trust boundaries.

## External Endpoints

Only these endpoint categories are allowed unless the user explicitly approves more:

| Endpoint | Data Sent | Purpose |
|----------|-----------|---------|
| https://cursor.com/* | prompts, selected repo context, diffs, integration metadata, and remote-workflow payloads needed by Cursor features | Cursor editor, agent, indexing, Background Agent, and review workflows |
| https://docs.cursor.com/* | doc queries only | Verify current Cursor behavior, feature scope, and integration details |
| https://github.com/* | repository metadata, code, pull-request context, and review actions approved by the user | Background Agents, Bugbot, and GitHub-connected Cursor workflows |
| https://api.github.com/* | repository, branch, PR, and review metadata approved by the user | GitHub API access used by Cursor-connected review and remote execution flows |
| https://{user-approved-mcp-host} | request payloads required by the approved MCP server | Optional MCP tool access beyond the local machine |

No other data is sent externally unless the user explicitly approves more hosts or integrations.

## Security & Privacy

Data that leaves your machine:
- prompts and selected code context sent to Cursor services
- indexing-related code chunks or metadata needed for Cursor codebase features
- optional repo, branch, and PR context when Background Agents or Bugbot use GitHub-connected flows
- optional MCP payloads only for user-approved MCP servers

Data that stays local:
- durable operating notes under `~/cursor/`
- local repo state, local rules, and diffs unless the user enables remote features
- any ignored or unshared files that never enter a Cursor request or approved tool call

This skill does NOT:
- treat `.cursorignore` as a perfect protection layer for secrets
- enable Background Agents, Bugbot, or remote MCP without explicit approval
- claim Cursor requests stay entirely local by default
- assume legacy `.cursorrules` is still the right target for new setups
- modify its own skill files

## Trust

By using this skill, prompts and selected code context may be sent to Cursor services, plus optional GitHub and user-approved MCP hosts.
Only install if you trust those services with that data.

## Scope

This skill ONLY:
- helps operate Cursor safely across editor, CLI, rules, indexing, remote agents, and review workflows
- structures repo work into the right local or remote execution surface
- keeps durable notes for approved repos, rule strategy, privacy posture, and recurring failure fixes

This skill NEVER:
- blur the line between local editor help and remote Background Agent execution
- claim ignore files solve every privacy or access problem
- recommend unattended high-trust Cursor runs as a default
- treat Cursor as just another generic chat wrapper

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `agentic-engineering` - Strengthen multi-agent workflow design, review discipline, and blast-radius thinking around Cursor usage.
- `coding` - Improve implementation quality once Cursor is operating inside the right repo boundaries.
- `git` - Handle branches, diffs, stashes, and non-destructive repo recovery around Cursor-driven changes.
- `api` - Reuse request-debugging and integration patterns when Cursor work touches external services.
- `workflow` - Turn recurring Cursor tasks into cleaner, repeatable operating procedures.

## Feedback

- If useful: `clawhub star cursor`
- Stay updated: `clawhub sync`