docs: document Agent Skills for the Cube AI agent

CLAUDE.md

@@ -50,13 +50,24 @@ yarn test
 ```
 
 ### Documentation Development
-The documentation is in `/docs` directory:
+
+**IMPORTANT: `/docs-mintlify` is the active documentation site. `/docs` is the legacy
+docs site and is deprecated — do NOT add or edit content there.** When asked to write or
+update documentation, work in `/docs-mintlify` unless the user explicitly says otherwise.
+
 ```bash
-cd docs
-yarn dev    # Start development server
-yarn build  # Build for production
+cd docs-mintlify
+yarn dev    # Start the Mintlify dev server
 ```
 
+- Content is authored as `.mdx` under topic directories (e.g. `admin/ai/`, `docs/explore-analyze/`).
+- Frontmatter uses `title` and `description` keys.
+- Navigation is registered in `docs-mintlify/docs.json` (pages must be added to the
+  relevant `group` to appear in the sidebar).
+- Use Mintlify components: `<Note>`, `<Warning>`, `<Info>`, `<Tip>`, `<Steps>`/`<Step>`,
+  `<CardGroup>`/`<Card>`. Internal links are root-relative (e.g. `/admin/ai/rules`).
+- See `docs-mintlify/CLAUDE.md` for full conventions.
+
 ## Architecture Overview
 
 ### Monorepo Structure
@@ -66,7 +77,8 @@ yarn build  # Build for production
   - Database drivers: `cubejs-postgres-driver`, `cubejs-bigquery-driver`, etc.
   - API layer: `cubejs-api-gateway`
 - **`/rust`**: Rust components including CubeSQL (SQL interface) and CubeStore (distributed storage)
-- **`/docs`**: Next.js documentation site
+- **`/docs-mintlify`**: Mintlify documentation site — **the active docs site** (author docs here)
+- **`/docs`**: Legacy Next.js/Nextra documentation site — **deprecated**, do not edit
 - **`/examples`**: Example implementations and recipes
 
 ### Key Components
@@ -133,7 +145,8 @@ Include scope in parentheses when applicable, e.g., `fix(tesseract):` or `feat(d
 
 ## Important Notes
 
-- This is documentation for the old Cube docs site structure (the existing `/docs/CLAUDE.md` refers to the documentation site)
+- Documentation lives in `/docs-mintlify` (active, Mintlify). `/docs` is the legacy docs
+  site and is deprecated — do not add or edit content there. See `docs-mintlify/CLAUDE.md`.
 - The main Cube application development happens in `/packages`
 - For data model changes, focus on `cubejs-schema-compiler` package
 - For query execution changes, focus on `cubejs-query-orchestrator` package

docs-mintlify/CLAUDE.md

@@ -0,0 +1,69 @@
+# Cube Documentation (Mintlify)
+
+This is the **active** Cube documentation site, built with [Mintlify](https://mintlify.com).
+All documentation work should happen here.
+
+> The `/docs` directory at the repo root is the **legacy** Nextra docs site and is
+> **deprecated** — do not add or edit content there.
+
+## Local development
+
+```bash
+cd docs-mintlify
+yarn dev    # Start the Mintlify dev server
+```
+
+## Writing style
+
+- **Tone**: professional, direct, instructive. Address the reader as "you" (second person).
+- **Headings**: one H1 is provided by the frontmatter `title` — start body sections at H2 (`##`).
+- **Code**: always specify a language fence (` ```yaml`, ` ```markdown`, ` ```text`). Use
+  inline backticks for identifiers (`accessible_views`, `agents/rules/`).
+- **Paragraphs**: keep them short; use `-` bullet lists for multiple items.
+
+## File and frontmatter conventions
+
+- Content is `.mdx`, organized by topic directory (e.g. `admin/ai/`, `docs/explore-analyze/`).
+- The file path maps to the URL: `admin/ai/rules.mdx` → `/admin/ai/rules`.
+- Every page starts with YAML frontmatter using `title` and `description`:
+
+  ```mdx
+  ---
+  title: Rules
+  description: One-sentence summary used for SEO and navigation previews.
+  ---
+  ```
+
+- **Do not** add an H1 in the body — the `title` is the page heading.
+
+## Navigation
+
+Navigation is defined in `docs-mintlify/docs.json`. A new page only appears in the sidebar
+once its path (without the `.mdx` extension) is added to the appropriate `group` in
+`docs.json`. After adding a page, update `docs.json` and verify it is still valid JSON.
+
+## Components
+
+Mintlify provides these components (used throughout the docs):
+
+- Callouts: `<Note>`, `<Warning>`, `<Info>`, `<Tip>`, `<Check>`
+- `<Steps>` with nested `<Step title="...">` for sequential instructions
+- `<CardGroup cols={2}>` with nested `<Card title="..." icon="..." href="...">`
+- `<Tabs>` / `<Tab>`, `<Accordion>` / `<AccordionGroup>`, `<Frame>` for images
+
+Content inside callouts and steps is plain MDX. Internal links are root-relative
+(`/admin/ai/skills`), not file paths.
+
+## Images and screenshots
+
+Wrap screenshots in `<Frame>` and store assets under `images/`. When a screenshot is
+needed but not yet available, leave an MDX comment placeholder: `{/* TODO: screenshot — ... */}`.
+
+## AI / agent docs structure
+
+The agent configuration (code-first, developer-facing) lives under `admin/ai/`:
+`rules.mdx`, `certified-queries.mdx`, `skills.mdx`, `memory-isolation.mdx`,
+`multi-agent.mdx`, `bring-your-own-model.mdx`. The end-user chat experience
+(explorer/viewer-facing) lives under `docs/explore-analyze/` (e.g. `analytics-chat.mdx`,
+`skills.mdx`). Keep authoring docs in `admin/ai/` and usage docs in `docs/explore-analyze/`,
+and cross-link the two.

docs-mintlify/admin/ai/index.mdx

@@ -59,6 +59,7 @@ Rules and certified queries have their own dedicated pages:
 
 - [Rules](/admin/ai/rules) — instructions that guide the agent's behavior
 - [Certified queries](/admin/ai/certified-queries) — a library of trusted SQL examples for the agent
+- [Skills](/admin/ai/skills) — reusable, named agent workflows users can run on demand from chat
 
 ## LLM
 
@@ -134,6 +135,9 @@ See [Memories](/admin/ai/memory-isolation) for details on how memories are store
   <Card title="Certified queries" icon="certificate" href="/admin/ai/certified-queries">
     Provide a library of trusted SQL queries for the agent to reference.
   </Card>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/admin/ai/skills">
+    Package reusable, named agent workflows that users can run on demand from chat.
+  </Card>
   <Card title="Bring your own model" icon="brain" href="/admin/ai/bring-your-own-model">
     Configure the agent to use your own LLM provider or model.
   </Card>

docs-mintlify/admin/ai/skills.mdx

@@ -0,0 +1,135 @@
+---
+title: Skills
+description: Package reusable, named agent workflows in your data model repository that users can run on demand from chat.
+---
+
+Skills are reusable, named instruction packages for the agent — saved workflows a user
+can run on demand wherever they work with the agent, including
+[Analytics Chat](/docs/explore-analyze/analytics-chat), Workbooks, dashboards, and the
+IDE. Instead of re-typing the same multi-step request ("produce a weekly revenue report,
+broken down by region, with week-over-week trends…"), a user picks a skill and the agent
+follows the workflow you've defined.
+
+Skills are configured as code in your [data model repository](/admin/ai#agent-configuration),
+alongside your cubes and views, so they're versioned, reviewed, and deployed like the rest
+of your Cube project.
+
+<Note>
+A skill guides what the agent does using the same data access the agent already has. The
+first version of skills is instructions-only — `title`, `description`, and instructions.
+There is no per-skill data scoping or external actions yet.
+</Note>
+
+## Defining skills
+
+Skills are defined as Markdown files under `agents/skills/`. Each skill lives in its own
+file: the YAML frontmatter holds metadata, and the Markdown body is the instructions the
+agent follows.
+
+```markdown
+<!-- agents/skills/weekly-revenue-report.md -->
+---
+title: "Weekly revenue report"
+description: "Use when the user asks for a weekly revenue summary, a weekly revenue report, or week-over-week revenue trends."
+---
+Produce a weekly revenue report:
+
+1. Report total revenue for the requested week, alongside the prior week and the
+   week-over-week percentage change.
+2. Break revenue down by region, sorted from highest to lowest.
+3. Highlight any region whose revenue changed by more than 10% week over week.
+4. If the user names a region or a time range, scope the report accordingly.
+```
+
+Files placed under a `skills/` directory are treated as skills automatically — no `kind`
+property is required. The `name` is inferred from the file name (e.g.,
+`weekly-revenue-report.md` → `weekly-revenue-report`). Nested folders are allowed for
+organization but do not namespace the skill — skill names must be unique across the
+entire `skills/` directory.
+
+### Frontmatter properties
+
+| Property        | Type   | Required | Description                                                                       |
+|-----------------|--------|:--------:|-----------------------------------------------------------------------------------|
+| `title`         | string | Yes      | User-facing label shown on the skill button and in the `/` menu.                  |
+| `description`   | string | Yes      | What the agent matches free-text requests against to auto-select the skill.       |
+| `name`          | string | No       | Unique identifier. Inferred from the file name if omitted.                        |
+
+The Markdown body is the skill's instructions.
+
+### Inlining skills in YAML
+
+You can also inline skills directly in `agents/config.yml` under a `skills` key:
+
+```yaml
+# agents/config.yml
+skills:
+  - name: weekly-revenue-report
+    title: "Weekly revenue report"
+    description: "Use when the user asks for a weekly revenue summary or week-over-week trends."
+    instructions: |
+      Produce a weekly revenue report:
+      1. Total revenue for the requested week, with the week-over-week change.
+      2. A breakdown by region, sorted by revenue descending.
+      3. Highlight any region that moved more than 10% week over week.
+```
+
+Inline skills use the same `name`, `title` (required), and `description` (required) as
+Markdown skills. Since there is no Markdown body in YAML, provide the instructions inline
+via the `instructions` key.
+
+<Note>
+Skills inlined at the root of `agents/config.yml` are attached to the implicit `auto`
+space and applied to the default agent in a [single-agent setup](/admin/ai). In a
+[multi-agent setup](/admin/ai/multi-agent), attach skills to a specific space by inlining
+them under that space's `skills` key (or by placing Markdown files under
+`agents/skills/<space-name>/`).
+</Note>
+
+## How skills are surfaced
+
+Skills use **progressive disclosure**. The agent is given a compact catalog of every
+available skill — just the `name`, `title`, and `description` — so it knows what each
+skill is for without carrying the full instructions. When a skill is run, the agent loads
+its complete instructions on demand.
+
+- The chat UI only ever receives a skill's `name`, `title`, and `description`. The full
+  instruction body stays server-side and is never sent to the browser.
+- Skills are surfaced through a viewer-accessible deployment endpoint, so they work for
+  any configured agent as well as the default `auto` agent.
+- Because the agent matches against `description`, a well-written description makes
+  automatic matching more reliable.
+
+For how skills appear and run in chat — buttons, the `/` menu, and automatic matching —
+see [Agent skills](/docs/explore-analyze/skills).
+
+## Deploying and testing
+
+Skills ship through the normal Cube development flow: author the skill on a development
+branch, commit, and merge to your production branch. Because skills live on the branch, a
+skill on a development branch is testable before it reaches production — open chat against
+the dev branch and run the skill to confirm it behaves as intended.
+
+## Permissions
+
+Authoring skills requires data-model edit access — the same access needed to define
+[rules](/admin/ai/rules) and [certified queries](/admin/ai/certified-queries). In Cube
+Cloud's built-in roles, that means the **Admin** or **Developer**
+[roles](/admin/users-and-permissions/roles-and-permissions), or a custom role with
+semantic-model edit access.
+
+Running skills is available to anyone with chat access, including **Explorer** and
+**Viewer** roles. In-product tips that promote authoring skills, rules, and certified
+queries are role-aware and shown only to developers.
+
+## Writing effective skills
+
+- **Phrase `description` as a "use when…" statement.** This is what the agent matches
+  against incoming requests, so describe the situations the skill applies to.
+- **Write instructions as an explicit workflow.** Number the steps and state the output
+  you expect, the same way you'd brief an analyst.
+- **Account for added context.** Users can add specifics after selecting a skill (e.g.,
+  `/weekly-revenue-report for EMEA, last 6 weeks`), so instruct the agent to honor a
+  named region or time range when provided.
+- **Keep each skill focused.** One skill should cover one well-defined workflow; create
+  separate skills for distinct tasks.

docs-mintlify/docs.json

@@ -91,7 +91,8 @@
                   }
                 ]
               },
-              "docs/explore-analyze/analytics-chat"
+              "docs/explore-analyze/analytics-chat",
+              "docs/explore-analyze/skills"
             ]
           },
           {
@@ -378,6 +379,7 @@
               "admin/ai/index",
               "admin/ai/rules",
               "admin/ai/certified-queries",
+              "admin/ai/skills",
               "admin/ai/memory-isolation",
               "admin/ai/multi-agent",
               "admin/ai/bring-your-own-model"

docs-mintlify/docs/explore-analyze/skills.mdx

@@ -0,0 +1,68 @@
+---
+title: Agent skills
+description: Run saved agent workflows using skill buttons, the slash menu, or automatic matching.
+---
+
+Skills are reusable, named workflows the agent can run on demand wherever you work with
+it — [Analytics Chat](/docs/explore-analyze/analytics-chat), Workbooks, dashboards, and
+the IDE. Instead of re-typing the same multi-step request every time, you pick a skill and
+the agent follows the workflow your team has already defined — for example, a
+**Weekly revenue report** that totals revenue, breaks it down by region, and calls out
+week-over-week trends.
+
+Skills are authored by your data team as part of the semantic model. This page covers how
+to find and run them. To create skills, see [Skills](/admin/ai/skills) in the agent
+configuration docs.
+
+<Frame>
+  <img src="https://static.cube.dev/blog/2026/06/introducing-cube-agent-skills/slash-menu.png" alt="The slash menu in Analytics Chat listing available agent skills, each with a title and description" />
+</Frame>
+
+## Running a skill
+
+There are three ways to run a skill from the chat input.
+
+<Steps>
+  <Step title="Skill buttons">
+    When skills are available, they appear as buttons in the chat empty state — one button
+    per skill, labeled with the skill's title. Click a button to start the skill.
+
+    {/* TODO: screenshot — skill buttons in the chat empty state */}
+  </Step>
+  <Step title="Slash menu">
+    Type `/` in the chat input to open the skill menu. The menu filters as you type and is
+    keyboard-navigable. When skills are available, the input placeholder reads
+    **"Type / for skills."**
+  </Step>
+  <Step title="Automatic matching">
+    You don't always have to pick a skill explicitly. If a free-text request matches a
+    skill's description, the agent recognizes the intent and runs the matching skill on
+    its own — asking "can I get the weekly revenue summary?" may trigger a weekly revenue
+    report skill.
+  </Step>
+</Steps>
+
+## Adding context before you run
+
+Picking a skill — whether from a button or the `/` menu — does **not** send the message
+immediately. Instead, it inserts a styled `/skill-name` token into the chat input and
+keeps your cursor there.
+
+{/* TODO: screenshot — the styled `/skill-name` token in the chat input */}
+
+This lets you add specifics before running. Type any extra context after the token, then
+send. On send, the message becomes the skill invocation plus whatever you added. For
+example:
+
+```text
+/weekly-revenue-report for EMEA, last 6 weeks
+```
+
+runs the weekly revenue report skill, scoped to the EMEA region over the last six weeks.
+
+<Note>
+Running skills is available to anyone with chat access, including **Explorer** and
+**Viewer** [roles](/admin/users-and-permissions/roles-and-permissions). Authoring skills
+requires data-model edit access — see [Skills](/admin/ai/skills) in the agent
+configuration docs.
+</Note>

docs/CLAUDE.md

@@ -1,4 +1,9 @@
-# Cube Documentation
+# Cube Documentation (LEGACY — DEPRECATED)
+
+> **This `/docs` site is deprecated. Do not add or edit content here.**
+> The active documentation site is `/docs-mintlify` (Mintlify). Write all new and updated
+> docs there — see `docs-mintlify/CLAUDE.md` for conventions. The guidance below is kept
+> only for reference to the legacy site.
 
 This file provides guidance to Claude Code when working with the documentation site.