Best practices for prompting Maia AI Agents🔗

This guide explains how to get the best results from your conversations with Maia AI Agents, your agentic data team. If you're new to Maia AI Agents, check out the Maia AI Agents overview to learn more about what they can do.

Prompting best practices🔗

The quality of Maia AI Agents' responses depends significantly on how prompts are structured. Following these best practices will help Maia AI Agents understand your intent and deliver more accurate results.

Be specific and provide context🔗

Name resources explicitly: Reference specific tables, columns, pipelines, and components by their exact names rather than using vague descriptions.
Include relevant details: Specify data types, expected formats, business rules, or constraints that affect the task.
State your goal: Explain what you're trying to achieve, not just what you want Maia AI Agents to do. This helps Maia AI Agents make better decisions when multiple approaches exist.
Use the @ symbol: Reference specific files in your project using @filename to direct Maia AI Agents' attention.
Use slash commands: Use slash commands like /explain, /fix, /optimize, and /document for common tasks.

The table below gives some examples of less effective prompts, and how to improve them to get the best response from Maia AI Agents.

Less effective	More effective
Join these tables	Join the `customers` and `orders` tables on `customer_id`, keeping only customers with at least one order
Filter the data	Filter `transactions` to include only rows where `status` is `completed` and `amount` is greater than 100
Create a pipeline	Create an orchestration pipeline that loads data from Salesforce contacts into the `staging_contacts` table daily
Add a calculation	Add a calculator component that creates a `profit_margin` column calculated as `(revenue - cost) / revenue`
Clean up the data	Remove rows where `email` is null or doesn't contain an @ symbol, and trim whitespace from the `name` column
Connect to the API	Create a custom connector to extract data from the HubSpot Contacts API using OAuth2 authentication and load it into `raw_hubspot_contacts`
Fix this pipeline	The `daily_sales` pipeline is failing at the join component—check why the join keys might not be matching
What does this do?	Explain what the `weekly_inventory_sync` pipeline does, including its data sources and output tables
Why isn't it working?	Why is the `customer_dedupe` transformation returning fewer rows than expected after the join?

Break complex tasks into steps🔗

For multi-step or complex tasks, prompt Maia AI Agents incrementally rather than requesting everything at once:

Start with the foundation (e.g. "Create a transformation pipeline that reads from the raw_orders table").
Add transformations one at a time (e.g. "Add a filter to keep only orders from the last 30 days").
Validate your pipeline at each step before continuing.

This approach allows you to verify Maia AI Agents' work progressively and course-correct early if needed.

Use plan mode for complex work🔗

When working on complex pipelines or when you want more control, enable Plan mode using the toggle at the bottom of the chat interface. This is particularly useful for large refactors, unfamiliar patterns, or when you want to understand Maia AI Agents' reasoning.

In plan mode, Maia AI Agents will:

Analyze your request and present a detailed plan before making changes
Allow you to review, modify, or approve the plan
Only execute changes after you've confirmed the approach

Maia AI Agents will automatically suggest switching to plan mode if they think your prompt is complex enough to require planning. When this happens, you will see a message in the Maia AI Agents chat interface—click Accept to allow Maia AI Agents to use plan mode.

Video example🔗

Expand this box to watch our video about using plan mode for complex tasks.

Video

Iterate and refine🔗

If Maia AI Agents' response doesn't match your expectations:

Provide feedback: Tell Maia AI Agents what's wrong or what you expected instead.
Add constraints: Specify requirements that weren't clear in your original prompt.
Rephrase the request: Try explaining the same goal from a different angle.

Video example🔗

Expand this box to watch our video about iterating and refining.

Video

Troubleshooting tips🔗

If Maia AI Agents don't follow your standards:

Check that your context file is in .matillion/maia/rules/ and within the character limit.
Check that rules are written as clear directives.
Explicitly reference standards in your prompt.

If skills aren't activating:

Review the skill description for clarity and relevant keywords.
Test with prompts that directly relate to the skill's purpose.

If Maia AI Agents' responses are inconsistent:

Start a new chat to clear potentially conflicting context.
Simplify your request and add complexity incrementally.
Use plan mode to review Maia AI Agents' approach before execution.

Video example🔗

Expand this box to watch our video about troubleshooting.

Video