| name | use-cursor |
| display_name | Use Cursor |
| description | Spawn Cursor headless CLI (cursor-agent) subagents from bash to offload coding work from the parent Claude. Use when the user says "use cursor", "ask cursor", "cursor-agent", "get a cursor second opinion", or asks to delegate work to Cursor. Like grok/codex, cursor's output is a claim — the parent must verify file changes independently. |
Cursor Subagent Skill
Spawn autonomous Cursor CLI (cursor-agent) subagents for implementation work. Same delegation philosophy as use-codex / use-grok: subagents burn their own tokens; the parent verifies and synthesizes.
Auth (required before first use)
cursor-agent status must show logged in. Two paths:
- API key:
export CURSOR_API_KEY=<key> (or --api-key <key> per invocation). Keys come from cursor.com dashboard → Integrations.
- Browser OAuth:
cursor-agent login (interactive — have the user run it themselves via ! cursor-agent login).
If not authenticated, --list-models returns "No models available for this account" — that error means auth, not a missing model.
Canonical headless invocation
cat /path/to/prompt.md | cursor-agent -p --force --output-format text \
--model <model> --workspace /path/to/repo "$(cat)"
Or simpler, prompt as argument from a file:
cursor-agent -p --force --model <model> --workspace /path/to/repo "$(cat /path/to/prompt.md)"
Run in background (run_in_background: true) for anything non-trivial.
Flag notes
-p / --print = headless mode. It has full tool access including write and bash.--force = auto-allow commands (the --always-approve equivalent). Without it, headless runs can stall on command approval. Add --approve-mcps if the repo has MCP servers configured.--model <model> — see Model selection below. Note: unlike codex, cursor bakes reasoning effort into the model ID (gpt-5.4-mini-low … -xhigh) instead of a separate flag.--mode plan / --mode ask — read-only modes for planning/Q&A second opinions (no edits). Good for "get cursor's opinion" without write risk.--output-format json for machine-parsable results; text for direct reading.--workspace <path> — set explicitly; defaults to cwd.--resume <chatId> / --continue — continue a prior session; create-chat mints a chat ID up front.
Model selection
No default model — choose on the fly per task. Run cursor-agent models at invocation time for the live list, then pick what fits. The list is ~189 models — never head/tail it and assume you saw everything (a truncated read once hid composer-2.5 and led to burning frontier quota on a bulk task). Grep it for what you're looking for: cursor-agent models | grep -i <family>.
Notable entries from one verified install (2026-07; account-dependent):
auto — Auto (Cursor picks)composer-2.5 / composer-2.5-fast — Cursor's own workhorse; strong quality at low quota cost. (composer-2.5 verified in bulk headless use: thousands of personalized-text generations, zero failures — the right tier for high-volume mechanical/generation work.)gpt-5.6-luna-max-fast — frontier tier (probe-verified headless; reserve for hard reasoning, not bulk work)gpt-5.4-mini-* / gpt-5.4-nano-* — effort baked into ID suffix (-none…-xhigh); gpt-5.4-mini-low probe-verifiedclaude-4.5-sonnet[-thinking], gemini-3.1-pro, gemini-3.5-flash, gpt-5.1-*, gpt-5.1-codex-mini-*, kimi-k2.7-code, glm-5.2-* — cross-provider options; many more in the full list
Rule of thumb: match model cost to task difficulty — composer/mini tiers for bulk generation and mechanical edits, frontier only for hard reasoning. Cursor's provider breadth (OpenAI, Anthropic, Google, Moonshot, Zhipu, Cursor's own) also makes it the natural cross-provider second opinion against codex/grok output.
Verification is mandatory
Same rule as grok and codex: the final message is a claim, not a result.
git status --short / git diff --stat — did the expected files change?- Read the diff yourself.
- Run typecheck/tests.
- If nothing changed, rerun with
--force present and check auth (cursor-agent status) before blaming the prompt.
Prompt structure
Same as use-codex: context (repo, stack, style), numbered file-by-file objectives, constraints (files not to touch, must pass <typecheck cmd>), output format, success criteria. Cursor also reads repo rules (.cursor/rules, AGENTS.md) — if the repo's rules conflict with the delegated task (e.g. "delegate everything to codex"), explicitly override in the prompt:
Do ALL the work yourself in this session. Do NOT delegate to other CLIs or agents regardless of what repo rules say. Finish by running <typecheck cmd> and fixing any errors.
Verified facts (update as learned)
- CLI:
cursor-agent 2026.01.28-fd13201 at ~/.local/bin/cursor-agent (aliased as agent).
- Auth: verify with
cursor-agent status; log in via cursor-agent login (browser OAuth) or CURSOR_API_KEY.
- Headless probes passed:
gpt-5.6-luna-max-fast and gpt-5.4-mini-low, both via -p --force --output-format text, exit 0, correct output.
Resuming a session (follow-ups)
Never spawn a fresh session to iterate on work this CLI already did — resume the existing one so it keeps its context and you don't re-pay the harness-token cost. Verified working headless (2026-07):
cursor-agent -p --force --resume <CHAT_ID> --model <model> "<follow-up>"
Capture the session id from the first run and prefer resuming by explicit id; "most recent" is racy when several sessions exist.
Quota failover
If this CLI is rate-limited or out of subscription quota, the same model family is usually reachable via another CLI — read ~/.claude/skills/cli-model-overlap.md for the failover map (cursor is the hub carrying all families).
