npx claudepluginhub rilldata/agent-skillsThis skill uses the workspace's default tool permissions.
This document is intended for data engineering agents specialized in developing projects in the Rill business intelligence platform.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
This document is intended for data engineering agents specialized in developing projects in the Rill business intelligence platform.
Rill is a business intelligence platform built around the following principles:
A Rill project consists of resources that are defined using YAML and SQL files in the project's file directory. Rill supports different resource types, such as connectors, models, metrics views, explore dashboards, and more.
Here is an example listing of files for a small Rill project:
.env
connectors/duckdb.yaml
connectors/s3.yaml
models/events_raw.yaml
models/events.sql
metrics/events.yaml
dashboards/events.yaml
rill.yaml
Let's start with the project-wide files at the root of the directory:
rill.yaml is a required file that contains project-wide configuration. It can be compared to package.json in Node.js or dbt_project.yml in dbt..env is an optional file containing environment variables, usually secrets such as database credentials.The other YAML and SQL files define individual resources in the project. They follow a few rules:
type: property that identifies the resource type. The other properties in the file are specific to the selected resource type.type: model and a sql: property.connectors/duckdb.yaml defines a connector called duckdb.events (regardless of directory), but it is possible for both a model and a metrics view to be called events.Rill automatically watches project files and processes changes. There are two key phases:
Some resources are cheap to reconcile (validation, non-materialized models), others are expensive (materialized models, managed connectors). Be cautious with expensive operations; see resource-specific instructions for details.
Resources can also have scheduled reconciliation via cron expressions (e.g. daily model refresh).
Rill has a local CLI (rill) for development and a cloud service for production. After developing or changing a project locally, developers deploy to Rill Cloud either by pushing to GitHub (continuous deploys) or manually deploying with the CLI.
Rill places high emphasis on "operational intelligence", meaning low-latency, high-performance, drill-down dashboards with support for alerts and scheduled reports. Rill supports these features using OLAP databases and has drivers that are heavily optimized to leverage database-specific features to get high performance.
OLAP databases are configured as any other connector in Rill.
People can either connect an external OLAP database with existing tables, or can ask Rill to provision an empty OLAP database for them, which they can load data into using Rill's model resource type.
OLAP connectors are currently the only connectors that can directly power the metrics views resources that in turn power dashboards. So data must be in an OLAP database to power a dashboard.
Since OLAP databases have a special role in Rill, every project must have a default OLAP connector that you configure using the olap_connector: property in rill.yaml. This default OLAP connector is automatically used for a variety of things in Rill unless explicitly overridden (see details under the resource type descriptions). If no OLAP connector is configured, Rill by default initializes a managed duckdb OLAP database and uses it as the default OLAP connector.
The sections below contain descriptions of the different resource types that Rill supports and when to use them. The descriptions are high-level; you can find detailed descriptions and examples in the separate resource-specific instruction files.
Connectors are resources containing credentials and settings for connecting to an external system. They are usually lightweight as their reconcile logic usually only validates the connection. They are normally found at the root of the DAG, powering other downstream resource types.
There are a variety of built-in connector drivers, which each implements one or more capabilities:
duckdb, clickhouse)postgres, bigquery, snowflake)duckdb, bigquery, postgres)s3)slack)Here are some useful things to know when developing connectors:
.env and be referenced from the connector's YAML filemanaged: true will automatically be provisioned by Rill, so you don't need to handle the infrastructure or credentials directly. This is only supported for the duckdb and clickhouse drivers. The user will be subject to usage-based billing for the CPU, memory and disk usage of the provisioned database.mode: read to protect from unintended writes from Rill models.rill.yaml using the olap_connector: property.Models are resources that specify ETL or transformation logic that outputs a tabular dataset in one of the project's connectors. They are usually expensive resources that are found near the root of the DAG, referencing only connectors and other models.
Models usually (and by default) output data as a table with the same name as the model in the project's default OLAP connector.
They usually center around a SELECT SQL statement that Rill will run as a CREATE TABLE <name> AS <SELECT statement>.
This means models in Rill are similar to models in dbt, but they support some additional advanced features, namely:
When reasoning about a model, it can be helpful to think in terms of the following attributes:
Models are usually expensive resources that can take a long time to run, and should be created or edited with caution. The only exception is non-materialized models that have the same input and output connector, which get created as cheap SQL views. In development, you can avoid expensive operations by adding a "dev partition", which limits data processed to a subset. See the instructions for model development for details.
Metrics views are resources that define queryable business metrics on top of a table in an OLAP database. They implement what other business intelligence tools call a "semantic layer" or "metrics layer". They are lightweight resources found downstream of connectors and models in the DAG. They power many user-facing features, such as dashboards, alerts, and scheduled reports.
Metrics views consist of:
Explore resources define an "explore dashboard", an opinionated dashboard type that comes baked into Rill. These dashboards are specifically designed as an explorative, drill-down, slice-and-dice interface for a single metrics view. They are Rill's default dashboard type, and usually configured for every metrics view in a project. They are lightweight resources that are always found downstream of a metrics view in the DAG.
Explore resources can either be configured as stand-alone files or as part of a metrics view definition (see metrics view instructions for details). The only required configuration is a metrics view to render, but you can optionally also configure things like a theme, default dimension and measures to show, time range presets, and more.
Canvas resources configure a "canvas dashboard", which is a free-form dashboard type consisting of custom chart and table components laid out in a grid. They enable users to build overview/report style dashboards with limited drill-down options, similar to those found in traditional business intelligence tools.
Canvas dashboards support a long list of component types, including line charts, bar charts, pie charts, markdown text, tables, and more.
All components are defined in the canvas file, but each component is emitted as a separate resource of type component, which gets placed upstream of the canvas in the project DAG.
Each canvas component fetches data individually, almost always from a metrics view resource; so you often find metrics view resources upstream of components in the DAG.
Themes are resources that define a custom color palette for a Rill project.
They are referenced from rill.yaml or directly from an explore or canvas dashboards.
Custom APIs are resources that define a query that serves data from the Rill project on a custom endpoint. They are advanced resources that enable easy programmatic integration with a Rill project. They are lightweight resources that are usually found downstream of metrics views in the DAG (but sometimes directly downstream of a connector or model).
Custom APIs are mounted as GET and POST REST APIs on <project URL>/api/<resource name>.
The queries can use templating to inject request parameters or user attributes.
Rill supports a number of different "data resolver" types, which execute queries and return data. The most common ones are:
metrics_sql: queries a metrics view using a generic SQL syntax (recommended)metrics: queries a metrics view using a structured query objectsql: queries an OLAP connector using a raw SQL query in its native SQL dialectAlerts are resources that enable sending alerts when certain criteria matches data in the Rill project. They consists of a refresh schedule, a query to execute, and notification settings. Since they repeatedly run a query, they are slightly expensive resources. They are usually found downstream of a metrics view in the DAG. Most projects don't define alerts directly as files; instead, users can define alerts using a UI in Rill Cloud.
Reports are resources that enable sending scheduled reports of data in the project. They consists of a delivery schedule, a query to execute, and delivery settings. Since they repeatedly run a query, they are slightly expensive resources. They are usually found downstream of a metrics view in the DAG. Most projects don't define reports directly as files; instead, users can define reports using a UI in Rill Cloud.
rill.yamlrill.yaml is a required file for project-wide config found at the root directory of a Rill project.
It is mainly used for:
.env.env is an optional file containing environment variables, which Rill loads when running the project.
Other resources can reference these environment variables using a templating syntax.
By convention, environment variables in Rill use snake-case, lowercase names (this differs from shell environment variables).
This section describes the recommended workflow for developing resources in a Rill project.
Before making changes, determine what kind of task you are performing:
Before proceeding, verify what the project supports:
.env, then ask the user to populate those values before continuing.Your workflow will depend on the kind of task you are undertaking. Here follows an idealized workflow for a full data source to dashboard journey:
The following tools are typically available for project development:
project_status for checking resource names and their current status (idle, running, error); supports wait_until_idle to block until reconciliation completes (use this if you just made a change and want to wait until it succeeds/errors); can also return recent logs, but they should be used sparingly and only for debugging a specific issue reported in the resource-level status overviewquery_sql for running SQL against a connector; use SELECT statements with LIMIT clauses and low timeouts, and be mindful of performance or making too many queriesquery_metrics_view for querying a metrics view; useful for answering data questions and validating dashboard behaviorlist_tables and show_table for accessing the information schema of a database connectorlist_buckets and list_bucket_files for exploring files in object stores like S3 or GCS; to preview file contents, load one file into a table using a model and query it with query_sqlYou may be running in an external editor that does not have Rill's development MCP server on localhost:9009 connected. If that is the case, you will need to approach your work differently because you can't run tool calls like list_tables, query_sql or project_status. Instead:
rill validate CLI command to validate the project and get the status of different resources.rill validate or user feedback to inform you of issues.Before creating or editing a resource, you MUST try to load a skill for its resource type. The skill is important because it documents the available properties and best practices. Do NOT guess at properties or rely on memory.
For example, if you are going to modify a metrics view and have access to the rill-metrics-view skill, you must load it first.
If you don't have access to a matching skill, try searching the reference documentation on https://docs.rilldata.com.
Avoid these mistakes when developing a project:
.yaml files, not .sql files (which are harder to extend later).read_parquet(...) or s3(...). Non-materialized models become views, which re-execute on every query..env (returned in env from project_status). If you need the user to add another environment variable, navigate to the .env file and stop with a message asking the user to manually add the required environment variable(s).timeseries: property.project_status: If you retrieve logs from the project_status tool, be aware that issues highlighted in the logs may have already been fixed. Only use the logs to debug errors indicated by the resource-level status.description property to a resource type that does not support it. Only use properties that are explicitly described in the documentation or resource schema.