Context files

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.

Context files are a powerful way to embed reusable knowledge and best practices directly into every prompt. These Markdown files are stored in your project and can include project context, business rules that affect pipeline design, data warehousing standards, and naming conventions. automatically read all context files stored in your project and use them to enhance their responses so you don’t have to repeat your requirements every time. Each time you interact with , the content of all context files is included in the background, helping understand your standards and preferences. Context files and additional rules, such as naming conventions, are an extremely useful tool that will help you get the most out of , your agentic data team. We strongly recommend creating a context file that contains information about your data, project, and organization as applicable. Context files can help you to:

• Contextualize your project: Give context about your work so they are better able to understand your needs.
• Enforce naming conventions: Define how pipelines and resources should be named, in order to ensure consistency.
• Build awareness: Provide with business-specific definitions, glossary terms, or standards so they can understand your data.
• Simplify reuse: Store connection information, such as usernames, for systems that you will frequently use to build data pipelines.

​

When to use skills and context files

Skills and context files should be used in different ways to help understand your data and provide better responses to your prompts. The table below clarifies some of the differences between skills and context files.

​

Context file best practices

• Keep content focused and actionable
  • Prioritize rules over explanations: Focus on what should do, not background information.
  • Use imperative language: Write instructions as directives (e.g., “Always prefix staging tables with stg_”) rather than descriptions.
  • Be concise: read all context files with every interaction. Verbose files slow down processing and may dilute important rules.
• Structure for clarity
  • Use clear headers: Organize by topic (naming conventions, data standards, connection info) so can quickly locate relevant rules.
  • Use bullet points and tables: These formats are easier for to parse than dense paragraphs.
  • Provide examples: Include concrete examples alongside rules to reduce ambiguity.
• Maintain and update regularly
  • Review periodically: Context files should evolve with your project. Outdated rules can lead to incorrect outputs.
  • Remove obsolete content: Delete rules that no longer apply rather than letting them accumulate.
  • Version with your project: Commit context file changes alongside related pipeline changes.

---

​

Formatting and storing context files

Context files must be .md (Markdown) files and must be stored in a folder with the following path: .matillion/maia/rules/. This folder is created automatically if you add a context file in the interface. If you create a context file from scratch, you need to create this folder structure first. The rules folder can be accessed in the Files panel in . It is important to note:

• enforce a strict 12,000-character limit across all Markdown context files stored in the .matillion/maia/rules/ directory. Additional context files stored in different folders are ignored unless you tell to reference them as described in Adding additional context files. These files do not count toward the character limit.
• It’s important to keep your context files updated. won’t automatically prompt you to make updates unless you ask them to, so make sure you regularly review and update them as your project evolves.

​

Add or edit context files in the Maia AI Agents interface

You can work with context files directly in the chat interface by clicking the corresponding option in the top right of the chat interface:

• Add context: This button appears at the top of the chat panel when no context file exists. Clicking this option automatically creates the .matillion/maia/rules/ folder and a Markdown file called context.md.
• Edit context: After a context file has been created, this button allows you to open and edit the file without switching views. If you have more than one context file in the .matillion/maia/rules/ folder, this button will open the context file that was created first.

​

Add or edit context files in the Files panel

To add a new context file if no context file exists, follow these steps. If you have already created at least one context file, skip steps 1 and 2.

1. Create a top-level folder called .matillion.
2. In the .matillion folder, create a folder called maia.
3. In the maia folder, create a folder called rules.
4. Click the three dots … next to the rules folder, then Add, then Markdown file.
5. Write your context content in plain Markdown. support headings, lists, and tables.

​

Adding additional context files

can also access additional context, such as complex logic, detailed documentation, or full business process guides. Unlike your static context files, which always read, will dynamically choose when to refer to your additional files. This allows to use situational information and use-case-specific context to respond to your prompts. For example, if you tell “When building a transformation pipeline, always refer to the comprehensive standards in additional-context/transformation_standards.md”, will always refer to this additional context file when building transformation pipelines, but not orchestration pipelines. To allow to access additional context files:

1. Store this content in a directory other than the .matillion/... directory. Any other directory in your project is suitable. For example, you could create a new folder called additional-context at the root level and add a new Markdown file called naming-conventions.
2. Click Edit context in the chat interface to edit your context file.
3. In your context file, reference the location of your additional context. For example, you could tell “Follow all the rules listed in the naming-conventions file stored in the additional-context folder.”

This ensures that the context file containing essential information remains within the character limit, while still allowing users and teammates to access more detailed information.

---

​

Sample context files

Sample context files are available to help teams standardize project documentation, enforce naming conventions, and define best practices. These examples are intended to accelerate setup and ensure consistency across pipeline development. Example context files are available to download below, or from the Matillion Exchange. These files can be used to:

• Apply consistent naming and modeling standards across teams.
• Embed reusable business logic and glossary terms into ’ prompts.
• Simplify setup by reusing validated patterns and integration rules.

To use a context file from the Matillion Exchange:

1. Download a context file using the links below or the Matillion Exchange.
2. Replace any placeholder logic, metadata, and KPIs with your own standards.
3. Save the file in the .matillion/maia/rules/ directory of your project.
4. Commit your changes.
5. Once you have committed your changes, will use the context file during future interactions.

---

​

Merging context files to your main branch

To make sure your context file is available in all future branches, we recommend using this Git workflow:

1. Start from your default branch (for example, main).
2. Create a feature branch from main (e.g., adding-context-file).
3. Add the context file, then commit and push your changes.
4. Switch back to main, merge in the feature branch, and push the updated main branch.
5. All future branches created from main will automatically include the context file.