cursor

# Cursor CLI Skill Guide

## Baseline Rules

Always apply these for programmatic (headless) execution:
- `-p "<prompt>"` — required for headless mode
- `--output-format text` — recommended for clean output capture

## Command Templates

### New Task (analysis/read-only)
```bash
agent -p "<prompt>" --mode ask --output-format text
```

### New Task (with file edits)
```bash
agent -p "<prompt>" --mode agent --output-format text
```

### New Task (planning only)
```bash
agent -p "<prompt>" --mode plan --output-format text
```

### With model selection
```bash
agent -p "<prompt>" --model gpt-5 --output-format text
```

### Resume Session (latest)
```bash
agent resume -p "<prompt>" --output-format text
```

### Resume Session (specific)
```bash
agent --resume="<chat-id>" -p "<prompt>" --output-format text
```

### List Previous Sessions
```bash
agent ls
```

## Execution Modes

| Task Type | Flag | Notes |
| --- | --- | --- |
| Analysis, review, Q&A | `--mode ask` | Read-only, no file changes |
| Create or edit files | `--mode agent` | Full agent capabilities |
| Planning, architecture | `--mode plan` | Generates plan without execution |

## Model Selection

When the calling agent specifies requirements, translate to flags:

| Requirement | Flag | Notes |
| --- | --- | --- |
| Default / high-quality | `--model gpt-5` | Best for complex reasoning |
| Fast / cheap | `--model gpt-4o` | Quick, straightforward tasks |
| Claude | `--model claude-sonnet` | Anthropic model option |

If not specified, use default model (no flag needed).

## Output Formats

| Format | Flag | Use Case |
| --- | --- | --- |
| Text | `--output-format text` | Programmatic processing, CI/automation |
| Default | (none) | Interactive/human-readable output |

## Cloud Agent Handoff

For complex tasks requiring cloud processing, prefix the prompt with `&`:
```bash
agent "& refactor the auth module and add comprehensive tests"
```

## Interpreting Results

### Success indicators
- Clean text output with expected content
- Exit code 0
- Response addresses the original request

### Failure indicators
- Non-zero exit code
- Error messages in output
- Missing expected deliverables

### Scope creep indicators
- Mentions of "I also..." or "While I was at it..."
- Changes to files not mentioned in the original request
- Response describes work beyond the original request

### Redirection indicators
- Output describes different work than requested
- "Instead of X, I did Y..."
- Solving a different problem than specified

## After Completion

Report to user: "You can resume this Cursor session by saying 'cursor resume'."

### Session Management
- `agent ls` — List all previous conversations
- `agent resume` — Resume most recent session
- `agent --resume="<id>"` — Resume specific session by ID

## Error Handling

- If command exits non-zero: stop and report the error
- If output contains error messages: summarize and report
- If output contains warnings: summarize and ask how to proceed

## Reference

### Useful Patterns

```bash
# Code review (read-only)
agent -p "Review src/auth.py for security issues" --mode ask --output-format text

# Implement feature
agent -p "Add input validation to the login form" --mode agent --output-format text

# Generate plan
agent -p "Plan the migration from REST to GraphQL" --mode plan --output-format text

# Continue previous work
agent resume -p "Now add unit tests for the changes"

# Cloud-powered complex task
agent "& analyze codebase architecture and suggest improvements"
```

### Interactive Mode

For complex multi-step tasks, you may run `agent` without `-p` to enter interactive mode:
```bash
agent
```
Then provide prompts conversationally. Use this when:
- The task requires back-and-forth dialogue
- You need to inspect intermediate results before continuing
- The task scope may evolve based on findings