diff --git a/docs/docs/developers/build/ai-configuration.md b/docs/docs/developers/build/ai-configuration.md index af0e94923081..e7978fe0f475 100644 --- a/docs/docs/developers/build/ai-configuration.md +++ b/docs/docs/developers/build/ai-configuration.md @@ -166,6 +166,13 @@ always_apply: true # Optional: load the skill up front in every conver - **`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. +Users can also invoke a skill directly by typing `/` in [AI Chat](/guide/ai/ai-chat#using-project-skills) and picking it from a list. The AI then loads that skill before answering, instead of relying on the description to match the question. The list shows each skill's `name` and `description`, so choose a short, recognizable name and a description that reads well to people as well as to the AI. The `agents` field controls where a skill is listed: + +- Skills with `analyst` are listed in the project chat, the Explore and Canvas dashboard chats, and chat in embedded dashboards. +- Skills with `developer` are listed in the developer chat in Rill Developer. + +Skills with an error are not listed. In analysis chats, a skill that was already loaded earlier in the conversation is not loaded again. The developer chat loads a referenced skill on every message that references it, because the developer agent only sees the current message's tool calls. An `always_apply` skill is already loaded, so picking it has no additional effect. + 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. diff --git a/docs/docs/guide/ai/ai-chat.md b/docs/docs/guide/ai/ai-chat.md index 7edf4b2e9bab..e954be4042b1 100644 --- a/docs/docs/guide/ai/ai-chat.md +++ b/docs/docs/guide/ai/ai-chat.md @@ -59,6 +59,31 @@ Opening AI Chat from within a dashboard allows for more natural, context-aware q If the project administrator has configured starter prompts for a dashboard or for the project, a new chat shows them as clickable suggestions. Click one to send it with your current filters and time range applied. Prompts are configured with the `ai_prompts` key; see [AI Configuration](/developers/build/ai-configuration#suggested-prompts). +## Using Project Skills + +Skills are playbooks that your project's developers write for the AI, such as how to investigate a revenue drop or what your company's business terms mean. The AI loads a skill on its own when your question matches the skill's description. To make sure the AI follows a specific skill, invoke it yourself with `/`: + +1. In the chat input, type `/` at the start of a line or after a space, or click the **/** button next to **@** below the input. +2. Pick a skill from the list. Each entry shows the skill's name and description. Keep typing to narrow the list, and use the arrow keys and **Enter** to select. +3. Type your question after the skill and send the message. + +![Skill picker in AI Chat](/img/explore/chat/skill-picker.png) + +The list shows the skills that apply to the chat you're in: + +| Chat | Skills listed | +|------|---------------| +| Project chat (the **AI** tab), dashboard chat on Explore and Canvas dashboards, and chat in embedded dashboards | Skills written for data analysis (`agents: [analyst]`) | +| Developer chat, which edits your project files in Rill Developer | Skills written for project development (`agents: [developer]`) | + +The **/** button appears only when the project has skills for that chat. Skills with errors in their file are not listed. + +When the AI uses a skill, whether you picked it or the AI chose it, the response's activity trace shows a **Loaded skill** step. In an analysis chat, a skill is loaded once per conversation, so referencing it again in a later message does not add it a second time. + +:::tip Writing skills +Skills are files in your project. To create or change one, see [Skills](/developers/build/ai-configuration#skills) in the AI Configuration guide. +::: + ## Understanding Responses AI Chat provides rich, multi-layered responses to help you understand your data quickly while maintaining easy access to deeper exploration: diff --git a/docs/docs/guide/ai/mcp.md b/docs/docs/guide/ai/mcp.md index 8034a07b892d..fa0987cb2c1b 100644 --- a/docs/docs/guide/ai/mcp.md +++ b/docs/docs/guide/ai/mcp.md @@ -263,6 +263,10 @@ You can look at one of our [example projects](https://github.com/rilldata/rill-e - __*List skills*__ – Use `list_skills` to discover the [skills](/developers/build/ai-configuration#skills) defined in the project. It returns an empty list when the project defines no skills. - __*Load a skill*__ – Use `load_skill` to fetch a skill's full instructions before doing work its description covers. +The skill tools are available to every user who can use AI features in the project, whether or not the project defines skills. `list_skills` returns every skill in the project with its `description`, `metrics_views`, `agents` and `always_apply` fields, so the client can pick the ones that fit its task. If `load_skill` is called with a name that doesn't exist, the error lists the skills that do. + +The `/` skill picker is part of Rill's [AI Chat](/guide/ai/ai-chat#using-project-skills). In an external client, ask for a skill by name instead, for example: "Use the `revenue-rca` skill to explain last week's revenue drop." + ### Usage Examples diff --git a/docs/static/img/explore/chat/skill-picker.png b/docs/static/img/explore/chat/skill-picker.png new file mode 100644 index 000000000000..ea732c546280 Binary files /dev/null and b/docs/static/img/explore/chat/skill-picker.png differ