Cursor Agent Skill

Execute coding tasks using Cursor CLI (agent command). Supports multiple frontier models (GPT-5, Claude Opus/Sonnet, Gemini, Grok, etc.).

⚠️ PTY Mode Required!

Cursor Agent is an interactive terminal application that requires PTY to work correctly.

# ✅ Correct
bash pty:true command:"agent 'Your prompt'"

# ❌ Wrong - will hang without PTY
bash command:"agent 'Your prompt'"

Bash Tool Parameters

Quick Start

# Check status and login
agent status
agent login

# List available models
agent --list-models

# Quick task (interactive mode)
bash pty:true command:"agent 'Add error handling to the API calls'"

# Specify working directory
bash pty:true workdir:~/Projects/myproject command:"agent 'Build a snake game'"

The Pattern: workdir + background + pty

For longer tasks, use background mode:

# Start background task
bash pty:true workdir:~/project background:true command:"agent --yolo 'Refactor the auth module'"

# Returns sessionId, monitor with process tool
process action:list
process action:log sessionId:XXX
process action:poll sessionId:XXX

# Send input
process action:submit sessionId:XXX data:"yes"

# Terminate
process action:kill sessionId:XXX

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

Command Flags Reference

Execution Modes

Interactive Mode (default)

bash pty:true workdir:~/project command:"agent 'Build a dark mode toggle'"

Auto-Execute Mode (--yolo)

# Auto-approve all operations, fast execution
bash pty:true workdir:~/project command:"agent --yolo 'Refactor the auth module'"

Plan Mode (--plan)

# Read-only mode, generate plan without executing
bash pty:true workdir:~/project command:"agent --plan 'Analyze the codebase structure'"

Ask Mode (--mode ask)

# Q&A only, no file modifications
bash pty:true command:"agent --mode ask 'Explain how the auth flow works'"

Non-Interactive Mode (--print) ⭐ Unique Feature

Cursor's unique --print mode, ideal for scripting and CI/CD:

# Non-interactive execution, output to console
bash pty:true command:"agent --print 'Generate a summary of the codebase'"

# JSON output (ideal for parsing)
bash pty:true command:"agent --print --output-format json 'List all API endpoints'"

# Streaming JSON (real-time processing)
bash pty:true command:"agent --print --output-format stream-json 'Analyze the project'"

Use cases:

• CI/CD integration
• Automation scripts
• Batch tasks
• Scenarios requiring parsed results

Git Worktree Isolation

For parallel processing of multiple independent tasks:

# Run in isolated worktree
bash pty:true workdir:~/project command:"agent -w fix-issue-78 'Fix the login bug'"

# Specify base branch
bash pty:true workdir:~/project command:"agent -w feature-x --worktree-base develop 'Add feature X'"

Parallel Issue Fixing

Use git worktrees to fix multiple issues simultaneously:

# 1. Create worktrees for each issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. Launch agent in each worktree (background + PTY)
bash pty:true workdir:/tmp/issue-78 background:true command:"agent --yolo 'Fix issue #78: login bug. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"agent --yolo 'Fix issue #99: API timeout. Commit and push.'"

# 3. Monitor progress
process action:list
process action:log sessionId:XXX

# 4. Create PRs
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

Batch PR Reviews

⚠️ NEVER review PRs in OpenClaw's own project directory!

# Clone to temp directory
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130

# Review in plan mode (read-only)
bash pty:true workdir:$REVIEW_DIR command:"agent --plan 'Review this PR for security issues and code quality'"

# Cleanup
trash $REVIEW_DIR

Batch Review Multiple PRs

# Fetch all PR refs
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Launch multiple agents in parallel
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor
process action:list

# Post results to GitHub
gh pr comment 86 --body "<review content>"

Process Tool (Background Task Management)

Model Selection

# List available models
agent --list-models

# Specify model
bash pty:true command:"agent --model opus-4 'Complex refactoring task'"
bash pty:true command:"agent --model gpt-5 'Build a CLI tool'"
bash pty:true command:"agent --model gemini 'Analyze this Python codebase'"

Auto-Notify on Completion

For long-running tasks, append a wake trigger to your prompt:

bash pty:true workdir:~/project background:true command:"agent --yolo 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API\" --mode now'"

This triggers immediate notification instead of waiting for heartbeat.

Authentication

# Check login status
agent status

# Login
agent login

# Logout
agent logout

# View account info
agent about

⚠️ Rules

1. Always use pty:true - Will hang without PTY
2. Use background for long tasks - Don't block main thread
3. --yolo for building - Auto-approve changes
4. --plan for reviewing - Read-only analysis
5. --print for scripting - Non-interactive, parseable output
6. Use -w worktree for isolation - Parallel task processing
7. NEVER start in ~/.openclaw/ - It'll read your soul docs!
8. Notify user on completion - Don't leave user guessing

Progress Updates

When spawning background agents:

• Send 1 short message stating what's running
• Only update when something changes:
  • Milestone completed
  • User input needed
  • Error or user action required
  • Task finished (explain what changed)

Learnings

• PTY is essential: Without pty:true, interactive agents hang or output garbage.
• --print is powerful: Cursor's unique non-interactive mode, ideal for CI/CD and scripted tasks.
• --plan for safety: When unsure what the agent will do, use --plan first.
• worktree for parallel: For multiple independent tasks, worktree isolation is the best choice.
• submit vs write: submit sends data + Enter, write sends raw data only.