> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/working-efficiently-with-ai/writing-effective-prompts.md).

# Writing effective prompts

## **The Principle**

Your agent can already see your entire Sandbox Studio project: the file tree, the engine source, every existing class and pattern. What it needs from you is direction, not description. The most effective prompts are specific about intent and explicit about where to look.

## **What an Effective Prompt Contains**

### **Your goal**

What you are building and why it exists in the game. One or two sentences. "A pickup node that adds ammo to the player inventory when the player overlaps it."

### **Where to look**

Name the closest existing file as a reference and identify which engine system is involved. Your agent will read those files and use them as its pattern. "Look at HealthPickup.ts for the overlap pattern. The inventory system is in InventoryComponent.ts."

When you want your agent to use a specific engine pattern, tell it to check the .engine folder. "Check the engine source for how SceneNode attachment works before implementing this" gives your agent access to the authoritative reference rather than a guess.

### **What to create or modify**

Be explicit about whether this is a new class or an addition to something that already exists, and which file to change or create.

### **What to leave alone**

Name anything that should not be touched. Your agent can see every file in your project, so it needs to know what is in scope and what is not. "Do not modify InventoryComponent.ts directly. Only call its public methods."

## **Bring files into context**

Attach or open the file in the chat so your agent reads it as part of the current task. That is the most reliable way to anchor your agent to the exact pattern you want it to follow.

In Cursor, an @ reference does that load. `@PlayerPawn.ts` in your prompt means your agent is working from the actual code, not a general understanding of what a player Pawn might look like. Use an explicit file attachment whenever pattern accuracy matters.

{% hint style="warning" %}
*NOTE: Naming a file in prose and attaching the file are not the same thing. An attachment (in Cursor, `@filename`) actively loads the file into the current context window. When pattern accuracy matters, attach the file.*
{% endhint %}

## **Plan Before You Build**

For any feature that involves multiple systems or new classes, ask your agent to plan before it builds. "Before writing any code, explore the relevant files and outline how you will structure this" produces a plan grounded in the real project rather than a generic one.

Review the plan. Check that the classes it names exist, that the files it intends to modify are the right ones, and that the engine patterns it references match what is in .engine. This is the moment to catch a wrong assumption before it becomes wrong code.

{% hint style="info" %}
*TIP: After your agent produces a plan, ask it to verify: "Confirm your planned approach matches the pattern in the engine source." Catching a discrepancy here saves a full round of correction.*
{% endhint %}

## **Practical Guidance**

* Point your agent at an existing file that uses the pattern you want. Let it read the pattern rather than describing it yourself.
* Attach the most relevant files at the start of the prompt. In Cursor, use an @file reference.
* Tell your agent to check the .engine folder when you want it to verify engine behaviour before implementing.
* Structure every prompt around four things: goal, where to look, what to change, what to leave alone.
* For complex features, ask for a plan first and ask your agent to ground it in the actual project files.
* State what is out of scope explicitly. Your agent can see every file and needs to know which ones are not part of this task.

## **Common Mistakes**

| Mistake                                                                      | What to do instead                                                                            |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Writing long explanations of how the engine works                            | Point your agent at the engine source or a relevant existing file. It can read the real thing |
| Giving no file references and expecting your agent to find the right pattern | Name the closest existing file as a reference in the prompt                                   |
| Forgetting to name what is out of scope                                      | Explicitly state which files or systems should not be modified                                |
| Asking for implementation without a plan on complex features                 | Ask for a plan grounded in the actual project files first                                     |
| Naming files in prose instead of attaching them                              | Attach the file so it loads into context. In Cursor, use `@filename`                          |
| Not asking your agent to verify its plan against the engine source           | Add "verify against .engine" as a step before implementation begins                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://studio-docs.sandbox.game/working-efficiently-with-ai/writing-effective-prompts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
