agent.md — System Prompts

The agent.md file is the system prompt for your agent. Every time a conversation starts (or resumes), the orchestrator injects this Markdown content at the beginning of the LLM context. It’s the single most important file for shaping how your agent behaves.

What goes in agent.md

A good system prompt covers four things:

1. Identity — Who is the agent? What’s its name, role, and tone?
2. Instructions — What should the agent do when the user asks for help? What’s the workflow?
3. Constraints — What should the agent not do? What are the boundaries?
4. Capability guidance — When and how should the agent use its available tools?

Example

You are WeatherBot, a helpful weather assistant running on the Selu platform.

## Your role
- Answer weather-related questions for any location worldwide.
- Use the `weather_lookup` capability to fetch current conditions and forecasts.
- If the user doesn't specify a location, ask them for one.

## Tone
- Friendly, concise, and informative.
- Use plain language — avoid jargon like "synoptic" or "isobar".
- Keep responses under 3 sentences for simple queries.

## Constraints
- Only answer weather-related questions. If the user asks about something else, politely redirect them.
- Never fabricate weather data. If the capability returns an error, say so honestly.
- Do not store or reference the user's location unless they provide it in the current conversation.

Best practices

Tip

Keep your system prompt under 2,000 tokens. Longer prompts increase latency, cost more, and can dilute the model’s attention on what matters.

• Be specific — Vague instructions like “be helpful” don’t add value. Tell the agent exactly what to do and what not to do.
• Reference capabilities by name — If the agent has a weather_lookup tool, mention it explicitly so the model knows it exists and when to use it.
• Use Markdown structure — Headings and bullet points help the model parse your instructions. Wall-of-text prompts perform worse.
• Test iteratively — Small wording changes can significantly alter behaviour. Use selu dev to test locally and refine.

Template variables

Selu supports a small set of template variables inside agent.md that are resolved at runtime:

Variable	Description
{{user_name}}	The display name of the current user.
{{agent_name}}	The display name of this agent.
{{date}}	Current date in ISO 8601 format.
{{capabilities}}	Comma-separated list of available capability names.

Example usage:

You are {{agent_name}}, assisting {{user_name}} on {{date}}.
Your available tools are: {{capabilities}}.

Capability prompts vs agent.md

Each capability can also ship with a prompt.md file. These are appended to the system prompt automatically when that capability is available. Use agent.md for the agent’s core personality and high-level instructions. Use capability prompt.md files for detailed, tool-specific guidance. See Capability Prompts for details.