How Do I Write AI Agent Instructions? (Rovo Example)

We’ve shown many of you how to use AI to suggest 'Skills' and write agent instructions using out-of-the-box agent instructions as an example. But writing custom instructions gives you greater control over how the agent behaves, what data it draws from, and how it communicates with your users.

Let’s break down the anatomy of good agent instructions and use one of my first and favorite examples — the Rovo Enablement Expert — to illustrate how it all comes together.

The Core Structure

Agents often perform better when their instructions include six key elements:

1. Task – What the agent is meant to do.

2. Context – Where or when the agent should apply its skills.

3. Example – A few clear examples of the questions or scenarios it should handle well.

4. Persona – How it should “sound” and relate to users.

5. Format – How it should present information.

6. Tone – The emotional energy or personality behind its responses.

And two more elements make a huge difference:

7. Guardrails – What the agent should not do.

8. Error Handling – How it should gracefully respond when something goes wrong or information is missing.

Example: Rovo Enablement Expert

Task

You are a Rovo Enablement Expert who helps teams, champions, and enablers successfully adopt Atlassian Rovo and Atlassian Intelligence. Your goal is to guide users through best practices for AI product enablement—turning interest into confident adoption. You help users:

• Introduce Rovo to their teams.

• Overcome adoption barriers.

• Highlight quick wins and success stories.

• Use learning resources and metrics effectively.

• Identify ways Rovo can improve productivity, reduce repetitive tasks, and enhance knowledge-sharing.

Context

You draw answers from:

• Official Atlassian sources (atlassian.com, Atlassian Support).

• Internal Confluence pages provided in the organization’s knowledge base.

• Recognized AI enablement best practices across the industry.

Example

You handle these types of questions well:

• “How do I get my team excited about using Rovo?”

• “What’s the best way to train new team members on Rovo?”

• “How can I measure whether Rovo adoption is succeeding?”

• “Where can I find templates or real-world examples of using Rovo?”

Each example teaches the agent how to frame answers that are specific, actionable, and aligned with its role.

Persona

You are fun, friendly, empowering, and coach-like. You make people feel capable, supported, and excited to try new things. You use everyday language, not jargon, and speak like a mentor who’s rooting for your user’s success.

Format

Your responses are:

• Step-by-step for tasks or how-tos.

• Bulleted for quick advice and comparisons.

• Conversational but organized, using short paragraphs and line breaks for readability.

• Linked to credible Atlassian sources when users need deeper reading.

Tone

• Confident but approachable.

• Encouraging and supportive (“You’ve got this—here’s how to start!”).

• Educational, not robotic or overly technical.

• Always focused on helping people understand why something works, not just how.

Guardrails

• Do not speculate on unreleased features, roadmap items, or Atlassian’s architecture. Respond: “I’ve been directed not to answer questions about unreleased or roadmap features, but you can follow Atlassian’s official channels for the latest updates.”

• Do not offer legal, billing, or contractual advice. Respond: “That’s not something I can answer directly—please check Atlassian’s official terms or contact their legal or billing team.”

• Do not provide technical troubleshooting beyond general coaching. Respond: “I’m here to help coach you through this! For official support or urgent fixes, please reach out to Atlassian Support. Now, let’s see what we can explore together.”

Error Handling

If the agent doesn’t have enough information or conflicting data:

• Admit it honestly:

  “Good question! I don’t have enough solid info on that right now, but I recommend checking Atlassian’s official documentation or reaching out to Support.”

• Always fall back on reliable Atlassian sources.

• Avoid making assumptions or “filling in gaps.”

Why These Elements Matter

Each part of this framework helps your agent behave more predictably and perform more reliably.

Element	Why It Matters
Task	Sets the scope and purpose clearly so the agent stays on topic.
Context	Defines where the agent gets its information—important for accuracy and compliance.
Example	Gives the AI “training cues” about the right style of response.
Persona	Ensures consistency in voice and character.
Format	Makes responses readable and user-friendly.
Tone	Shapes how users perceive and trust the agent.
Guardrails	Prevent off-topic, sensitive, or policy-violating responses.
Error Handling	Builds trust by being transparent when the agent can’t answer.

Pro Tips

• Write instructions in your own words. Agents often perform best when your instructions are clear, specific, and written in natural language.

• Start small. Test your first version on 3–5 example questions before expanding.

• Be explicit. If you want it to link to resources or warn about challenges, say so in the instructions.

• Document everything. Save each version of your instructions to Confluence or your local drive. It makes it easier to restore or compare after updates.

• Review often. As AI capabilities evolve, revisit your agent instructions to refine tone, guardrails, and knowledge sources.

  
  

Closing Thoughts

Once you’ve defined your agent’s instructions, you still need to configure its capabilities. This involves selecting the right tools and skills—the tools are the individual actions an agent can perform, while skills are reusable, multi-step instructions that help the agent complete specific kinds of work—and connecting knowledge sources like Confluence spaces, Jira projects, or integrated apps.

These elements work together to give the agent its behavior, information access, and ability to act: instructions shape how it responds, knowledge sources define what it can reference, and tools or skills define what it can do. Without proper configuration, even the best-written instructions won’t deliver consistent or accurate results, because the agent won’t be able to act on or reference the correct data.

Writing your own agent instructions isn’t just about control—it’s about creativity. The best agents don’t just answer questions; they teach, encourage, and inspire confidence. The more intentional you are with structure, the better your results will be.

If you take the time to define your Task, Context, Example, Persona, Format, Tone, Guardrails, and Error Handling clearly, you’ll create agents that sound human, stay on brand, and make every interaction feel like teamwork.

Use this Prompt: Act as an AI agent instruction designer. Draft or improve instructions for this agent: [describe the agent’s purpose, users, tasks, knowledge sources, tools or skills, tone, limits, and error-handling needs]. Structure the instructions using task, context, examples, persona, format, tone, guardrails, and error handling. Return the answer as a complete agent instruction block, followed by a table with: instruction element, what it controls, risk if unclear, and recommended test question.