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