Agent SDK

Appearance

Scaffold an agent with Cursor ​

Turn an idea into a verified agent while Cursor guides you through each decision.

What does the create-agent skill do? ​

The bundled create-agent skill turns your goal into a small working project. Have Cursor read that file and follow it.

Where to find the file depends on how you got the package:

  • Reading these docs on a hosted site? Run agent-sdk install-skills to copy every package skill into ~/.cursor/skills/agentkit/, where Cursor discovers them by name.
  • Installed @cursor/july as a dependency? The skill ships inside the package at node_modules/@cursor/july/skills/create-agent/SKILL.md.
  • Working in the monorepo? It's at packages/agent-serve/skills/create-agent/SKILL.md.

Cursor will:

  • Ask only for choices missing from your prompt
  • Recommend defaults based on what you want to build
  • Show you the plan and file tree before writing files
  • Create the agent after you confirm the plan
  • Run structural checks, a real turn, and a smoke eval

Use this skill for a new agent. Use convert-automation when the starting point is a Cursor Automation in the dashboard. Use hillclimb (skills/hillclimb/SKILL.md) when an existing agent works but needs better results.

How do I start a guided scaffold? ​

Describe the outcome and any constraints you already know:

Build a local weather agent for the playground. Give it one tool for current conditions and add a smoke eval. Guide me through the remaining decisions.

More detail means fewer questions. Include a channel, runtime, model, or required integration when those choices are fixed.

Which choices will Cursor ask me to make? ​

Cursor fills gaps in two short rounds:

  • Identity: purpose, project name, and location
  • Runtime: local or cloud
  • Model: the default model or another Cursor model
  • Channels: playground and HTTP, Slack, GitHub, a webhook, or a schedule
  • MCP connections: remote or local MCP servers
  • Capabilities: tools, skills, subagents, hooks, seed files, approvals, and evals

Questions adapt to your goal. A playground chat agent won't get cloud-repository questions. A local agent won't get cloud setup questions.

What happens before Cursor writes files? ​

Cursor shows one plan with the choices it made and the folders it will create. Choose Scaffold it to continue or Adjust something to change the plan.

No files change before you approve this step.

What will Cursor create? ​

A first version usually includes:

  • agent/agent.ts for the model and runtime
  • agent/instructions.md for the always-on prompt
  • One or two tools under agent/tools/
  • Any channels or MCP connections you selected
  • evals/evals.config.ts and one smoke eval

Cursor keeps the first version small. Side-effecting server tools use needsApproval. Deterministic setup, such as fetching a pull request, stays in host code instead of model instructions.

See Project layout for every supported folder.

How does Cursor verify the scaffold? ​

Cursor checks the project in this order:

  1. Run agent-sdk validate and fix every error
  2. Inspect the discovered surface with info --json
  3. Call each server tool directly with validated sample input
  4. Run one end-to-end model turn
  5. Run the smoke eval
  6. Run the project's TypeScript check

Validation, discovery, direct server-tool calls, and server startup work without a Cursor credential. Model turns and evals need CURSOR_API_KEY or a saved agent-sdk login.

What happens after the first agent works? ​

Choose one to three fixed inputs, define what should improve, and name what must stay unchanged. Then have Cursor follow skills/hillclimb/SKILL.md.

The hillclimb skill measures a baseline, changes one lever, runs the same inputs again, and adds an eval for each improvement you keep.