---
name: cursor-agent
description: Guide for delegating complex coding tasks to Cursor Agent via the cursor-acp extension. Use when users ask to use Cursor Agent, want to offload complex coding tasks, or need to use Cursor's AI capabilities from within pi.
---

# Cursor Agent Delegation

This skill provides guidance for using the `cursor-acp` extension to delegate tasks to Cursor Agent.

## Setup (One-time)

The `cursor-acp` extension must be installed:
1. Install Cursor CLI: `curl https://cursor.com/install -fsS | bash`
2. Authenticate: `agent login`
3. Extension auto-loads from `~/.pi/agent/extensions/`

## Available Tools

### `cursor_agent(prompt, mode?)`

Delegate a task to Cursor Agent with full tool access.

| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt` | string | What Cursor Agent should do |
| `mode` | "agent" \| "plan" \| "ask" | Execution mode (default: "agent") |

**Modes:**
- `agent` - Full tool access: read/write files, run commands, use all tools
- `plan` - Read-only analysis: explore codebase, propose plans, no changes
- `ask` - Q&A: answer questions about code, no changes

### `cursor_status`

Check if Cursor CLI is installed and authenticated.

### `cursor_disconnect`

End the Cursor Agent session.

## When to Use

Delegate to Cursor Agent when:
- Complex multi-file code changes needed
- User explicitly asks to use Cursor
- Debugging complex issues across multiple files
- Large refactoring tasks
- Tasks requiring Cursor's specific tool ecosystem

## Examples

```
@cursor_agent Fix the authentication bug in src/auth/login.ts and src/auth/session.ts

@cursor_agent Plan: Analyze the codebase structure and suggest a migration strategy for moving to TypeScript

@cursor_agent Write tests for the UserService class in src/services/UserService.ts
```

## Important Notes

- Cursor Agent runs in a separate process (`agent acp`)
- Each session maintains context across multiple prompts
- Permission requests from Cursor Agent will prompt the user for confirmation
- The working directory defaults to the current pi workspace

## Error Handling

If connection fails:
1. Check `cursor_status` for authentication state
2. Ensure `agent login` has been run
3. Verify Cursor CLI is installed: `agent --version`