Context files

Context files are a powerful way to embed reusable knowledge and best practices directly into every Maia Team 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. Maia Team automatically reads all context files stored in your project and uses them to enhance its responses so you don’t have to repeat your requirements every time. Each time you interact with Maia Team, the content of all context files is included in the background, helping Maia Team understand your standards and preferences. Context files and the rules they contain, such as naming conventions, help you get the most out of Maia Team, your agentic data team. We strongly recommend creating a context file that contains information about your data, project, and organization. Context files can help you to:

• Contextualize your project: Give Maia Team context about your work so it is 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 Maia Team with business-specific definitions, glossary terms, or standards so it 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 Maia Team 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 Maia Team 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: Maia Team reads 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 Maia Team can quickly locate relevant rules.
  • Use bullet points and tables: These formats are easier for Maia Team 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 Maia Team 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 Designer. It is important to note:

• Maia Team enforces a strict 12,000-character limit across all Markdown context files stored in the .matillion/maia/rules/ directory. Maia Team can also read reference files stored in different folders, as described in Adding reference files, but these files don’t count toward the character limit.
• It’s important to keep your context files updated. Maia Team won’t automatically prompt you to make updates unless you ask it to, so make sure you regularly review and update them as your project evolves.

Add or edit context files in the Maia Team interface

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

• 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. Maia Team supports headings, lists, and tables.

Tracking the character limit

When editing a context file located in the .matillion/maia/rules/ folder, you can see its character count and status in the top right corner. The character count represents the number of characters in the open context file, not the total number of characters in all your context files. If you have more than one context file in the .matillion/maia/rules/ folder, Maia Team reads them in the order they appear in the folder (alphabetical order by file name). If the total character count in all your context files exceeds the 12,000-character limit, Maia Team reads your context files in this order until it reaches 12,000 characters, at which point it can’t read any more context files. The file’s status indicates how much of the context file Maia Team can read:

• Loaded: Maia Team can read all the information in the open context file.
• Partially loaded: Maia Team can only read some of the information in the open context file, because it exceeds the character limit.
• Not loaded: Maia Team can’t read any information in the open context file, because your other context files have already exceeded the character limit.

If any of your files are Partially loaded or Not loaded, click Fix with Maia to prompt Maia Team to read your context files and suggest a plan to edit them so that their total character count is within the 12,000-character limit. Maia Team won’t make any changes to your context files unless you approve its suggestions. Click the file status to open a dialog that lists all the context files in the .matillion/maia/rules/ folder, their status, and how many characters of each file have been loaded. For example, let’s say you have three context files that collectively exceed the 12,000-character limit. Here’s an example of what you would see in the dialog, and what it means:

• context.md, the file that Maia Team reads first, contains fewer than 12,000 characters, so it is loaded and Maia Team can read all its information.
• naming_conventions.md, the second file, contains fewer than 12,000 characters but causes the total character count to exceed the 12,000-character limit, so it is partially loaded. Maia Team can read and use the first 5,496 characters in this file, but nothing else.
• terminology.md, the third file, isn’t loaded because the previous two files already exceed the character limit. Maia Team can’t use any of its content when working on your prompts.

Adding reference files

Maia Team can also access reference files containing additional information for it to use when working on your prompts. For example, reference files could contain complex logic, detailed documentation, or full business process guides. Unlike your context files, which Maia Team always reads, Maia Team chooses when to refer to your reference files, based on your prompt. This allows Maia Team to use situational information and use-case-specific context to respond to your prompts. You can use your context files to tell Maia Team what information your reference files contain, and when to use them, as explained in the example below. To add reference files to your project and tell Maia Team when to use them:

1. In a folder outside the .matillion/... directory, create or import a .md file containing your reference information.
2. Click Edit context in the Maia Team chat panel to edit your context file.
3. In your context file, tell Maia Team when to use your reference files, and where they’re stored.

For example, let’s say you have developed a set of standards for orchestration pipelines, and one for transformation pipelines. You want Maia Team to use this information when building pipelines in your project. This is situational information, because Maia Team only needs to read these standards when your prompt involves working on a pipeline—this means it’s better to provide this information in reference files, not in your context files. In this case, you should:

1. Create a new root folder in your project, e.g. reference.
2. Add the Markdown files containing the standards to this folder, e.g. orchestration_standards.md and transformation_standards.md.
3. Add the following instruction to your context file: “When building a pipeline, refer to the corresponding set of standards in the reference folder. Use the standards in orchestration_standards.md when building orchestration pipelines, and use the standards in transformation_standards.md when building transformation pipelines.”

This approach means that your context file is concise and only contains general rules that you always want Maia Team to consider. Every time you chat with Maia Team, it reads your context file—as per the new instruction, if your prompt involves building an orchestration or transformation pipeline, it will use the corresponding reference file to ensure its output matches your standards.

---

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. These files can be used to:

• Apply consistent naming and modeling standards across teams.
• Embed reusable business logic and glossary terms into Maia Team‘s 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. Each file is a Markdown file.
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, Maia Team will use the context file during future interactions.