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

# Writing instructions

> Best practices for writing effective Agent instructions

## Overview

Instructions are the most important part of an Agent. They define how the Agent behaves, what it should do, and how it should approach the task. You can write them manually or use Write with AI to generate a starting point.

In general, specificity improves results. Clear goals, step-by-step guidance, relevant context, and explicit references to tools or documents all help the Agent perform more reliably.

## Key Concepts

### Purpose

Start by clearly describing what the Agent is meant to do.

<Tip>
  Example: "Your task is to help me prepare for discovery calls. Gather relevant background information and produce a concise summary that helps me understand who the customer is, what they do, and how we might fit."
</Tip>

### Step-by-Step Guidance

Break the workflow into numbered steps. This makes the Agent's process easier to follow and improves consistency.

```text theme={null}
1. Review the customer's website and recent news
2. Check the CRM for past interactions
3. Search for key contacts on LinkedIn
4. Compile findings into a brief summary
```

### References to the Right Context

You can point the Agent to specific Documents, Integrations, Tools, or other Agents. For example, you might ask it to review a specific document in one step, check HubSpot in another, or call another Agent as part of the workflow.

To insert these references, type the `@` character in the instructions field or click the insert icon.

To add a subagent, select an Agent from that menu. See [Delegating to subagents](#delegating-to-subagents) below for details.

### Variables for Reusable Workflows

Use `{{ }}` to define variables the user fills in when running the Agent, such as `{{Customer}}` or `{{Deal}}`. This is useful for reusable workflows like a Customer Health Agent, where the Agent can run against any company based on the input provided.

```text theme={null}
Research {{Customer}} and provide a health score based on:
- Recent interactions
- Product usage
- Support tickets
```

## Delegating to subagents

An Agent can hand off a focused task to another Agent, called a subagent. The subagent runs on its own, with its own instructions, knowledge, and tools, and returns a summary of what it found or did. This keeps the main Agent's workflow simple and lets you reuse specialists you have already built.

### Add a subagent

In the instructions field, type `@` (or click the insert icon) and select an Agent. The Agents you select are the ones this Agent is allowed to delegate to. Reference the subagent in the step where it should run.

<Tip>
  Example step: "For each account, delegate to @CRM Researcher to pull the latest opportunities and open support tickets, then summarize the risks."
</Tip>

### When to delegate

* **Reuse a specialist**: Build one Agent that does a job well, such as deep CRM research or competitor analysis, and call it from higher-level Agents instead of duplicating the logic.
* **Split independent work**: Break a large task into focused subtasks the Agent can run separately, such as researching several accounts.
* **Keep context focused**: Push noisy retrieval into a subagent and get back only the summary, so the main Agent stays focused on the final output.

### Write clear delegation steps

A subagent does not see the full conversation or the parent Agent's context, so give it a self-contained task.

* State exactly what to find or produce, and what to return.
* Keep each delegated task focused and independent so it can run on its own.
* Delegate to a few focused Agents rather than chaining many; deep chains of subagents are slower and harder to follow.

## Best Practices

<AccordionGroup>
  <Accordion title="Be Clear and Specific" icon="bullseye">
    Provide specific objectives and detailed instructions. Longer prompts with relevant context outperform short queries.
  </Accordion>

  <Accordion title="Provide Context" icon="book">
    Supply sufficient background information. Modern AI models can process complex information effectively.
  </Accordion>

  <Accordion title="Structure Logically" icon="list">
    Follow a logical order: role assignment, tone setting, background information, detailed task description with rules.
  </Accordion>

  <Accordion title="Include Examples" icon="lightbulb">
    Show, don't just tell. Examples of desired outputs work better than descriptions of what you want.
  </Accordion>

  <Accordion title="Define a Persona" icon="user">
    Always define a persona to set the tone of the response. This guides how the model communicates.
  </Accordion>

  <Accordion title="Address Edge Cases" icon="shield">
    Provide instructions for handling unusual situations. Focus on base cases first, then add edge case handling.
  </Accordion>

  <Accordion title="Test and Iterate" icon="rotate">
    Evaluate prompts under various scenarios and refine based on results. Prompt engineering is an iterative process.
  </Accordion>
</AccordionGroup>

## Example Instruction Structure

```text theme={null}
# Role
You are [specific role] for [company/context].

# Task
Given [input], your job is to [specific task].

# Guidelines
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

# Output Format
[Describe expected format]

# Examples
Input: [example input]
Output: [example output]

# Constraints
- Only use information from the provided materials
- If unsure, say so rather than guessing
- [Other constraints]
```

## Create Instructions with AI

Ask the LLM in Realm to create instructions for you:

<Steps>
  <Step title="Open Chat">
    Start a new chat session.
  </Step>

  <Step title="Select an LLM">
    Choose Claude, Gemini, or GPT.
  </Step>

  <Step title="Describe Your Task">
    Explain what you want the Agent to accomplish.
  </Step>

  <Step title="Get a Prompt">
    The AI will generate an optimized prompt for you.
  </Step>
</Steps>

<Note>
  Modern LLMs excel at creating effective prompts for themselves or other models, often producing better results than manually crafted prompts.
</Note>

## Common Mistakes to Avoid

<Warning>
  **Don't:**

  * Use vague instructions like "be helpful"
  * Assume the AI knows your company context
  * Give contradictory instructions
  * Make instructions too long without structure
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Knowledge Selection" icon="folder" href="/agents/knowledge-selection">
    Configure what knowledge your Agent can access
  </Card>

  <Card title="Tools & Actions" icon="wrench" href="/agents/tools-and-actions">
    Enable your Agent to take actions in external systems
  </Card>
</CardGroup>