How to use context file in Maia

About this guide
This guide explains how to create, manage, and use context files in Maia to apply consistent project standards across all pipeline prompts.

What are context files?

Context files are plain Markdown documents that embed reusable knowledge such as naming conventions, schema rules, and project goals directly into every interaction with Maia. When you ask Maia to build or modify a pipeline, these files are automatically included in the background to help Maia follow your project’s standards.

Why use context files?

Using context files helps you:

  • Avoid repeating the same instructions in every prompt
  • Standardize how pipelines are created across your team
  • Ensure naming, structure, and logic follow your organization’s best practices
  • Share project-specific knowledge in a scalable way

Where to store context files

Context files must be placed in the following location within your project:

.matillion/maia/rules/

You can create:

  • A single file, like context.md
  • Or multiple files based on topic, such as:
    • naming.md
    • standards.md
    • warehouse_design.md

Maia automatically reads all .md files in this folder and applies them to every prompt.

How to add or edit context files

You can manage context files in two ways:

1. From the Files panel in the designer

  • Navigate to .matillion/maia/rules/
  • Right-click to add a new Markdown file
  • Use standard Markdown formatting (headings, bullet lists, code blocks)

2. From the Maia chat panel

  • Add Context: Appears when no context file exists yet
  • Edit Context: Appears once context is active, so you can update it without switching views

What to Include in a context file

Typical context file elements:

  • A brief project overview
  • Naming conventions (e.g., for tables, pipelines, or views)
  • Schema design rules (e.g., star schema structure)
  • Data source metadata
  • Business logic constraints

You can use standard Markdown features:

  • Headings (##)
  • Lists (- item)
  • Bold/italic text
  • Code blocks for SQL, YAML, or example config

Example context files

Start with one of these sample files, which you can customize:

These examples show different structures and standards you can reuse across projects.

Best practices

  • Keep each file short and focused
  • Use clear, natural language — Maia doesn’t require technical syntax
  • Update files as your project evolves
  • Use multiple context files to organize guidance by topic

Summary

Context files let you teach Maia your team’s standards once and reuse them automatically in every pipeline prompt. With just a few Markdown files, you can boost accuracy, consistency, and team alignment.