|
| 1 | +--- |
| 2 | +title: Skills |
| 3 | +description: Package reusable, named agent workflows in your data model repository that users can run on demand from chat. |
| 4 | +--- |
| 5 | + |
| 6 | +Skills are reusable, named instruction packages for the agent — saved workflows a user |
| 7 | +can run on demand wherever they work with the agent, including |
| 8 | +[Analytics Chat](/docs/explore-analyze/analytics-chat), Workbooks, dashboards, and the |
| 9 | +IDE. Instead of re-typing the same multi-step request ("produce a weekly revenue report, |
| 10 | +broken down by region, with week-over-week trends…"), a user picks a skill and the agent |
| 11 | +follows the workflow you've defined. |
| 12 | + |
| 13 | +Skills are configured as code in your [data model repository](/admin/ai#agent-configuration), |
| 14 | +alongside your cubes and views, so they're versioned, reviewed, and deployed like the rest |
| 15 | +of your Cube project. |
| 16 | + |
| 17 | +<Note> |
| 18 | +A skill guides what the agent does using the same data access the agent already has. The |
| 19 | +first version of skills is instructions-only — `title`, `description`, and instructions. |
| 20 | +There is no per-skill data scoping or external actions yet. |
| 21 | +</Note> |
| 22 | + |
| 23 | +## Defining skills |
| 24 | + |
| 25 | +Skills are defined as Markdown files under `agents/skills/`. Each skill lives in its own |
| 26 | +file: the YAML frontmatter holds metadata, and the Markdown body is the instructions the |
| 27 | +agent follows. |
| 28 | + |
| 29 | +```markdown |
| 30 | +<!-- agents/skills/weekly-revenue-report.md --> |
| 31 | +--- |
| 32 | +title: "Weekly revenue report" |
| 33 | +description: "Use when the user asks for a weekly revenue summary, a weekly revenue report, or week-over-week revenue trends." |
| 34 | +--- |
| 35 | +Produce a weekly revenue report: |
| 36 | + |
| 37 | +1. Report total revenue for the requested week, alongside the prior week and the |
| 38 | + week-over-week percentage change. |
| 39 | +2. Break revenue down by region, sorted from highest to lowest. |
| 40 | +3. Highlight any region whose revenue changed by more than 10% week over week. |
| 41 | +4. If the user names a region or a time range, scope the report accordingly. |
| 42 | +``` |
| 43 | + |
| 44 | +Files placed under a `skills/` directory are treated as skills automatically — no `kind` |
| 45 | +property is required. The `name` is inferred from the file name (e.g., |
| 46 | +`weekly-revenue-report.md` → `weekly-revenue-report`). Nested folders are allowed for |
| 47 | +organization but do not namespace the skill — skill names must be unique across the |
| 48 | +entire `skills/` directory. |
| 49 | + |
| 50 | +### Frontmatter properties |
| 51 | + |
| 52 | +| Property | Type | Required | Description | |
| 53 | +|-----------------|--------|:--------:|-----------------------------------------------------------------------------------| |
| 54 | +| `title` | string | Yes | User-facing label shown on the skill button and in the `/` menu. | |
| 55 | +| `description` | string | Yes | What the agent matches free-text requests against to auto-select the skill. | |
| 56 | +| `name` | string | No | Unique identifier. Inferred from the file name if omitted. | |
| 57 | + |
| 58 | +The Markdown body is the skill's instructions. |
| 59 | + |
| 60 | +### Inlining skills in YAML |
| 61 | + |
| 62 | +You can also inline skills directly in `agents/config.yml` under a `skills` key: |
| 63 | + |
| 64 | +```yaml |
| 65 | +# agents/config.yml |
| 66 | +skills: |
| 67 | + - name: weekly-revenue-report |
| 68 | + title: "Weekly revenue report" |
| 69 | + description: "Use when the user asks for a weekly revenue summary or week-over-week trends." |
| 70 | + instructions: | |
| 71 | + Produce a weekly revenue report: |
| 72 | + 1. Total revenue for the requested week, with the week-over-week change. |
| 73 | + 2. A breakdown by region, sorted by revenue descending. |
| 74 | + 3. Highlight any region that moved more than 10% week over week. |
| 75 | +``` |
| 76 | +
|
| 77 | +Inline skills use the same `name`, `title` (required), and `description` (required) as |
| 78 | +Markdown skills. Since there is no Markdown body in YAML, provide the instructions inline |
| 79 | +via the `instructions` key. |
| 80 | + |
| 81 | +<Note> |
| 82 | +Skills inlined at the root of `agents/config.yml` are attached to the implicit `auto` |
| 83 | +space and applied to the default agent in a [single-agent setup](/admin/ai). In a |
| 84 | +[multi-agent setup](/admin/ai/multi-agent), attach skills to a specific space by inlining |
| 85 | +them under that space's `skills` key (or by placing Markdown files under |
| 86 | +`agents/skills/<space-name>/`). |
| 87 | +</Note> |
| 88 | + |
| 89 | +## How skills are surfaced |
| 90 | + |
| 91 | +Skills use **progressive disclosure**. The agent is given a compact catalog of every |
| 92 | +available skill — just the `name`, `title`, and `description` — so it knows what each |
| 93 | +skill is for without carrying the full instructions. When a skill is run, the agent loads |
| 94 | +its complete instructions on demand. |
| 95 | + |
| 96 | +- The chat UI only ever receives a skill's `name`, `title`, and `description`. The full |
| 97 | + instruction body stays server-side and is never sent to the browser. |
| 98 | +- Skills are surfaced through a viewer-accessible deployment endpoint, so they work for |
| 99 | + any configured agent as well as the default `auto` agent. |
| 100 | +- Because the agent matches against `description`, a well-written description makes |
| 101 | + automatic matching more reliable. |
| 102 | + |
| 103 | +For how skills appear and run in chat — buttons, the `/` menu, and automatic matching — |
| 104 | +see [Agent skills](/docs/explore-analyze/skills). |
| 105 | + |
| 106 | +## Deploying and testing |
| 107 | + |
| 108 | +Skills ship through the normal Cube development flow: author the skill on a development |
| 109 | +branch, commit, and merge to your production branch. Because skills live on the branch, a |
| 110 | +skill on a development branch is testable before it reaches production — open chat against |
| 111 | +the dev branch and run the skill to confirm it behaves as intended. |
| 112 | + |
| 113 | +## Permissions |
| 114 | + |
| 115 | +Authoring skills requires data-model edit access — the same access needed to define |
| 116 | +[rules](/admin/ai/rules) and [certified queries](/admin/ai/certified-queries). In Cube |
| 117 | +Cloud's built-in roles, that means the **Admin** or **Developer** |
| 118 | +[roles](/admin/users-and-permissions/roles-and-permissions), or a custom role with |
| 119 | +semantic-model edit access. |
| 120 | + |
| 121 | +Running skills is available to anyone with chat access, including **Explorer** and |
| 122 | +**Viewer** roles. In-product tips that promote authoring skills, rules, and certified |
| 123 | +queries are role-aware and shown only to developers. |
| 124 | + |
| 125 | +## Writing effective skills |
| 126 | + |
| 127 | +- **Phrase `description` as a "use when…" statement.** This is what the agent matches |
| 128 | + against incoming requests, so describe the situations the skill applies to. |
| 129 | +- **Write instructions as an explicit workflow.** Number the steps and state the output |
| 130 | + you expect, the same way you'd brief an analyst. |
| 131 | +- **Account for added context.** Users can add specifics after selecting a skill (e.g., |
| 132 | + `/weekly-revenue-report for EMEA, last 6 weeks`), so instruct the agent to honor a |
| 133 | + named region or time range when provided. |
| 134 | +- **Keep each skill focused.** One skill should cover one well-defined workflow; create |
| 135 | + separate skills for distinct tasks. |
0 commit comments