{
  "schemaVersion": "1.0",
  "item": {
    "slug": "cursor-cloud-agents",
    "name": "Cursor Cloud Agents",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/ParcostaBot/cursor-cloud-agents",
    "canonicalUrl": "https://clawhub.ai/ParcostaBot/cursor-cloud-agents",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/cursor-cloud-agents",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=cursor-cloud-agents",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SECURITY.md",
      "SKILL.md",
      "references/api-reference.md",
      "scripts/cca-aliases.sh",
      "scripts/cursor-api.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "cursor-cloud-agents",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-02T07:20:54.411Z",
      "expiresAt": "2026-05-09T07:20:54.411Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=cursor-cloud-agents",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=cursor-cloud-agents",
        "contentDisposition": "attachment; filename=\"cursor-cloud-agents-1.3.3.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "cursor-cloud-agents"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/cursor-cloud-agents"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/cursor-cloud-agents",
    "agentPageUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent",
    "manifestUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "⚡ Quick Reference",
        "body": "Most common commands and patterns:\n\n# Launch an agent (uses default model: gpt-5.2)\ncursor-api.sh launch --repo owner/repo --prompt \"Add tests for auth module\"\n\n# Check agent status\ncursor-api.sh status <agent-id>\n\n# Get conversation history\ncursor-api.sh conversation <agent-id>\n\n# Send follow-up message\ncursor-api.sh followup <agent-id> --prompt \"Also add edge case tests\"\n\n# List all agents\ncursor-api.sh list\n\n# Check usage/quota\ncursor-api.sh usage\n\nCommon Options:\n\n--model <name> - Specify model (default: gpt-5.2)\n--branch <name> - Target branch\n--no-pr - Don't auto-create PR\n--no-cache - Bypass cache\n--verbose - Debug output\n--background - Run agent in background mode\n\nBackground Tasks:\n\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background\ncursor-api.sh bg-list\ncursor-api.sh bg-status <task-id>\ncursor-api.sh bg-logs <task-id>\n\nMax Runtime (Background Tasks):\n\n# Default is 24 hours\n cursor-api.sh launch --repo owner/repo --prompt \"...\" --background\n\n# Custom max runtime (2 hours)\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background --max-runtime 7200\n\n# Unlimited runtime (not recommended)\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background --max-runtime 0\n\n# Set default via environment variable\nexport CURSOR_BG_MAX_RUNTIME=43200  # 12 hours\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background\n\nShort Commands (cca aliases):\n\nFor faster daily usage, source the cca-aliases.sh file:\n\nsource scripts/cca-aliases.sh\n\nThen use cca instead of cursor-api.sh:\n\ncca list                    # List agents\ncca launch --repo ...       # Launch agent\ncca status <id>             # Check status\ncca conversation <id>       # Get conversation\ncca followup <id> --prompt  # Send followup\ncca delete <id>             # Delete agent\n\nExit Codes: 0=Success, 1=API Error, 2=Auth, 3=Rate Limit, 4=Repo Access, 5=Invalid Args"
      },
      {
        "title": "Overview",
        "body": "This skill wraps the Cursor Cloud Agents HTTP API, allowing OpenClaw to dispatch coding tasks to Cursor's cloud agents, monitor their progress, and incorporate results."
      },
      {
        "title": "When to Use",
        "body": "Use this skill when you need to:\n\nDelegate coding tasks to Cursor agents running on GitHub repositories\nGenerate code, tests, or documentation on existing codebases\nPerform refactoring or feature implementation asynchronously\nGet a \"second opinion\" on code changes"
      },
      {
        "title": "When NOT to Use",
        "body": "For simple questions that don't require code changes\nWhen you need real-time streaming responses (use local Cursor CLI instead)\nFor tasks outside of GitHub repositories"
      },
      {
        "title": "Authentication",
        "body": "The skill automatically discovers your Cursor API key from these locations (in order):\n\nEnvironment variable: CURSOR_API_KEY\nOpenClaw env file: ~/.openclaw/.env\nOpenClaw local env: ~/.openclaw/.env.local\nProject env: .env in current directory\nCursor config: ~/.cursor/config.json\n\nRecommended: Add to ~/.openclaw/.env:\n\nCURSOR_API_KEY=your_cursor_api_key_here\n\nTo get your API key:\n\nOpen Cursor IDE\nGo to Settings → General\nCopy your API key\n\nVerify it's working:\n\ncursor-api.sh me"
      },
      {
        "title": "Pattern A: Fire-and-Forget",
        "body": "Launch an agent and let it work independently. Check back later.\n\n# Launch agent (uses default model: gpt-5.2)\ncursor-api.sh launch --repo owner/repo --prompt \"Add comprehensive tests for auth module\"\n\n# Launch with specific model\ncursor-api.sh launch --repo owner/repo --prompt \"Add tests\" --model claude-4-opus\n\n# Response: {\"id\": \"agent_123\", \"status\": \"CREATING\", ...}\n\n# Later - check status\ncursor-api.sh status agent_123\n\nNote: If no --model is specified, the default model (gpt-5.2) will be used automatically. You'll see a message indicating which model is being used.\n\nBest for: Tasks that don't need immediate attention, exploratory work"
      },
      {
        "title": "Pattern B: Supervised Dispatch",
        "body": "Launch, monitor, and report results when complete.\n\n# 1. Launch\ncursor-api.sh launch --repo owner/repo --prompt \"Implement user authentication\"\n\n# 2. Poll for completion (check every 60 seconds)\nwhile true; do\n    status=$(cursor-api.sh status agent_123)\n    if [[ $(echo \"$status\" | jq -r '.status') == \"FINISHED\" ]]; then\n        break\n    fi\n    sleep 60\ndone\n\n# 3. Get results\ncursor-api.sh conversation agent_123 | jq -r '.messages[] | select(.role == \"assistant\") | .content'\n\nBest for: Important tasks where you want to report completion"
      },
      {
        "title": "Pattern C: Iterative Collaboration",
        "body": "Launch, review, and send follow-ups to refine work.\n\n# 1. Launch initial task\ncursor-api.sh launch --repo owner/repo --prompt \"Add login page\"\n\n# 2. Review conversation\ncursor-api.sh conversation agent_123\n\n# 3. Send follow-up\ncursor-api.sh followup agent_123 --prompt \"Also add form validation and error handling\"\n\n# 4. Final review when done\ncursor-api.sh conversation agent_123\n\nBest for: Complex tasks requiring multiple iterations"
      },
      {
        "title": "Pattern D: Background Mode",
        "body": "For long-running tasks, launch agents in background mode and check on them later.\n\n# Launch in background\nresult=$(cursor-api.sh launch --repo owner/repo --prompt \"Refactor entire codebase\" --background)\ntask_id=$(echo \"$result\" | jq -r '.background_task_id')\necho \"Task started: $task_id\"\n\n# List active background tasks\ncursor-api.sh bg-list\n\n# Check specific task status\ncursor-api.sh bg-status $task_id\n\n# View logs\ncursor-api.sh bg-logs $task_id\n\n# List all tasks including completed ones\ncursor-api.sh bg-list --all\n\nBackground tasks are monitored automatically and logs are saved to ~/.cache/cursor-api/background-tasks/.\n\nBest for: Long-running tasks (10+ minutes), batch operations, CI/CD integration"
      },
      {
        "title": "List Agents",
        "body": "cursor-api.sh list\n\nReturns all agents with status, repo, and creation time."
      },
      {
        "title": "Launch Agent",
        "body": "cursor-api.sh launch --repo owner/repo --prompt \"Your task description\" [--model model-name] [--branch branch-name] [--no-pr] [--background]\n\nOptions:\n\n--repo (required): Repository in owner/repo format\n--prompt (required): Initial instructions for the agent\n--model (optional): Model to use (defaults to gpt-5.2 if not specified)\n--branch (optional): Target branch name (auto-generated if omitted)\n--no-pr (optional): Don't auto-create a PR\n--background (optional): Run agent in background mode\n\nNote: When launched without --model, the skill automatically uses gpt-5.2 and displays a message indicating which model is being used.\n\nBackground Mode: When using --background, the command returns immediately with a background_task_id. Use bg-list, bg-status, and bg-logs to monitor progress."
      },
      {
        "title": "Check Status",
        "body": "cursor-api.sh status <agent-id>\n\nReturns:\n\nstatus: CREATING, RUNNING, FINISHED, STOPPED, ERROR\nsummary: Summary of work done (if finished)\nprUrl: URL to created PR (if any)"
      },
      {
        "title": "Get Conversation",
        "body": "cursor-api.sh conversation <agent-id>\n\nReturns full message history including all prompts and responses."
      },
      {
        "title": "Send Follow-up",
        "body": "cursor-api.sh followup <agent-id> --prompt \"Additional instructions\"\n\nResumes a stopped or finished agent with new instructions."
      },
      {
        "title": "Stop Agent",
        "body": "cursor-api.sh stop <agent-id>\n\nStops a running agent gracefully."
      },
      {
        "title": "Delete Agent",
        "body": "cursor-api.sh delete <agent-id>\n\nPermanently deletes an agent and its conversation history."
      },
      {
        "title": "List Models",
        "body": "cursor-api.sh models\n\nReturns available models for agent tasks."
      },
      {
        "title": "Account Info",
        "body": "cursor-api.sh me\n\nReturns account information including subscription tier."
      },
      {
        "title": "Verify Repository",
        "body": "cursor-api.sh verify owner/repo\n\nChecks if the specified repository is accessible by Cursor agents.\n\nExit code 4 if repository not accessible."
      },
      {
        "title": "Usage/Cost Tracking",
        "body": "cursor-api.sh usage\n\nReturns usage information including:\n\nAgents used vs. limit\nCompute consumption\nSubscription tier"
      },
      {
        "title": "Clear Cache",
        "body": "cursor-api.sh clear-cache\n\nClears the response cache."
      },
      {
        "title": "Background Task Commands",
        "body": "cursor-api.sh bg-list [--all]\n\nList background tasks. By default, excludes completed tasks. Use --all to include finished tasks.\n\ncursor-api.sh bg-status <task-id>\n\nGet detailed status of a background task including current agent state.\n\ncursor-api.sh bg-logs <task-id>\n\nShow logs for a background task. Logs include status changes and any PR URLs created."
      },
      {
        "title": "Rate Limiting",
        "body": "The skill enforces a 1 request per second rate limit locally to avoid API rate limits. This is applied automatically to all API calls.\n\nIf you hit Cursor's API rate limit (HTTP 429), the script exits with code 3."
      },
      {
        "title": "Caching",
        "body": "GET requests (list, status, conversation, models, me) are cached for 60 seconds by default. To disable caching for a command:\n\ncursor-api.sh --no-cache status agent_123\n\nTo change the cache TTL, set the environment variable:\n\nexport CURSOR_CACHE_TTL=120  # 2 minutes\ncursor-api.sh status agent_123"
      },
      {
        "title": "Exit Codes",
        "body": "CodeMeaning0Success1API error (including non-existent resources)2Authentication missing or invalid3Rate limited4Repository not accessible5Invalid arguments"
      },
      {
        "title": "Testing",
        "body": "The skill includes a comprehensive test suite (cca-comprehensive-test.sh) that validates:\n\nAuthentication: Auto-discovery, missing key, invalid key handling\nAccount Commands: me, usage, models\nAgent Lifecycle: list, launch (with/without model), status, conversation, followup, stop\nError Handling: Invalid formats, missing args, non-existent agents (all return correct exit codes)\nOptions: --verbose, --no-cache, pagination\n\nAll tests pass with proper exit codes. Error conditions are correctly handled and return appropriate exit codes."
      },
      {
        "title": "Concurrent Agent Limits",
        "body": "Based on available documentation and API behavior, Cursor Cloud Agents have the following limits:\n\nTierConcurrent AgentsNotesFree1Limited to basic modelsPro3Access to most modelsUltra5Full model access, priority queue\n\nThese limits are enforced at the account level across all agents. If you exceed the limit, the API returns HTTP 429 with code CONCURRENT_LIMIT.\n\nTo check your current usage:\n\ncursor-api.sh usage | jq '.usage.agentsUsed, .limits.concurrentAgents'\n\nBest practices:\n\nStop finished agents when no longer needed\nUse cursor-api.sh list to monitor active agents\nConsider batching work into fewer, larger agents rather than many small ones\n\nNote: Concurrent limits are subject to change. Check cursor-api.sh usage for your current account limits."
      },
      {
        "title": "1. Always Verify Repository Access",
        "body": "Before launching, verify the repository is accessible:\n\nif cursor-api.sh verify owner/repo >/dev/null 2>&1; then\n    cursor-api.sh launch --repo owner/repo --prompt \"...\"\nelse\n    echo \"Repository not accessible. Install the Cursor GitHub App.\"\nfi"
      },
      {
        "title": "2. Use Clear, Specific Prompts",
        "body": "Good prompt:\n\n\"Add comprehensive unit tests for the auth module in src/auth/, covering login, logout, and token refresh. Use Jest and mock external API calls.\"\n\nBad prompt:\n\n\"Add some tests\""
      },
      {
        "title": "3. Check Usage Before Launching",
        "body": "Monitor your quota:\n\ncursor-api.sh usage | jq '.usage'"
      },
      {
        "title": "4. Clean Up Finished Agents",
        "body": "Delete agents you no longer need:\n\ncursor-api.sh list | jq -r '.[] | select(.status == \"FINISHED\") | .id' | while read id; do\n    cursor-api.sh delete \"$id\"\ndone"
      },
      {
        "title": "5. Choose Appropriate Max Runtime for Background Tasks",
        "body": "Typical task durations:\n\nQuick fixes (typos, small bugs): 5-15 minutes → --max-runtime 900\nFeature implementation: 30-60 minutes → --max-runtime 3600\nLarge refactors: 2-6 hours → --max-runtime 21600\nComplex migrations: 6-24 hours → --max-runtime 86400 (default)\n\n# Check remaining time\n cursor-api.sh bg-status <task-id> | jq '.remaining_seconds'\n\n# Set custom max runtime\n cursor-api.sh launch --repo owner/repo --prompt \"Migrate database schema\" --background --max-runtime 43200  # 12 hours"
      },
      {
        "title": "6. Handle Errors Gracefully",
        "body": "Always check exit codes in scripts:\n\nif ! response=$(cursor-api.sh launch --repo owner/repo --prompt \"...\" 2>&1); then\n    case $? in\n        2) echo \"Authentication error - check CURSOR_API_KEY\" ;;\n        3) echo \"Rate limited - try again later\" ;;\n        4) echo \"Repository not accessible\" ;;\n        *) echo \"API error: $response\" ;;\n    esac\nfi"
      },
      {
        "title": "Follow-up Templates",
        "body": "Use these templates for common follow-up scenarios:"
      },
      {
        "title": "\"Add more tests\"",
        "body": "Also add tests for edge cases: empty input, null values, and maximum length limits."
      },
      {
        "title": "\"Fix the implementation\"",
        "body": "The current implementation doesn't handle [specific case]. Please update it to [requirement]."
      },
      {
        "title": "\"Add documentation\"",
        "body": "Add comprehensive JSDoc comments to all public functions and a brief README section explaining the feature."
      },
      {
        "title": "\"Refactor for clarity\"",
        "body": "Refactor the code to use more descriptive variable names and extract complex logic into helper functions."
      },
      {
        "title": "Companion Setup: CLI Backend",
        "body": "For local tasks (not on GitHub repos), also configure the Cursor Agent CLI as a cliBackend:\n\n// In your OpenClaw config\n{\n  \"cliBackends\": {\n    \"cursor-agent\": {\n      \"command\": \"agent\",\n      \"args\": [\"-p\", \"--force\", \"--output-format\", \"text\"],\n      \"output\": \"text\",\n      \"input\": \"arg\",\n      \"env\": {\n        \"CURSOR_API_KEY\": \"${CURSOR_API_KEY}\"\n      }\n    }\n  }\n}\n\nThis enables cursor-agent as a backend for local file operations, while this skill handles Cloud Agents for GitHub repos."
      },
      {
        "title": "\"Repository not accessible\" (exit code 4)",
        "body": "Ensure the Cursor GitHub App is installed on the repository\nCheck that you have admin/write access to the repo\nVerify the repo name is correct (owner/repo format)"
      },
      {
        "title": "\"Authentication failed\" (exit code 2)",
        "body": "Check that CURSOR_API_KEY is set in your environment\nVerify the API key is valid in Cursor IDE settings\nEnsure the key hasn't expired"
      },
      {
        "title": "\"Rate limited\" (exit code 3)",
        "body": "Wait a few seconds and retry\nCheck your usage with cursor-api.sh usage\nConsider stopping unused agents"
      },
      {
        "title": "Agent stuck in \"CREATING\" status",
        "body": "Agents may take 1-2 minutes to start. If stuck longer:\n\nCheck Cursor status page for outages\nTry stopping and relaunching\nContact Cursor support if persistent"
      }
    ],
    "body": "Cursor Cloud Agents Skill\n⚡ Quick Reference\n\nMost common commands and patterns:\n\n# Launch an agent (uses default model: gpt-5.2)\ncursor-api.sh launch --repo owner/repo --prompt \"Add tests for auth module\"\n\n# Check agent status\ncursor-api.sh status <agent-id>\n\n# Get conversation history\ncursor-api.sh conversation <agent-id>\n\n# Send follow-up message\ncursor-api.sh followup <agent-id> --prompt \"Also add edge case tests\"\n\n# List all agents\ncursor-api.sh list\n\n# Check usage/quota\ncursor-api.sh usage\n\n\nCommon Options:\n\n--model <name> - Specify model (default: gpt-5.2)\n--branch <name> - Target branch\n--no-pr - Don't auto-create PR\n--no-cache - Bypass cache\n--verbose - Debug output\n--background - Run agent in background mode\n\nBackground Tasks:\n\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background\ncursor-api.sh bg-list\ncursor-api.sh bg-status <task-id>\ncursor-api.sh bg-logs <task-id>\n\n\nMax Runtime (Background Tasks):\n\n# Default is 24 hours\n cursor-api.sh launch --repo owner/repo --prompt \"...\" --background\n\n# Custom max runtime (2 hours)\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background --max-runtime 7200\n\n# Unlimited runtime (not recommended)\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background --max-runtime 0\n\n# Set default via environment variable\nexport CURSOR_BG_MAX_RUNTIME=43200  # 12 hours\ncursor-api.sh launch --repo owner/repo --prompt \"...\" --background\n\n\nShort Commands (cca aliases):\n\nFor faster daily usage, source the cca-aliases.sh file:\n\nsource scripts/cca-aliases.sh\n\n\nThen use cca instead of cursor-api.sh:\n\ncca list                    # List agents\ncca launch --repo ...       # Launch agent\ncca status <id>             # Check status\ncca conversation <id>       # Get conversation\ncca followup <id> --prompt  # Send followup\ncca delete <id>             # Delete agent\n\n\nExit Codes: 0=Success, 1=API Error, 2=Auth, 3=Rate Limit, 4=Repo Access, 5=Invalid Args\n\nOverview\n\nThis skill wraps the Cursor Cloud Agents HTTP API, allowing OpenClaw to dispatch coding tasks to Cursor's cloud agents, monitor their progress, and incorporate results.\n\nWhen to Use\n\nUse this skill when you need to:\n\nDelegate coding tasks to Cursor agents running on GitHub repositories\nGenerate code, tests, or documentation on existing codebases\nPerform refactoring or feature implementation asynchronously\nGet a \"second opinion\" on code changes\nWhen NOT to Use\nFor simple questions that don't require code changes\nWhen you need real-time streaming responses (use local Cursor CLI instead)\nFor tasks outside of GitHub repositories\nAuthentication\n\nThe skill automatically discovers your Cursor API key from these locations (in order):\n\nEnvironment variable: CURSOR_API_KEY\nOpenClaw env file: ~/.openclaw/.env\nOpenClaw local env: ~/.openclaw/.env.local\nProject env: .env in current directory\nCursor config: ~/.cursor/config.json\n\nRecommended: Add to ~/.openclaw/.env:\n\nCURSOR_API_KEY=your_cursor_api_key_here\n\n\nTo get your API key:\n\nOpen Cursor IDE\nGo to Settings → General\nCopy your API key\n\nVerify it's working:\n\ncursor-api.sh me\n\nWorkflow Patterns\nPattern A: Fire-and-Forget\n\nLaunch an agent and let it work independently. Check back later.\n\n# Launch agent (uses default model: gpt-5.2)\ncursor-api.sh launch --repo owner/repo --prompt \"Add comprehensive tests for auth module\"\n\n# Launch with specific model\ncursor-api.sh launch --repo owner/repo --prompt \"Add tests\" --model claude-4-opus\n\n# Response: {\"id\": \"agent_123\", \"status\": \"CREATING\", ...}\n\n# Later - check status\ncursor-api.sh status agent_123\n\n\nNote: If no --model is specified, the default model (gpt-5.2) will be used automatically. You'll see a message indicating which model is being used.\n\nBest for: Tasks that don't need immediate attention, exploratory work\n\nPattern B: Supervised Dispatch\n\nLaunch, monitor, and report results when complete.\n\n# 1. Launch\ncursor-api.sh launch --repo owner/repo --prompt \"Implement user authentication\"\n\n# 2. Poll for completion (check every 60 seconds)\nwhile true; do\n    status=$(cursor-api.sh status agent_123)\n    if [[ $(echo \"$status\" | jq -r '.status') == \"FINISHED\" ]]; then\n        break\n    fi\n    sleep 60\ndone\n\n# 3. Get results\ncursor-api.sh conversation agent_123 | jq -r '.messages[] | select(.role == \"assistant\") | .content'\n\n\nBest for: Important tasks where you want to report completion\n\nPattern C: Iterative Collaboration\n\nLaunch, review, and send follow-ups to refine work.\n\n# 1. Launch initial task\ncursor-api.sh launch --repo owner/repo --prompt \"Add login page\"\n\n# 2. Review conversation\ncursor-api.sh conversation agent_123\n\n# 3. Send follow-up\ncursor-api.sh followup agent_123 --prompt \"Also add form validation and error handling\"\n\n# 4. Final review when done\ncursor-api.sh conversation agent_123\n\n\nBest for: Complex tasks requiring multiple iterations\n\nPattern D: Background Mode\n\nFor long-running tasks, launch agents in background mode and check on them later.\n\n# Launch in background\nresult=$(cursor-api.sh launch --repo owner/repo --prompt \"Refactor entire codebase\" --background)\ntask_id=$(echo \"$result\" | jq -r '.background_task_id')\necho \"Task started: $task_id\"\n\n# List active background tasks\ncursor-api.sh bg-list\n\n# Check specific task status\ncursor-api.sh bg-status $task_id\n\n# View logs\ncursor-api.sh bg-logs $task_id\n\n# List all tasks including completed ones\ncursor-api.sh bg-list --all\n\n\nBackground tasks are monitored automatically and logs are saved to ~/.cache/cursor-api/background-tasks/.\n\nBest for: Long-running tasks (10+ minutes), batch operations, CI/CD integration\n\nCommands Reference\nList Agents\ncursor-api.sh list\n\n\nReturns all agents with status, repo, and creation time.\n\nLaunch Agent\ncursor-api.sh launch --repo owner/repo --prompt \"Your task description\" [--model model-name] [--branch branch-name] [--no-pr] [--background]\n\n\nOptions:\n\n--repo (required): Repository in owner/repo format\n--prompt (required): Initial instructions for the agent\n--model (optional): Model to use (defaults to gpt-5.2 if not specified)\n--branch (optional): Target branch name (auto-generated if omitted)\n--no-pr (optional): Don't auto-create a PR\n--background (optional): Run agent in background mode\n\nNote: When launched without --model, the skill automatically uses gpt-5.2 and displays a message indicating which model is being used.\n\nBackground Mode: When using --background, the command returns immediately with a background_task_id. Use bg-list, bg-status, and bg-logs to monitor progress.\n\nCheck Status\ncursor-api.sh status <agent-id>\n\n\nReturns:\n\nstatus: CREATING, RUNNING, FINISHED, STOPPED, ERROR\nsummary: Summary of work done (if finished)\nprUrl: URL to created PR (if any)\nGet Conversation\ncursor-api.sh conversation <agent-id>\n\n\nReturns full message history including all prompts and responses.\n\nSend Follow-up\ncursor-api.sh followup <agent-id> --prompt \"Additional instructions\"\n\n\nResumes a stopped or finished agent with new instructions.\n\nStop Agent\ncursor-api.sh stop <agent-id>\n\n\nStops a running agent gracefully.\n\nDelete Agent\ncursor-api.sh delete <agent-id>\n\n\nPermanently deletes an agent and its conversation history.\n\nList Models\ncursor-api.sh models\n\n\nReturns available models for agent tasks.\n\nAccount Info\ncursor-api.sh me\n\n\nReturns account information including subscription tier.\n\nVerify Repository\ncursor-api.sh verify owner/repo\n\n\nChecks if the specified repository is accessible by Cursor agents.\n\nExit code 4 if repository not accessible.\n\nUsage/Cost Tracking\ncursor-api.sh usage\n\n\nReturns usage information including:\n\nAgents used vs. limit\nCompute consumption\nSubscription tier\nClear Cache\ncursor-api.sh clear-cache\n\n\nClears the response cache.\n\nBackground Task Commands\ncursor-api.sh bg-list [--all]\n\n\nList background tasks. By default, excludes completed tasks. Use --all to include finished tasks.\n\ncursor-api.sh bg-status <task-id>\n\n\nGet detailed status of a background task including current agent state.\n\ncursor-api.sh bg-logs <task-id>\n\n\nShow logs for a background task. Logs include status changes and any PR URLs created.\n\nRate Limiting\n\nThe skill enforces a 1 request per second rate limit locally to avoid API rate limits. This is applied automatically to all API calls.\n\nIf you hit Cursor's API rate limit (HTTP 429), the script exits with code 3.\n\nCaching\n\nGET requests (list, status, conversation, models, me) are cached for 60 seconds by default. To disable caching for a command:\n\ncursor-api.sh --no-cache status agent_123\n\n\nTo change the cache TTL, set the environment variable:\n\nexport CURSOR_CACHE_TTL=120  # 2 minutes\ncursor-api.sh status agent_123\n\nExit Codes\nCode\tMeaning\n0\tSuccess\n1\tAPI error (including non-existent resources)\n2\tAuthentication missing or invalid\n3\tRate limited\n4\tRepository not accessible\n5\tInvalid arguments\nTesting\n\nThe skill includes a comprehensive test suite (cca-comprehensive-test.sh) that validates:\n\nAuthentication: Auto-discovery, missing key, invalid key handling\nAccount Commands: me, usage, models\nAgent Lifecycle: list, launch (with/without model), status, conversation, followup, stop\nError Handling: Invalid formats, missing args, non-existent agents (all return correct exit codes)\nOptions: --verbose, --no-cache, pagination\n\nAll tests pass with proper exit codes. Error conditions are correctly handled and return appropriate exit codes.\n\nConcurrent Agent Limits\n\nBased on available documentation and API behavior, Cursor Cloud Agents have the following limits:\n\nTier\tConcurrent Agents\tNotes\nFree\t1\tLimited to basic models\nPro\t3\tAccess to most models\nUltra\t5\tFull model access, priority queue\n\nThese limits are enforced at the account level across all agents. If you exceed the limit, the API returns HTTP 429 with code CONCURRENT_LIMIT.\n\nTo check your current usage:\n\ncursor-api.sh usage | jq '.usage.agentsUsed, .limits.concurrentAgents'\n\n\nBest practices:\n\nStop finished agents when no longer needed\nUse cursor-api.sh list to monitor active agents\nConsider batching work into fewer, larger agents rather than many small ones\n\nNote: Concurrent limits are subject to change. Check cursor-api.sh usage for your current account limits.\n\nBest Practices\n1. Always Verify Repository Access\n\nBefore launching, verify the repository is accessible:\n\nif cursor-api.sh verify owner/repo >/dev/null 2>&1; then\n    cursor-api.sh launch --repo owner/repo --prompt \"...\"\nelse\n    echo \"Repository not accessible. Install the Cursor GitHub App.\"\nfi\n\n2. Use Clear, Specific Prompts\n\nGood prompt:\n\n\"Add comprehensive unit tests for the auth module in src/auth/, covering login, logout, and token refresh. Use Jest and mock external API calls.\"\n\nBad prompt:\n\n\"Add some tests\"\n\n3. Check Usage Before Launching\n\nMonitor your quota:\n\ncursor-api.sh usage | jq '.usage'\n\n4. Clean Up Finished Agents\n\nDelete agents you no longer need:\n\ncursor-api.sh list | jq -r '.[] | select(.status == \"FINISHED\") | .id' | while read id; do\n    cursor-api.sh delete \"$id\"\ndone\n\n5. Choose Appropriate Max Runtime for Background Tasks\n\nTypical task durations:\n\nQuick fixes (typos, small bugs): 5-15 minutes → --max-runtime 900\nFeature implementation: 30-60 minutes → --max-runtime 3600\nLarge refactors: 2-6 hours → --max-runtime 21600\nComplex migrations: 6-24 hours → --max-runtime 86400 (default)\n# Check remaining time\n cursor-api.sh bg-status <task-id> | jq '.remaining_seconds'\n\n# Set custom max runtime\n cursor-api.sh launch --repo owner/repo --prompt \"Migrate database schema\" --background --max-runtime 43200  # 12 hours\n\n6. Handle Errors Gracefully\n\nAlways check exit codes in scripts:\n\nif ! response=$(cursor-api.sh launch --repo owner/repo --prompt \"...\" 2>&1); then\n    case $? in\n        2) echo \"Authentication error - check CURSOR_API_KEY\" ;;\n        3) echo \"Rate limited - try again later\" ;;\n        4) echo \"Repository not accessible\" ;;\n        *) echo \"API error: $response\" ;;\n    esac\nfi\n\nFollow-up Templates\n\nUse these templates for common follow-up scenarios:\n\n\"Add more tests\"\nAlso add tests for edge cases: empty input, null values, and maximum length limits.\n\n\"Fix the implementation\"\nThe current implementation doesn't handle [specific case]. Please update it to [requirement].\n\n\"Add documentation\"\nAdd comprehensive JSDoc comments to all public functions and a brief README section explaining the feature.\n\n\"Refactor for clarity\"\nRefactor the code to use more descriptive variable names and extract complex logic into helper functions.\n\nCompanion Setup: CLI Backend\n\nFor local tasks (not on GitHub repos), also configure the Cursor Agent CLI as a cliBackend:\n\n// In your OpenClaw config\n{\n  \"cliBackends\": {\n    \"cursor-agent\": {\n      \"command\": \"agent\",\n      \"args\": [\"-p\", \"--force\", \"--output-format\", \"text\"],\n      \"output\": \"text\",\n      \"input\": \"arg\",\n      \"env\": {\n        \"CURSOR_API_KEY\": \"${CURSOR_API_KEY}\"\n      }\n    }\n  }\n}\n\n\nThis enables cursor-agent as a backend for local file operations, while this skill handles Cloud Agents for GitHub repos.\n\nTroubleshooting\n\"Repository not accessible\" (exit code 4)\nEnsure the Cursor GitHub App is installed on the repository\nCheck that you have admin/write access to the repo\nVerify the repo name is correct (owner/repo format)\n\"Authentication failed\" (exit code 2)\nCheck that CURSOR_API_KEY is set in your environment\nVerify the API key is valid in Cursor IDE settings\nEnsure the key hasn't expired\n\"Rate limited\" (exit code 3)\nWait a few seconds and retry\nCheck your usage with cursor-api.sh usage\nConsider stopping unused agents\nAgent stuck in \"CREATING\" status\n\nAgents may take 1-2 minutes to start. If stuck longer:\n\nCheck Cursor status page for outages\nTry stopping and relaunching\nContact Cursor support if persistent"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/ParcostaBot/cursor-cloud-agents",
    "publisherUrl": "https://clawhub.ai/ParcostaBot/cursor-cloud-agents",
    "owner": "ParcostaBot",
    "version": "1.3.3",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/cursor-cloud-agents",
    "downloadUrl": "https://openagent3.xyz/downloads/cursor-cloud-agents",
    "agentUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent",
    "manifestUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/cursor-cloud-agents/agent.md"
  }
}