Skip to main content

Building Rill Projects with AI

Rill projects are defined as YAML and SQL files, which makes them a natural fit for AI coding agents. This guide walks through using an AI agent like Claude Code or Cursor to build a Rill project from scratch.

Prerequisites​

Step 1: Initialize a project with agent instructions​

Run rill init to create a new project. The interactive setup will prompt you for a project name, OLAP engine, and agent instructions:

rill init
? Project name my-rill-project
? OLAP engine clickhouse
? Agent instructions all

This creates a project directory with:

  • rill.yaml — project configuration
  • .claude/CLAUDE.md and .claude/skills/ — entry point and skills for Claude Code, with detailed instructions for each resource type (models, metrics views, dashboards, etc.)
  • .cursor/ — the same instructions as Cursor rules
  • AGENTS.md and .agents/skills/ — the same instructions in the tool-agnostic AGENTS.md format
  • .mcp.json — connects your agent to Rill's local MCP server

See the Agent Skills documentation for details on what each skill covers and the files generated for each tool.

Only using one AI agent?

Select a specific option in the "Agent instructions" prompt, or use the --agent flag to generate files for just that tool:

# Claude Code skills
rill init my-project --agent claude

# Cursor rules
rill init my-project --agent cursor

# Tool-agnostic AGENTS.md format
rill init my-project --agent agentsmd

Adding agent instructions to an existing project​

If you already have a Rill project, run rill init with only the --agent flag to generate the agent instruction files:

rill init ./my-existing-project --agent all

The command only writes agent instruction files and MCP configuration — but note that it overwrites existing agent files at the generated paths.

Step 2: Start Rill in preview mode​

Launch Rill Developer in preview mode to get a clean, dashboard-only view while your AI agent handles the code:

rill start my-project --preview

This also starts a local MCP server at http://localhost:9009/mcp. If you generated agent instructions in Step 1, your AI agent will connect to this server automatically via the .mcp.json config — no additional setup required.

The MCP server gives your AI agent access to:

  • Project status — see which resources are healthy, errored, or pending
  • Table schemas — inspect columns, types, and sample data
  • SQL queries — run analytical queries against your OLAP engine
  • File operations — read and write project files

Step 3: Build with your AI agent​

With Rill running, open your AI agent in the project directory and start building. Here are some examples of what you can ask:

Connect a data source​

"Connect to the parquet file at gs://rilldata-public/auction_data.parquet"

The agent will create a source YAML file and Rill will automatically ingest the data.

Create models​

"Create a model that cleans the auction data — filter out null bids and add a bid_bucket column that groups bids into $0-1, $1-5, $5-10, and $10+ ranges"

Define metrics​

"Create a metrics view on the auction model with measures for total bids, average bid price, and win rate, broken down by dimensions like domain, device type, and bid bucket"

Build dashboards​

"Create an explore dashboard for the auction metrics view"

"Create a canvas dashboard with KPI cards for total bids and win rate, a time series chart, and a breakdown table by domain"

Iterate​

The agent has full context on Rill's resource types and YAML schemas. It can fix errors, refactor models, add new measures, and restructure your project — just describe what you want.

Check project status

If something isn't working, ask your agent to check the project status. The MCP connection lets it see parse errors, reconciliation failures, and resource health directly.

Next steps​

  • Agent Skills — learn more about the skills, supported tools, and how to keep them updated
  • Deploy to Rill Cloud — share your dashboards with your team
  • AI Chat — ask questions about your data in natural language from Rill Cloud
  • AI Configuration — add ai_instructions to improve AI responses for your project
  • Rill MCP Server — connect Claude Desktop, ChatGPT, or other AI clients to Rill Cloud projects