> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runspark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Agent Instructions

> How to give your agent clear, effective instructions

Your agent's behavior is shaped by the instructions you give it. Better instructions = better agent. Here's how to write them well.

## The Basics

Your agent has two main instruction files:

* **SOUL.md** — who the agent *is* (personality, tone, core behaviors)
* **AGENTS.md** — what the agent *does* (rules, workflows, specific tasks)

You set these up during onboarding, and you can update them anytime through chat:

> "Update your instructions: always ask for the customer's budget before generating a quote"

## What Makes Good Instructions

### Be Specific, Not Vague

<Tabs>
  <Tab title="✅ Specific">
    "When a new lead comes in, review their info, check our pricing guide for the right tier, generate a quote based on their requirements, and draft a personalized response email for my review."
  </Tab>

  <Tab title="❌ Vague">
    "Handle new leads"
  </Tab>
</Tabs>

### Include Rules and Boundaries

Tell your agent what it should and shouldn't do:

* "Never quote a price without checking the pricing guide first"
* "Always get approval before sending any external emails"
* "If you're unsure about something, ask rather than guessing"

### Give Examples

If you want a specific output format, show your agent what it looks like:

> "Format quotes like this:
>
> * 60 guests × $18/person = $1,080
> * 15 pizzas × $17 = $255
> * Tax (9.2%): \$122.82
> * **Total: \$1,457.82**"

### Define Priorities

Tell your agent what matters most:

> "Priority order: (1) respond to hot leads within 5 minutes, (2) follow up on warm leads daily, (3) generate weekly pipeline reports"

## Updating Instructions

You can update your agent's instructions in two ways:

1. **Ask in chat** — "Add a new rule: always CC the manager on quotes over \$5,000"
2. **Edit directly** — go to Agent Settings and modify the SOUL.md or AGENTS.md content

When you tell your agent something in chat, it updates its own files. You don't need to edit config files manually.

## Common Mistakes

<Warning>
  **Don't overload with instructions.** A focused agent with 10 clear rules outperforms one with 50 vague guidelines. Start simple, add rules as situations come up.
</Warning>

* **Too many rules** — your agent can't prioritize when everything is "important"
* **Contradictory instructions** — "be concise" and "include all details" confuse the agent
* **No examples** — telling an agent "write professional emails" means nothing without showing what "professional" looks like to you
* **Forgetting to mention edge cases** — "what if the customer asks for a refund?" needs to be addressed