Skip to main content

Contents

Instructions turn the agent into a domain expert for your data. They capture business definitions, calculation formulas, SQL patterns, and coding standards that aren’t in your schema.
  • Semantic definitions - what terms mean in your org
  • Calculation logic - formulas, filters, table preferences
  • SQL patterns - joins, type casting, naming conventions
  • Agent behavior - what to check first, when to ask for clarification
  • Visualization - chart types, dashboard layouts
This knowledge typically lives in people’s heads or scattered documentation. Instructions make it available to everyone through the agent. Instructions Create instructions manually, let the AI suggest them during conversations, or load from Git (dbt, markdown, LookML). All changes are versioned with rollback. Users and AI can suggest; admins approve before they take effect.
Use System category instructions to control agent workflow, e.g., “Search dbt metadata before selecting tables” or “Ask for clarification on financial queries.”

What is an Instruction

An instruction has text (the actual content), and configuration that controls when and how it’s applied: Add Instruction Optional: Labels for organization.

Examples

Category: General · Load Mode: Always
Category: Code Gen · Load Mode: Always
Category: Code Gen · Load Mode: Intelligent
Category: General · Load Mode: Intelligent
Category: Code Gen · Load Mode: Always
Category: System · Load Mode: Always
Category: Visualization · Load Mode: Intelligent
Category: Dashboard · Load Mode: Always
Sync documentation with YAML frontmatter to control behavior:
Source: Git · Load Mode: Always (via frontmatter)
Large reference docs work best with Intelligent mode:
Source: Git · Load Mode: Intelligent (via frontmatter)

Analyzing Instructions

Click Analyze on any instruction to identify overlaps, conflicts, and estimate impact on past prompts. Analyze Instruction The analysis shows:
  • Impact - percentage of past prompts affected by this instruction
  • Sample impacted prompts - examples of queries that would use this instruction
  • Related - other instructions that overlap or conflict with this one
Use this to refine instructions and avoid redundancy.

Approval Workflow

Instructions require admin approval before affecting AI behavior. Flow: User/AI suggests → Admin reviews → Approves or Rejects → Approved instructions go live. Admins: Go to Suggested tab → Review instruction → Change status → Update Instruction.

AI-Generated Instructions

During conversations, Bag of words detects clarifications you provide and offers to save them as instructions. Example: You clarify “active user means at least one session in 30 days” → System offers to save this for future use.
Auto-suggesting can be toggled in AI settings.

Git Integration

Load instructions from existing documentation in Git repositories. Connect repos in Data Sources.

Supported Sources

Settings

Frontmatter

Control behavior in Markdown files:
  • alwaysApply: true → Load mode = Always
  • alwaysApply: false → Load mode = Intelligent
  • references → Auto-link to tables

Unlinking from Git

Edit a Git-synced instruction → Save → Confirm “Unlink from Git”. The instruction becomes user-owned.

Versioning

Every change creates a new build - an immutable snapshot of all instructions.
  • One active build at any time (marked “main”)
  • Full audit trail of who changed what and when
  • Agent runs are linked to specific builds for traceability

Build Sources

Version Explorer

Access: Instructions page → Version selector → Version Explorer Version Explorer Diff indicators: +N (added) · ~N (modified) · −N (removed) Rollback: Select build → Click “Rollback to this version” → New build becomes active.