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.
CODEBLOCK0
Bash Tool Parameters
| Parameter | Type | Description |
|---|
| INLINECODE1 | string | Shell command to execute |
| INLINECODE2 |
boolean |
Required! Allocates pseudo-terminal for interactive CLIs |
|
workdir | string | Working directory (agent only sees this folder's context) |
|
background | boolean | Run in background, returns sessionId for monitoring |
|
timeout | number | Timeout in seconds (kills process on expiry) |
|
elevated | boolean | Run on host instead of sandbox (if allowed) |
Quick Start
CODEBLOCK1
The Pattern: workdir + background + pty
For longer tasks, use background mode:
CODEBLOCK2
Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
Command Flags Reference
| Flag | Description |
|---|
| INLINECODE7 | Initial prompt for the agent |
| INLINECODE8 / INLINECODE9 |
Auto-approve all operations (dangerous but fast) |
|
--model <model> | Specify model (gpt-5, sonnet-4, opus-4, gemini, grok, etc.) |
|
--workspace <path> | Working directory |
|
-w, --worktree [name] | Run in isolated git worktree |
|
--print |
Non-interactive mode, output to console |
|
--mode <mode> | Execution mode: plan (read-only planning), ask (Q&A) |
|
--plan | Plan mode (read-only, no file modifications) |
|
--cloud | Cloud mode |
|
--resume | Resume previous session |
|
--trust | Trust workspace (headless mode only) |
Execution Modes
Interactive Mode (default)
CODEBLOCK3
Auto-Execute Mode (--yolo)
CODEBLOCK4
Plan Mode (--plan)
CODEBLOCK5
Ask Mode (--mode ask)
CODEBLOCK6
Non-Interactive Mode (--print) ⭐ Unique Feature
Cursor's unique --print mode, ideal for scripting and CI/CD:
CODEBLOCK7
Use cases:
- - CI/CD integration
- Automation scripts
- Batch tasks
- Scenarios requiring parsed results
Git Worktree Isolation
For parallel processing of multiple independent tasks:
CODEBLOCK8
Parallel Issue Fixing
Use git worktrees to fix multiple issues simultaneously:
CODEBLOCK9
Batch PR Reviews
⚠️ NEVER review PRs in OpenClaw's own project directory!
CODEBLOCK10
Batch Review Multiple PRs
CODEBLOCK11
Process Tool (Background Task Management)
| Action | Description |
|---|
| INLINECODE20 | List all running sessions |
| INLINECODE21 |
Check if session is still running |
|
log | Get session output (supports offset/limit) |
|
write | Send raw data to stdin |
|
submit | Send data + newline (simulate Enter) |
|
send-keys | Send key presses |
|
paste | Paste text |
|
kill | Terminate session |
Model Selection
CODEBLOCK12
Auto-Notify on Completion
For long-running tasks, append a wake trigger to your prompt:
CODEBLOCK13
This triggers immediate notification instead of waiting for heartbeat.
Authentication
CODEBLOCK14
⚠️ Rules
- 1. Always use pty:true - Will hang without PTY
- Use background for long tasks - Don't block main thread
- --yolo for building - Auto-approve changes
- --plan for reviewing - Read-only analysis
- --print for scripting - Non-interactive, parseable output
- Use -w worktree for isolation - Parallel task processing
- NEVER start in ~/.openclaw/ - It'll read your soul docs!
- 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.
Cursor Agent 技能
使用 Cursor CLI（agent 命令）执行编码任务。支持多种前沿模型（GPT-5、Claude Opus/Sonnet、Gemini、Grok 等）。
⚠️ 需要 PTY 模式！
Cursor Agent 是一个交互式终端应用程序，需要 PTY 才能正常工作。
bash
✅ 正确
bash pty:true command:agent 你的提示词
❌ 错误 - 没有 PTY 会挂起
bash command:agent 你的提示词
Bash 工具参数
| 参数 | 类型 | 描述 |
|---|
| command | 字符串 | 要执行的 Shell 命令 |
| pty |
布尔值 |
必需！ 为交互式 CLI 分配伪终端 |
| workdir | 字符串 | 工作目录（agent 只能看到此文件夹的上下文） |
| background | 布尔值 | 后台运行，返回 sessionId 用于监控 |
| timeout | 数字 | 超时时间（秒）（超时后终止进程） |
| elevated | 布尔值 | 在主机上运行而非沙箱（如果允许） |
快速开始
bash
检查状态并登录
agent status
agent login
列出可用模型
agent --list-models
快速任务（交互模式）
bash pty:true command:agent 为 API 调用添加错误处理
指定工作目录
bash pty:true workdir:~/Projects/myproject command:agent 构建一个贪吃蛇游戏
模式：workdir + background + pty
对于较长的任务，使用后台模式：
bash
启动后台任务
bash pty:true workdir:~/project background:true command:agent --yolo 重构认证模块
返回 sessionId，使用 process 工具监控
process action:list
process action:log sessionId:XXX
process action:poll sessionId:XXX
发送输入
process action:submit sessionId:XXX data:yes
终止
process action:kill sessionId:XXX
为什么 workdir 很重要： Agent 会在一个专注的目录中启动，不会四处读取不相关的文件（比如你的 soul.md 😅）。
命令标志参考
| 标志 | 描述 |
|---|
| prompt | Agent 的初始提示词 |
| --yolo / --force |
自动批准所有操作（危险但快速） |
| --model
| 指定模型（gpt-5、sonnet-4、opus-4、gemini、grok 等） |
| --workspace | 工作目录 |
| -w, --worktree [name] | 在隔离的 git worktree 中运行 |
| --print | 非交互模式，输出到控制台 |
| --mode | 执行模式：plan（只读规划）、ask（问答） |
| --plan | 规划模式（只读，不修改文件） |
| --cloud | 云模式 |
| --resume | 恢复之前的会话 |
| --trust | 信任工作区（仅限无头模式） |
执行模式
交互模式（默认）
bash
bash pty:true workdir:~/project command:agent 构建一个深色模式切换按钮
自动执行模式（--yolo）
bash
自动批准所有操作，快速执行
bash pty:true workdir:~/project command:agent --yolo 重构认证模块
规划模式（--plan）
bash
只读模式，生成计划但不执行
bash pty:true workdir:~/project command:agent --plan 分析代码库结构
问答模式（--mode ask）
bash
仅问答，不修改文件
bash pty:true command:agent --mode ask 解释认证流程如何工作
非交互模式（--print）⭐ 独特功能
Cursor 独特的 --print 模式，非常适合脚本和 CI/CD：
bash
非交互执行，输出到控制台
bash pty:true command:agent --print 生成代码库摘要
JSON 输出（适合解析）
bash pty:true command:agent --print --output-format json 列出所有 API 端点
流式 JSON（实时处理）
bash pty:true command:agent --print --output-format stream-json 分析项目
使用场景：
- - CI/CD 集成
- 自动化脚本
- 批量任务
- 需要解析结果的场景
Git Worktree 隔离
用于并行处理多个独立任务：
bash
在隔离的 worktree 中运行
bash pty:true workdir:~/project command:agent -w fix-issue-78 修复登录 bug
指定基础分支
bash pty:true workdir:~/project command:agent -w feature-x --worktree-base develop 添加功能 X
并行问题修复
使用 git worktrees 同时修复多个问题：
bash
1. 为每个问题创建 worktrees
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main
2. 在每个 worktree 中启动 agent（后台 + PTY）
bash pty:true workdir:/tmp/issue-78 background:true command:agent --yolo 修复问题 #78：登录 bug。提交并推送。
bash pty:true workdir:/tmp/issue-99 background:true command:agent --yolo 修复问题 #99：API 超时。提交并推送。
3. 监控进度
process action:list
process action:log sessionId:XXX
4. 创建 PR
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. 清理
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99
批量 PR 审查
⚠️ 永远不要在 OpenClaw 自己的项目目录中审查 PR！
bash
克隆到临时目录
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
在规划模式下审查（只读）
bash pty:true workdir:$REVIEW_DIR command:agent --plan 审查此 PR 的安全问题和代码质量
清理
trash $REVIEW_DIR
批量审查多个 PR
bash
获取所有 PR 引用
git fetch origin +refs/pull//head:refs/remotes/origin/pr/
并行启动多个 agent
bash pty:true workdir:~/project background:true command:agent --plan 审查 PR #86。git diff origin/main...origin/pr/86
bash pty:true workdir:~/project background:true command:agent --plan 审查 PR #87。git diff origin/main...origin/pr/87
监控
process action:list
将结果发布到 GitHub
gh pr comment 86 --body <审查内容>
Process 工具（后台任务管理）
检查会话是否仍在运行 |
| log | 获取会话输出（支持 offset/limit） |
| write | 向 stdin 发送原始数据 |
| submit | 发送数据 + 换行（模拟回车） |
| send-keys | 发送按键 |
| paste | 粘贴文本 |
| kill | 终止会话 |
模型选择
bash
列出可用模型
agent --list-models
指定模型
bash pty:true command:agent --model opus-4 复杂的重构任务
bash pty:true command:agent --model gpt-5 构建一个 CLI 工具
bash pty:true command:agent --model gemini 分析这个 Python 代码库
完成时自动通知
对于长时间运行的任务，在提示词末尾添加唤醒触发器：
bash
bash pty:true workdir:~/project background:true command:agent --yolo 构建一个待办事项 REST API。
完全完成后，运行：openclaw system event --text \完成：已构建待
