Cursor Cloud Agent Best Practices: Scoping, Review, Cost

Cursor's first recommendation is to configure a cloud agent's environment before you run it. Like a human developer, the agent does better work when its environment is set up correctly. Every other practice on this page depends on it, because an agent can't check its own work in a machine that can't run your code.

The order matters for a second reason. Cursor's trigger for the skills advice is an agent that has trouble testing its changes, and an agent whose environment never came up right shows exactly that symptom. If you reach for skills first, you may write careful instructions for a test command the machine could never have run.

Mistakes here cost more than they would on your laptop, because each fix needs a new Build. Saving an environment configuration starts one, and it runs your install command to completion before agents can start from it. Until an environment has a successful Build, agents start on Cursor's default image, without your setup.

Check which environment an agent will use, too. Cursor takes the first match: your personal saved environment, then the team's saved environment, then a committed .cursor/environment.json for single-repo runs. A saved environment reads that committed file only when its environment.json location points at it. Cursor suggests a personal environment for testing a new configuration before the whole team gets it. While yours exists, your runs on that repository won't pick up changes to the team environment.

Before you run a cloud agent, Cursor recommends checking three prerequisites. Each one decides whether the agent can run and test your code or stalls on missing access.

The three checks cost different amounts to fix. Secrets and egress are dashboard settings, quick to change once you know which one failed. Local testability belongs to the repo. If your tests need services that a VM can't reach, that is repo work, and it has to happen before an agent can help.

The egress check applies only if someone turned restrictions on. Cloud agents have internet access by default, and users, teams and saved environments can each restrict it. Even under Allowlist only, Cursor's own services and source control providers stay reachable. With a thin allowlist, the clone can succeed and the package install can still fail at the first host nobody added. The security and network page covers the modes.

If a cloud agent has trouble testing its changes, Cursor recommends configuring it with skills and an AGENTS.md file. Cursor asks you to treat the agent as a smart but low-context human developer, and the way to get the right behavior is to give it the context it needs. You can commit project skills to the repo, sync personal skills for your own cloud agents, or publish a skill so teammates can install it.

Cursor describes its own setup. Its AGENTS.md lists tips for running and debugging the most-used microservices in its mono-repo. It also keeps many skills on how to test and debug key services, each with clear instructions on when to use it.

That split is also a context decision. A root AGENTS.md applies to the whole project, and nested AGENTS.md files apply when the agent works in their directory, so every line in the root file reaches every task. A skill loads on demand, when the agent judges it relevant, which makes it the right home for six paragraphs about one microservice.

The description carries the most weight. Cursor's skills docs say the agent uses it to decide relevance, and a skill without one is unlikely to be picked on its own, though you can still invoke it by name.

When a skill never fires, rewrite its description first. Cursor Agent SkillsReusable, model-invoked instructions (a SKILL.md with a name, description and steps) the agent loads only when its description matches the task. Press Enter for the full definition. covers the format.

For conventions, Cursor recommends rules. Cloud agents can read and follow rules at three levels, and each level has its own reach.

Cursor has often found that agents are limited by the tools they can reach. It recommends using MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. and creating custom tools, so the agent can work with the same systems a human developer would.

A missing tool doesn't show up as an error. For example, an agent with no database access has nothing to query, so it works from whatever schema file is in the repo and writes something plausible against it. You find out at review, when the diff assumes a column that was renamed two releases ago.

To find the gap, read the transcript for workarounds. An agent that greps for a value it could have queried, or writes a parser for output a tool could have returned structured, is pointing at the next tool to add. Cursor's advice to iterate on tools based on how the agent uses them applies to the tools you already gave it, too.

Cursor's advice goes past granting tools: build tools the agent is good at using, then iterate on them based on how it uses them. Cursor's own example shows where ordinary dev commands fall short.

The example holds two separate problems. A forgotten argument is an interface problem, and the fix is a command with fewer things to get wrong. Noisy build logs are an output problem. Nothing in a log marks which lines your team stopped reading years ago, so quieter output tends to work better than more instructions about what to ignore.

On a small team, we would skip this one. Cursor is describing a mono-repo full of microservices and a CLI built to drive it, and that CLI is a project with an owner and a maintenance cost. A repo with one test command and one dev server gets most of the benefit from an AGENTS.md line that names the command and the two flags people forget.

Work back through the same order: environment, access, context, then tools. Environment and access failures leave their evidence in logs and runs, not in the diff.

An install failure shows up first, in the environment's Builds tab, because the install command runs during a Build, before any agent starts from it. An access failure gets further, then stalls on one specific thing, such as an unset variable or a host that won't resolve. Context and tool problems are the confusing case: every command succeeds and the change is still wrong. Read the transcript closely when that happens.

The environment and access checks are mostly one-time setup. Skills and custom tools are not. Cursor's wording on tools is to iterate based on observations of how the agent uses them, and skills need the same treatment, because you learn which descriptions fail to fire only once agents run against them. Plan a second pass after the first bad week, not on day one.