cursor-sdk skill for Claude Code: run Cursor agents in code
A skill for anyone driving Cursor agents from TypeScript: which call shape to use, local or cloud runtime, and where errors come from.
npx skills add cursor/plugins --skill cursor-sdk -a claude-codeWhat cursor-sdk 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.
What it helps with
- 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_KEYcorrectly - Tell
Agent.promptapart fromAgent.createplusagent.send - Wire an MCP server into an agent started from a script
Example prompts for the agent
- Write a
@cursor/sdkscript that callsAgent.promptto refactorsrc/utils.tsand 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.resumecall.
How to install cursor-sdk
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill cursor-sdk -a claude-code2Manually: put the files in place
~/.claude/skills/cursor-sdk/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cursor-sdk/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill cursor-sdk -a codex2Manually: put the files in place
.agents/skills/cursor-sdk/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill cursor-sdk -a cursor2Manually: put the files in place
.cursor/skills/cursor-sdk/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cursor/plugins cursor-sdk2Manually: put the files in place
.github/skills/cursor-sdk/SKILL.md1Skills CLI (Vercel)
npx skills add cursor/plugins --skill cursor-sdk -a gemini-cli2Platform CLI
gemini skills install https://github.com/cursor/plugins --path cursor-sdk/skills/cursor-sdkManually: put the files in place
.devin/skills/cursor-sdk/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add cursor/plugins --skill cursor-sdk -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cursor-sdk
How do I install cursor-sdk in Claude Code?
Run npx skills add cursor/plugins --skill cursor-sdk -a claude-code. The skill lands at ~/.claude/skills/cursor-sdk/SKILL.md.
What does cursor-sdk do?
It guides work against @cursor/sdk: picks the call shape, explains local versus cloud runtime, and covers errors and streaming.
What is needed before an agent can run?
CURSOR_API_KEY set in the environment and a model id such as composer-2. Miss the key and every request comes back 401.
