The agent works on its own in a cloud environment, so your prompt is most of what it knows about the task. A clear prompt saves time, avoids rework, and gives you a smaller change to review. Use this guide when you start a new thread or when the agent’s result is not what you expected.
Before you begin
- Start a thread with a repository and branch, or an environment. See Composer and context.
- Know the built-in agents. Ask answers questions, Plan writes a plan, and Agent changes code. See Agent, Ask, and Plan.
Steps
Step 1: Pick the agent that matches the task
Choose the agent in the agent picker below the prompt box before you send the message.
| You want to | Pick | Example |
|---|---|---|
| Understand code without changing it | Ask | Where is the session timeout set? |
| Agree on an approach before any code changes | Plan | Plan how to move the config loader to environment variables. |
| Change code, run commands, or open a pull request | Agent | Fix the failing date test and open a pull request. |
You can switch agents in the same thread. The agent keeps the earlier messages as context, so an Ask answer or a Plan carries over to Agent.
Step 2: Say what should change and why
State the outcome you want, not only the symptom. Include the reason when it affects the solution.
Product search is case-sensitive, so "Laptop" does not match "laptop".
Make search case-insensitive for product names and descriptions.Step 3: Point the agent to the right place
Name files, folders, functions, routes, or error messages when you know them. The agent can search the repository, but a starting point makes it faster and more accurate.
The bug is in src/services/search.js, in the filterProducts function.
The route that calls it is GET /api/products in src/routes/products.js.Paste the exact error message or stack trace. Attach a screenshot or log file if the problem is visual or the log is long. See Attach files.
Step 4: Say how to check the work
Tell the agent which tests or commands prove the change works. The agent can run commands in its environment, so it can check its own work before it finishes.
Add a unit test for mixed-case queries in tests/search.test.js.
Run npm test and fix any failures before you finish.Step 5: Set limits
Say what the agent must not change. This keeps the diff small and easy to review.
Do not change the response shape of the API. Do not add new dependencies.
Only edit files under src/services and tests.Step 6: Ask for the pull request when you are ready
The agent opens a pull request only when you ask. Ask in the same prompt for small, safe changes, or in a follow-up after you review the diff. Say what the description should cover.
When the tests pass, commit the changes and open a pull request against
main. In the description, explain the root cause.See Pull requests.
Example: a complete prompt
This prompt combines all the steps above:
Product search is case-sensitive, so "Laptop" does not match "laptop".
Make it case-insensitive for product names and descriptions.
The logic is in filterProducts in src/services/search.js.
Add a unit test for mixed-case queries in tests/search.test.js, run
npm test, and fix any failures. Do not change the API response shape or
add dependencies.
When the tests pass, open a pull request against main and explain the
root cause in the description.Steer the agent with follow-ups
You don’t need a perfect first prompt. Reply in the same thread to correct or extend the work. The agent continues on the same working branch with the context of the whole thread.
| Situation | Follow-up |
|---|---|
| The plan uses the wrong approach | “Use the existing logger in src/lib/log.js instead of console.log.” |
| The change is too broad | “Revert the changes to the README. Keep only the search fix.” |
| A test is missing | “Also add a test for an empty search query.” |
| Specific lines need changes | Add review comments in the Git panel and send them. See Send review comments back to the agent. |
To stop the agent while it is working, select Stop response, then send a corrected message. To run the last response again, select Retry.
Use skills for instructions you repeat
If you paste the same checklist or conventions into many prompts, turn them into a skill. The agent reads the skill when your task matches it. To make sure it uses a skill, name it in your prompt:
Use the api-conventions skill to add a GET /orders/{id} endpoint.See Skills overview.
Verify
A good prompt usually gives you:
- For longer tasks, a to-do list from the agent that matches what you asked for.
- A diff in the Git panel that touches only the files you expected.
- A final message that says which checks the agent ran and their results. If the result misses the mark, compare it with your prompt. The gap is often a missing location, a missing check, or a missing limit.
Best practices
- One task per thread: split large work into several threads. Smaller changes are faster to review and merge.
- Plan before big changes: use Plan for changes that touch many files, then switch to Agent to build it.
- Be specific, not long: a few precise sentences work better than a page of background.
- Write prompts you can check: if you can’t say how to verify the result, ask Ask or Plan first.
- Keep secrets out of prompts: never paste passwords, tokens, or keys into a message.
Troubleshooting
- The agent changed more than you wanted: add limits (“Only edit …”, “Do not change …”) and ask it to revert the extra changes.
- The agent stopped without running tests: say which command to run and that it must pass before the agent finishes.
- The agent can’t find a tool or service: the repository alone may not be enough. Use an environment with setup and start commands. See Add environment variables and setup commands.
- The answer is generic: point the agent to files, functions, or error messages, or attach a log or screenshot.