diegosouzapw 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)
agent -p "<prompt>" --mode ask --output-format text
New Task (with file edits)
agent -p "<prompt>" --mode agent --output-format text
New Task (planning only)
agent -p "<prompt>" --mode plan --output-format text
With model selection
agent -p "<prompt>" --model gpt-5 --output-format text
Resume Session (latest)
agent resume -p "<prompt>" --output-format text
Resume Session (specific)
agent --resume="<chat-id>" -p "<prompt>" --output-format text
List Previous Sessions
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 &:
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 conversationsagent resume— Resume most recent sessionagent --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
# 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:
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