rilldata · nishantmonu51 · Aug 24, 2026 · Aug 26, 2026
diff --git a/docs/docs/developers/agent-skills/_category_.yml b/docs/docs/developers/agent-skills/_category_.yml
@@ -0,0 +1,4 @@
+position: 40
+label: Agent Skills
+collapsible: false
+collapsed: false
diff --git a/docs/docs/developers/agent-skills/index.md b/docs/docs/developers/agent-skills/index.md
@@ -0,0 +1,62 @@
+---
+title: "Rill Agent Skills"
+description: Teach AI coding agents like Claude Code and Cursor how to build Rill projects
+sidebar_label: "Overview"
+sidebar_position: 0
+---
+
+Rill ships built-in agent skills that teach AI coding agents how to develop Rill projects. Because Rill projects are defined as YAML and SQL files, they are a natural fit for agentic development: the skills give your agent detailed knowledge of Rill's project structure, resource types, and development workflow, so it can build connectors, models, metrics views, and dashboards on your behalf.
+
+A single command generates everything your agent needs:
+
+```bash
+rill init --agent all
+```
+
+The skills work with Claude Code and Cursor out of the box, and ship in a tool-agnostic format for `AGENTS.md`-compatible agents such as OpenAI Codex, Gemini CLI, and GitHub Copilot. Agents that also support the [Agent Skills](https://agentskills.io) convention load the detailed skills automatically; for others, the skill files are plain Markdown that you can point the agent at directly. See the [Installation guide](/developers/agent-skills/install) for setup instructions for each tool.
+
+:::note Agent skills vs. the Rill MCP Server
+Agent skills and the [Rill MCP Server](/guide/ai/mcp) are complementary. The skills teach your agent *how* to build a Rill project — resource types, YAML schemas, and best practices. The MCP server gives it *live access* to your running project — resource status, table schemas, query results, and file operations. `rill init --agent` sets up both: it generates the skill files and an MCP configuration that connects your agent to Rill Developer's local MCP server.
+:::
+
+## What you can do
+
+With agent skills installed, your AI agent can:
+
+- Connect to data sources like S3, GCS, BigQuery, and Snowflake
+- Create and refactor SQL and YAML models, including incremental and partitioned models
+- Define metrics views with measures, dimensions, and access policies
+- Build explore and canvas dashboards
+- Configure project-wide settings in `rill.yaml` and custom themes
+- Inspect resource status, debug parse errors, and fix reconciliation failures
+- Run analytical queries against your metrics views and summarize the results
+
+## Supported tools
+
+| Tool | Format | Generated files |
+| --- | --- | --- |
+| [Claude Code](/developers/agent-skills/install#claude-code) | Claude skills | `.claude/CLAUDE.md`, `.claude/skills/`, `.mcp.json` |
+| [Cursor](/developers/agent-skills/install#cursor) | Cursor rules | `.cursor/rules/`, `.cursor/mcp.json` |
+| [Other agents](/developers/agent-skills/install#agentsmd-compatible-agents) (Codex, Gemini CLI, Copilot, ...) | `AGENTS.md` | `AGENTS.md`, `.agents/skills/`, `.mcp.json` |
+
+## Example prompts
+
+Once installed, the skills activate automatically based on your request. Ask naturally:
+
+```text
+"Connect to the parquet file at gs://rilldata-public/auction_data.parquet"
+"Create a model that cleans the auction data and buckets bids into price ranges"
+"Create a metrics view with measures for total bids, average bid price, and win rate"
+"Build an explore dashboard for the auction metrics view"
+"Add a canvas dashboard with KPI cards and a time series chart"
+"Why is my events model erroring?"
+"What were my top domains by win rate last week?"
+```
+
+## Related
+
+- [Agentic Quickstart](/developers/get-started/ai-quickstart) — step-by-step guide to building a project with an AI agent
+- [Installing agent skills](/developers/agent-skills/install)
+- [Agent skills reference](/developers/agent-skills/skills)
+- [AI Configuration](/developers/build/ai-configuration) — add `ai_instructions` to improve AI responses for your project
+- [Rill MCP Server](/guide/ai/mcp) — connect AI assistants to Rill Cloud projects for data analysis
diff --git a/docs/docs/developers/agent-skills/install.md b/docs/docs/developers/agent-skills/install.md
@@ -0,0 +1,123 @@
+---
+title: "Installing Agent Skills"
+description: Install Rill agent skills for Claude Code, Cursor, and AGENTS.md-compatible agents
+sidebar_label: "Installation"
+sidebar_position: 10
+---
+
+Rill's agent skills are bundled with the Rill CLI and generated directly into your project with `rill init --agent`. This page covers installation for each supported tool.
+
+## Requirements
+
+- [Rill CLI installed](/developers/get-started/install)
+- An AI coding agent: [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [Cursor](https://www.cursor.com/), or another agent that supports the `AGENTS.md` convention
+
+## Install with the CLI
+
+### New project
+
+Run `rill init` interactively and select an option at the "Agent instructions" prompt:
+
+```bash
+rill init
+? Project name my-rill-project
+? OLAP engine duckdb
+? Agent instructions all
+```
+
+Or pass the `--agent` flag directly:
+
+```bash
+rill init my-project --agent all
+```
+
+The `all` option generates the skills in every supported format, so the project works with any agent out of the box. To generate files for a single tool only, pass `claude`, `cursor`, or `agentsmd` instead.
+
+### Existing project
+
+To add agent skills to an existing Rill project, run `rill init` with only the `--agent` flag:
+
+```bash
+rill init ./my-existing-project --agent all
+```
+
+The command only writes agent instruction files and MCP configuration; the rest of your project is left untouched.
+
+:::warning Existing agent files are overwritten
+If the project already has agent instruction files at the generated paths — for example `.claude/CLAUDE.md`, `.cursor/rules/AGENTS.mdc`, or an `AGENTS.md` at the project root — the command replaces them without prompting. Back up or commit any customizations first, and keep your own instructions in separate files so they survive regeneration (see [Updating agent skills](/developers/agent-skills/update)).
+:::
+
+### Options
+
+The `--agent` flag accepts the following values:
+
+| Option | Description |
+| --- | --- |
+| `claude` | Claude Code skills in `.claude/` (default) |
+| `cursor` | Cursor rules in `.cursor/` |
+| `agentsmd` | Tool-agnostic `AGENTS.md` format |
+| `all` | All of the above |
+| `none` | No agent instructions |
+
+:::tip Commit the generated files
+The generated files are plain text and designed to be committed to version control. Check them in so everyone on your team — and every agent — works from the same instructions.
+:::
+
+## Claude Code
+
+The `all` and `claude` options generate:
+
+- **`.claude/CLAUDE.md`** — entry point that tells Claude Code to load the Rill development skills before making changes
+- **`.claude/skills/rill-*/SKILL.md`** — one skill per topic: the development workflow, data analysis, and each resource type (see the [skills reference](/developers/agent-skills/skills))
+- **`.mcp.json`** — connects Claude Code to Rill Developer's local MCP server
+
+Open Claude Code in the project directory. When prompted, trust the project's MCP configuration so Claude Code can connect to the Rill MCP server. The skills activate automatically based on your requests.
+
+## Cursor
+
+The `all` and `cursor` options generate:
+
+- **`.cursor/rules/AGENTS.mdc`** — an always-applied rule that points Cursor at the Rill development instructions
+- **`.cursor/rules/*.mdc`** — rules for the development workflow, data analysis, and each resource type, applied automatically based on their descriptions
+- **`.cursor/mcp.json`** — connects Cursor to Rill Developer's local MCP server
+
+Open the project in Cursor and enable the `rill-developer` MCP server when prompted.
+
+## AGENTS.md-compatible agents
+
+This format works with agents that follow the [AGENTS.md](https://agents.md) convention, including OpenAI Codex, Gemini CLI, and GitHub Copilot. The `all` and `agentsmd` options generate:
+
+- **`AGENTS.md`** — entry point at the project root
+- **`.agents/skills/rill-*/SKILL.md`** — one skill per topic, in the same format as the Claude Code skills
+- **`.mcp.json`** — MCP server configuration for agents that support it
+
+The entry point instructs the agent to load the `rill-development` skill by name. Agents that support the [Agent Skills](https://agentskills.io) convention resolve it from `.agents/skills/` automatically. If your agent only reads `AGENTS.md`, the skills are plain Markdown files — point the agent at `.agents/skills/rill-development/SKILL.md` directly.
+
+## Connect the MCP server
+
+The generated MCP configuration points at Rill Developer's local MCP server:
+
+```json
+{
+  "mcpServers": {
+    "rill-developer": {
+      "type": "http",
+      "url": "http://localhost:9009/mcp"
+    }
+  }
+}
+```
+
+The server becomes available when you start Rill Developer:
+
+```bash
+rill start my-project
+```
+
+Through the MCP server, your agent can check resource status, inspect table schemas, run SQL and metrics queries, and read and write project files with immediate feedback on parse and reconcile errors.
+
+## Next steps
+
+- [Agentic Quickstart](/developers/get-started/ai-quickstart) — build a project end-to-end with an AI agent
+- [Agent skills reference](/developers/agent-skills/skills) — what each skill covers
+- [Updating agent skills](/developers/agent-skills/update) — keep the skills up to date with new Rill releases
diff --git a/docs/docs/developers/agent-skills/skills.md b/docs/docs/developers/agent-skills/skills.md
@@ -0,0 +1,101 @@
+---
+title: "Agent Skills Reference"
+description: Reference for all Rill agent skills and the files generated by rill init --agent
+sidebar_label: "Skills Reference"
+sidebar_position: 30
+---
+
+Reference for the skills generated by `rill init --agent`. The same set of skills is generated for every tool — only the file format and location differ.
+
+## Entry point
+
+Each format includes an entry point that loads automatically when your agent starts working in the project:
+
+| Format | Entry point |
+| --- | --- |
+| Claude Code | `.claude/CLAUDE.md` |
+| Cursor | `.cursor/rules/AGENTS.mdc` (always applied) |
+| `AGENTS.md` | `AGENTS.md` at the project root |
+
+For Claude Code and `AGENTS.md`, the entry point instructs the agent to load the `rill-development` skill before making any changes, so the agent begins with an understanding of Rill's project structure and workflow. For Cursor, the development instructions live in the `development.mdc` rule instead, which Cursor applies on demand based on its description when you work on the project.
+
+## Skills
+
+The remaining skills activate on demand based on what you ask the agent to do:
+
+| Skill | Description |
+| --- | --- |
+| `rill-development` | Overview of how to develop a Rill project: project structure, resource types, the resource DAG, and the development workflow. Loaded before any project changes. |
+| `rill-analysis` | How to analyze data in a Rill project: discovering metrics views, running metrics queries, and presenting insights. |
+| `rill-connector` | Detailed instructions and examples for developing connector resources, covering OLAP engines and data sources. |
+| `rill-model` | Detailed instructions and examples for developing model resources, including SQL models, YAML models, incremental ingestion, and partitions. |
+| `rill-metrics-view` | Detailed instructions and examples for developing metrics views, including measures, dimensions, and time series configuration. |
+| `rill-explore` | Detailed instructions and examples for developing explore dashboard resources. |
+| `rill-canvas` | Detailed instructions and examples for developing canvas dashboard resources and their components. |
+| `rill-theme` | Detailed instructions and examples for developing theme resources. |
+| `rill-rillyaml` | Detailed instructions and examples for developing the `rill.yaml` project file. |
+
+Each resource skill embeds the complete YAML schema for its resource type, generated from the same source as the [project file reference](/reference/project-files). This lets your agent write valid configuration without guessing at property names.
+
+## File layout
+
+### Claude Code (`--agent claude`)
+
+```
+.claude/
+├── CLAUDE.md
+└── skills/
+    ├── rill-development/SKILL.md
+    ├── rill-analysis/SKILL.md
+    ├── rill-connector/SKILL.md
+    ├── rill-model/SKILL.md
+    ├── rill-metrics-view/SKILL.md
+    ├── rill-explore/SKILL.md
+    ├── rill-canvas/SKILL.md
+    ├── rill-theme/SKILL.md
+    └── rill-rillyaml/SKILL.md
+.mcp.json
+```
+
+### Cursor (`--agent cursor`)
+
+```
+.cursor/
+├── mcp.json
+└── rules/
+    ├── AGENTS.mdc
+    ├── development.mdc
+    ├── analysis.mdc
+    └── resources/
+        ├── connector.mdc
+        ├── model.mdc
+        ├── metrics_view.mdc
+        ├── explore.mdc
+        ├── canvas.mdc
+        ├── theme.mdc
+        └── rillyaml.mdc
+```
+
+`AGENTS.mdc` is marked `alwaysApply: true`; the other rules carry descriptions that let Cursor apply them automatically when relevant.
+
+### AGENTS.md (`--agent agentsmd`)
+
+```
+AGENTS.md
+.agents/
+└── skills/
+    ├── rill-development/SKILL.md
+    ├── rill-analysis/SKILL.md
+    └── ... (same skills as Claude Code)
+.mcp.json
+```
+
+## MCP server configuration
+
+Every format also writes an MCP configuration that registers Rill Developer's local MCP server as `rill-developer` at `http://localhost:9009/mcp`. If the file already contains other MCP servers, the Rill entry is added alongside them. See [Connect the MCP server](/developers/agent-skills/install#connect-the-mcp-server) for details.
+
+## Related
+
+- [Installing agent skills](/developers/agent-skills/install)
+- [Updating agent skills](/developers/agent-skills/update)
+- [Project file reference](/reference/project-files)
diff --git a/docs/docs/developers/agent-skills/update.md b/docs/docs/developers/agent-skills/update.md
@@ -0,0 +1,37 @@
+---
+title: "Updating Agent Skills"
+description: Keep Rill agent skills up to date with new Rill releases
+sidebar_label: "Updating"
+sidebar_position: 20
+---
+
+Agent skills are bundled with the Rill CLI, so each Rill release may include updated instructions that reflect new resource types, YAML properties, and best practices. The generated files in your project are a snapshot from the CLI version that created them — they do not update automatically.
+
+## Update the skills
+
+First, make sure you are on the latest version of Rill:
+
+```bash
+rill upgrade
+```
+
+Then re-run `rill init` in your project to regenerate the skill files:
+
+```bash
+rill init . --agent all
+```
+
+Use the same `--agent` option you installed with (`all`, `claude`, `cursor`, or `agentsmd`). The command overwrites the previously generated files with the latest versions and leaves the rest of your project untouched.
+
+:::warning Regenerating overwrites customizations
+Re-running `rill init --agent` replaces the generated files, including the entry points (`.claude/CLAUDE.md`, `.cursor/rules/AGENTS.mdc`, or `AGENTS.md`). Keep your own project-specific agent instructions in separate files — for example, a `CLAUDE.md` at the repository root for Claude Code, or additional rule files in `.cursor/rules/` — so they survive updates.
+:::
+
+## When to update
+
+- After upgrading Rill to a new version, especially if the release notes mention new resource types or YAML properties
+- If your agent generates YAML that Rill rejects — the skills embed the YAML schema for each resource type, so stale skills can produce stale configuration
+
+## Verify the update
+
+The generated files are plain text, so a `git diff` after regenerating shows exactly what changed. Review and commit the changes like any other update to your project.
diff --git a/docs/docs/developers/build/ide/ide.md b/docs/docs/developers/build/ide/ide.md
@@ -23,13 +23,12 @@ You can edit these files in any IDE, and Rill will automatically detect changes
 
 ## Using AI Agents to Build Rill Projects
 
-Rill ships built-in instructions that teach AI coding agents like **Claude Code** and **Cursor** how to build Rill projects. A single `rill init` command scaffolds everything your agent needs — resource schemas, best practices, and development conventions.
+Rill ships built-in [agent skills](/developers/agent-skills) that teach AI coding agents like **Claude Code** and **Cursor** how to build Rill projects. A single `rill init` command scaffolds everything your agent needs — resource schemas, best practices, and development conventions.
 
 ```bash
-# Add Claude Code instructions to your project
-rill init --template claude
-
-# Or add Cursor rules
-rill init --template cursor
+# Add agent skills for Claude Code, Cursor, and AGENTS.md-compatible tools
+rill init --agent all
 ```
 
+See the [Agent Skills documentation](/developers/agent-skills) for installation instructions for each tool, or the [Agentic Quickstart](/developers/get-started/ai-quickstart) for a full walkthrough.
+