feat(ai): support project-defined skills (skills/*.md) for AI agents

admin/server/mcp.go

@@ -52,6 +52,8 @@ var mcpForwardedTools = []string{
 	ai.GetMetricsViewName,
 	ai.QueryMetricsViewSummaryName,
 	ai.QueryMetricsViewName,
+	ai.ListSkillsName,
+	ai.LoadSkillName,
 }
 
 // mcpSessionNamespace is a UUIDv5 namespace for the per-project session IDs derived in callRuntimeTool.

docs/docs/developers/build/ai-configuration.md

@@ -16,6 +16,8 @@ There are two places to add `ai_instructions`:
 1.  **`rill.yaml`**: Project-wide instructions that apply to all queries across your entire project.
 2.  **`<metrics_view>.yaml`**: Metrics view-specific instructions for individual dashboards.
 
+For longer, structured guidance — such as step-by-step analysis playbooks — use [skills](#skills) instead, which the AI loads on demand.
+
 ## Automatic Context Inclusion
 
 In addition to `ai_instructions`, Rill automatically includes the following in the AI context:
@@ -95,6 +97,52 @@ ai_instructions: |
   - Weekend traffic patterns are anomalous due to our B2B focus.
 ```
 
+## Skills
+
+Skills teach Rill's AI project-specific practices, such as analysis playbooks (e.g. how to do root-cause analysis for a revenue drop) or business glossaries. Where `ai_instructions` is best for short guidance that always applies, skills hold longer, structured instructions that the AI loads only when they are relevant to the question at hand. Skills apply both in [AI Chat](/guide/ai/ai-chat) and to external AI clients connected via the [MCP Server](/guide/ai/mcp).
+
+Skills follow the [Agent Skills](https://agentskills.io) format: a skill is a directory containing a `SKILL.md` file with YAML front matter followed by markdown instructions. Rill loads skills from `skills/<name>/SKILL.md`, and also from `.agents/skills/<name>/SKILL.md` for compatibility with skills authored for other agent clients (note that the Rill Developer file explorer hides dot-directories, so prefer `skills/` for skills you edit in Rill). For example, `skills/revenue-rca/SKILL.md`:
+
+```markdown
+---
+name: revenue-rca
+description: Playbook for diagnosing revenue drops. Use when asked why revenue or bookings declined.
+---
+
+# Revenue root-cause analysis
+
+When asked why revenue declined:
+1. Establish the comparison window and compute the total change.
+2. Break the change down by `channel`, then `region`, then `plan_type`.
+3. Account for known seasonality: B2B traffic drops on weekends.
+4. State your confidence and call out data quirks that may affect the result.
+```
+
+The `description` is required: the AI sees the list of skills with their descriptions, and uses the description to decide when to load a skill. Phrase it as "what it does + when to use it". Always include the `name`, which the Agent Skills format requires and other clients reject when missing. It must match the skill's directory name (lowercase letters, numbers and hyphens). Rill is lenient and derives it from the directory if omitted.
+
+In addition to the standard Agent Skills fields, Rill supports these extension properties:
+
+```markdown
+---
+description: Business glossary for our e-commerce metrics.
+metrics_views: [orders]      # Optional: the metrics views this skill is relevant to
+agents: [analyst]            # Optional: which agents the skill applies to; defaults to [developer]
+always_apply: true           # Optional: load the skill up front in every conversation instead of on demand
+---
+```
+
+- **`metrics_views`** tells the AI which metrics views a skill is relevant to, so for example a marketing playbook is not used during a finance analysis. It is a relevance hint, not access control. Referencing a metrics view that doesn't exist shows an error on the skill file, and the skill is not offered to the AI until the error is fixed.
+- **`agents`** selects the agents the skill applies to: `analyst` for answering questions about your data, `developer` for editing the project's files. It defaults to `[developer]`, so skills written for coding agents (such as the Rill development skills that `rill init` writes to `.agents/skills/`) are not offered to the analyst. Set `agents: [analyst]` on analysis skills.
+- **`always_apply`** loads the skill up front in every conversation instead of on demand, like `ai_instructions`. Use it for short, broadly applicable guidance such as glossaries. For external MCP clients, always-apply skills are also appended to the `ai_instructions` returned by `list_metrics_views`, up to 32 KiB in total; a skill that doesn't fit must be loaded with `load_skill` and a warning is logged.
+
+Other agent clients ignore Rill's extension fields, so a Rill skill remains a valid Agent Skill and vice versa. A skill directory may also hold supporting files (such as `references/` or `scripts/`) as the format allows; Rill ignores everything in a skill directory except `SKILL.md`, so a SQL or YAML example inside a skill is not parsed as a project resource.
+
+Skills are parsed into resources like the rest of your project: invalid skill files (e.g. a missing `description`) show an error on the file in Rill Developer. When the AI uses a skill, the chat response's activity trace shows a "Loaded skill" step, so you can verify a skill was applied and iterate on it: edit the file, ask a test question, and check the trace.
+
+:::warning Skills are visible to all AI users
+Skill contents are provided to every user who can use AI features in the project, including viewers and, on a public project, anonymous visitors. Never put secrets or sensitive data in a skill. Access to the underlying data is still governed by your metrics view security policies.
+:::
+
 ## Visualization Tips 
 
 When using the [Rill MCP Server](/guide/ai/mcp) with external AI clients like Claude, you can provide specific instructions on how to visualize data. Since the MCP server returns structured data, the AI client is responsible for rendering it.

docs/docs/guide/ai/mcp.md

@@ -243,6 +243,8 @@ There are two places to add `ai_instructions`:
 1. `rill.yaml` for project-wide context, such as instructions on how to use Rill MCP Server
 2. Every metrics view YAML (`<metrics_view>.yaml`), with examples of Explore URLs for that metrics view
 
+For longer, structured guidance — such as analysis playbooks and business glossaries — you can also define [skills](/developers/build/ai-configuration#skills) in your project. External MCP clients discover them with the `list_skills` tool and load them on demand with `load_skill`.
+
 For detailed examples and best practices on writing effective AI instructions, see the [AI Configuration guide](/developers/build/ai-configuration).
 
 You can look at one of our [example projects](https://github.com/rilldata/rill-examples/tree/main/rill-openrtb-prog-ads) to see how these are used. Experiment with the instructions and see what works best for your requirements.
@@ -258,6 +260,8 @@ You can look at one of our [example projects](https://github.com/rilldata/rill-e
 - __*Get metrics view spec*__ – Use `get_metrics_view` to fetch a metrics view's specification. This is important to understand all the dimensions and measures in a metrics view.
 - __*Query the time range*__ – Use `query_metrics_view_summary` to obtain the available time range for a metrics view. This is important to understand what time range the data spans.
 - __*Query the metrics*__ – Use `query_metrics_view` to run queries to get aggregated results.
+- __*List skills*__ – Use `list_skills` to discover the [skills](/developers/build/ai-configuration#skills) defined in the project. The skill tools are only exposed when the project defines skills.
+- __*Load a skill*__ – Use `load_skill` to fetch a skill's full instructions before doing work its description covers.
 
 
 ### Usage Examples