# cursor-sdk

A skill for anyone driving Cursor agents from TypeScript: which call shape to use, local or cloud runtime, and where errors come from.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 14099
- Author: cursor
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cursor/plugins/tree/HEAD/cursor-sdk/skills/cursor-sdk/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/cursor-sdk

## What it does

The skill switches on while you build an app, a script or a CI step on top of `@cursor/sdk`. That package runs Cursor agents from code, outside the IDE. Local runtime touches files on your machine; cloud runtime works against a cloned repo and ends in a pull request.

You get `SKILL.md` plus a `references/` folder: runtime choice, auth, `CursorAgentError` and retries, event streaming, MCP server setup, sub-agents and `Agent.resume`. One reference holds ready patterns such as a PR review bot or scheduled triage.

All three invocation shapes ship with code: `Agent.prompt` for a single shot, `Agent.create` with `agent.send` when you want a stream or follow-ups, `Agent.resume` to carry on an earlier agent. Sort out `CURSOR_API_KEY` before the first call. Without it you get a 401 and nothing else, which is where most first runs die.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill cursor-sdk -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cursor-sdk/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cursor-sdk/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill cursor-sdk -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cursor-sdk/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill cursor-sdk -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cursor-sdk/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cursor/plugins cursor-sdk
```

2. **Manually: put the files in place**
- File: `.github/skills/cursor-sdk/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill cursor-sdk -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cursor/plugins --path cursor-sdk/skills/cursor-sdk
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cursor-sdk/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill cursor-sdk -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cursor/plugins/tree/HEAD/cursor-sdk/skills/cursor-sdk/SKILL.md

## When to use it
- Run a Cursor agent from a CI pipeline without opening the IDE
- Decide between local and cloud runtime for a given job
- Debug a 401 and pass `CURSOR_API_KEY` correctly
- Tell `Agent.prompt` apart from `Agent.create` plus `agent.send`
- Wire an MCP server into an agent started from a script

## Example prompts
- Write a `@cursor/sdk` script that calls `Agent.prompt` to refactor `src/utils.ts` and prints the status.
- Build a GitHub Action step: `Agent.create`, stream events to the log, then a follow-up asking for a regression test.
- I want to continue the agent with the id from last run — show me the `Agent.resume` call.

## Similar
- [setup-local-sdk](https://affpapa.org/en/nevibecode/skills/setup-local-sdk.md) — skill · 2900 installs
- [zapier-sdk](https://affpapa.org/en/nevibecode/skills/zapier-sdk.md) — skill · 1000 installs
- [kernel-typescript-sdk](https://affpapa.org/en/nevibecode/skills/kernel-typescript-sdk.md) — skill · 403 installs
- [appwrite-cli](https://affpapa.org/en/nevibecode/skills/appwrite-cli.md) — skill · 1900 installs
- [claude-sdk-integration-patterns](https://affpapa.org/en/nevibecode/skills/claude-sdk-integration-patterns.md) — skill · 434 installs
- [qdrant-clients-sdk](https://affpapa.org/en/nevibecode/skills/qdrant-clients-sdk.md) — skill · 61 installs

From the same set: [cursor/plugins](https://affpapa.org/en/nevibecode/by/cursor/plugins.md) — 47 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md