> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompting best practices
export const maia_agents = "Maia AI Agents";
This guide explains how to get the best results from your conversations with {maia_agents}, your agentic data team. If you're new to {maia_agents}, check out the [Maia AI Agents overview](/docs/guides/maia-ai-agents-overview) to learn more about what they can do.
The quality of {maia_agents}' responses depends significantly on how you write and structure your prompts. Following these best practices will help {maia_agents} understand your intent and deliver more accurate results.
When chatting with {maia_agents}, write your prompts in natural language. The {maia_agents} chat panel supports Markdown formatting, which allows you to format your messages so they are easier for you to read. If you want to write something inside underscores, for example to tell {maia_agents} to name a column `_customers_`, enclose it in backticks or quote marks so that the underscores are visible.
***
## 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_agents} to do. This helps {maia_agents} make better decisions when multiple approaches exist.
* **Use the @ symbol:** Reference specific files in your project using `@filename` to direct {maia_agents}' attention.
* **Use slash commands:** Use [slash commands](/docs/guides/maia-sessions-and-tools#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_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? |
***
## Use plan mode for complex tasks
When working on complex tasks or when you want more control, enable [**Plan mode**](/docs/guides/maia-sessions-and-tools#plan-mode) using the toggle at the bottom of the chat panel. {maia_agents} will automatically suggest switching to plan mode if they think your prompt is complex enough to require planning. When this happens, a message will appear in the {maia_agents} chat panel—click **Accept** to allow {maia_agents} to use plan mode.
In plan mode, {maia_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
When manually prompting {maia_agents} to work on complex tasks, give step-by-step instructions rather than requesting everything at once. For example:
1. Start with the first step in your process, e.g. "Create a transformation pipeline that reads from the `raw_orders` table".
2. Request additional transformations one at a time, e.g. "Add a filter to keep only orders from the last 30 days" and then "Sort the orders from the last 30 days by date".
We recommend validating your pipeline at each step. This approach allows you to check {maia_agents}' work as you go, and make corrections early if necessary.
***
## Iterate and refine
If {maia_agents}' response doesn't match your expectations:
* Provide feedback: Tell {maia_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.
Expand this box to watch our video about iterating and refining your prompts.
***
## Troubleshooting chats with Maia AI Agents
If {maia_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_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_agents}' approach before execution.
Expand this box to watch our video about improving your prompts when chatting with {maia_agents}.