AGENT SKILL

cube-configure-agent

Inspect and tune Cube's in-product AI agent — its rules, certified queries and Agent Skills — by authoring markdown in the semantic model, through the Cube MCP tools or the Cube CLI. Use whenever someone wants the Cube agent to answer better: teach it a business definition, stop it making a recurring mistake, certify a trusted query, capture a repeatable workflow as a skill, or find out why it answered the way it did. Triggers on "the agent keeps getting X wrong", "teach the agent that", "make the agent always", "add a certified query", "create an agent skill", "why did the agent say that", "what rules does the agent have". To change the underlying model use cube-build-model; to explore what is queryable use cube-explore-model.

License 许可
Apache-2.0
最近更新
2026-10-01
Stars
★ 4
Forks
0

01 前言 Front Matter

name
cube-configure-agent
license
Apache-2.0
description
Inspect and tune Cube's in-product AI agent — its rules, certified queries and Agent Skills — by authoring markdown in the semantic model, through the Cube MCP tools or the Cube CLI. Use whenever someone wants the Cube agent to answer better: teach it a business definition, stop it making a recurring mistake, certify a trusted query, capture a repeatable workflow as a skill, or find out why it answered the way it did. Triggers on "the agent keeps getting X wrong", "teach the agent that", "make the agent always", "add a certified query", "create an agent skill", "why did the agent say that", "what rules does the agent have". To change the underlying model use cube-build-model; to explore what is queryable use cube-explore-model.
compatibility
Needs the Cube MCP server (bundled in the Cube plugin, or the Cube connector) or the Cube CLI, and network access to Cube Cloud.

03 SKILL.md 正文

Configure the Cube agent

Mostly know-how rather than commands. Two CLI calls read the current state; everything else is writing markdown into the data model, which means the dev-mode workflow from cube-build-model applies.

Choose the path

Cube MCP tools are written cube:<tool> below: the cube server this plugin bundles. Through the Cube connector, the same tools carry the connector's name.

If the Cube MCP tools are available (this plugin's cube server or the Cube connector), edit agent configuration like any other model file, with the cube-build-model loop: cube:startDataModelEdit, then cube:readDataModelFile and cube:writeDataModelFile under agents/, then cube:commitDataModelChanges. Two things the MCP path does better:

  • cube:listDeployments returns each deployment's agents.
  • cube:chat with the dev branchName runs Cube's agent against that branch's rules, certified queries and skills. Ask the question that went wrong before and after the change, in two separate chats — a chat stays on the branch it started on.

The CLI's cube agents skills lists skill metadata in one call; over MCP, list the files under agents/skills/.

Preflight (CLI)

command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list

See what's configured

cube agents list <deployment>
cube agents skills <deployment>
cube agents skills <deployment> --space <space> --branch <branch>

cube agents skills returns name, title and description — the metadata the agent matches on. It does not return the instructions; read those from the model files below.

Agent config lives in the data model

Under agents/ in the project — settings in YAML, everything else as markdown:

agents/
  rules/               always-on instructions
  certified_queries/   trusted, named queries
  skills/              named multi-step workflows, run from the / menu
  config.yml           agent settings: llm, runtime, accessible_views, memory_mode

Deployments created before April 30, 2026 read these files only when CUBE_CLOUD_AGENTS_CONFIG_ENABLED=true is set — check with cube variables list <deployment> or the MCP cube:getDeploymentEnv. Without it, writes here change nothing, silently. With several agents, rules, certified queries and skills can also sit in per-space subdirectories such as agents/rules/<space>/.

Read and write them with cube data-model, on a dev-mode branch:

cube data-model get <deployment> agents/rules/revenue-definitions.md
cube data-model dev-mode <deployment> main
cube data-model put <deployment> agents/skills/weekly-revenue-report.md --file ./skill.md --branch <dev-branch>
cube data-model commit <deployment> -m "Add weekly revenue report skill" --branch <dev-branch>

The filename is the identity. weekly-revenue-report.md becomes the skill weekly-revenue-report. Because these are project files, they inherit the project's git flow, review and access policies — a rule on a dev branch is testable before it reaches anyone.

Which one to reach for

This is the judgement the skill exists to carry.

Use When
Rule A fact or constraint that should apply to every answer. "Revenue excludes refunds." "Never show data before 2024." Always in context, so keep them few and short.
Certified query A specific question with one correct query. Pins the answer so the agent stops re-deriving it.
Skill A repeatable multi-step workflow a person would otherwise re-type. "Weekly revenue report" — pull, break down, compare, summarize.

The common mistake is writing a rule for something that should be a skill. Rules are always loaded, so every rule is charged to every conversation; a long list of them dilutes all of them. If the instruction only matters when someone asks for a particular thing, it is a skill.

Writing a good rule

  • State the fact, not the behaviour. "Active user means logged in within 28 days" beats "always calculate active users correctly".
  • One idea per rule. Split compound rules; they are easier to review and to delete when they go stale.
  • Prefer fixing the model. A rule that explains what a badly named measure means is a workaround — renaming the measure with cube-build-model fixes it for every consumer, not just the agent.

Writing a good skill

Frontmatter title and description (both required), markdown body for the instructions. The description is what the agent matches free-text requests against, so write it the way a user would ask, not the way you would file it.

Number the steps. Say what the output should look like. If a step depends on a certified query or a specific view, name it.

Diagnosing a bad answer

When someone says the agent got something wrong, check in this order:

  1. Is the model right? A wrong measure produces a wrong answer no amount of instruction fixes. Verify with cube-run-query.
  2. Is the field exposed? If it is not in a view, the agent cannot use it.
  3. Is there a conflicting rule? Read every rule, not just the relevant one. Contradictory rules are common and the symptom is inconsistency.
  4. Only then add a rule or certified query.

Skipping to step 4 is how deployments end up with thirty rules that paper over four model problems.

When something fails

Symptom Cause
Skill does not appear Not on the branch the chat is using, or the branch has not been built
Write rejected Not on a dev-mode branch — see cube-build-model
cube agents skills returns nothing No skills authored, or the wrong --space/--branch

04 同仓库更多 Skills

cube-js
cube-js/cube-agent-skills

cube-run-query

Run queries against a Cube deployment's semantic layer and interpret the results — through the Cube MCP tools when they are connected, or the Cube CLI from a terminal. Use whenever someone wants numbers out of Cube — pull a metric, check a total, compare periods, verify that a measure returns what it should, sanity-check a model change. Triggers on "how many", "what's the total", "show me revenue by month", "did that measure work", "what's our MoM growth", "pull the numbers for", and any request to verify a model change against real data. To find out what is queryable first use cube-explore-model; to change the model use cube-build-model; to save a result as a report or dashboard use cube-build-content.

★ 4
cube-js
cube-js/cube-agent-skills

cube-explore-model

Search and inspect a Cube semantic model — cubes, views, measures, dimensions, joins, and the files they live in — through the Cube MCP tools or the Cube CLI. Use whenever someone wants to know what data is available in Cube, where a metric is defined, which cube a field belongs to, how two cubes join, or what a change would affect. Triggers on "what can I query", "what measures do we have", "where is revenue defined", "show me the data model", "what's in this deployment", "which cube has customer email", and impact questions like "what breaks if I rename this". Read the model with this skill before changing it. To edit the model use cube-build-model; to run a query and get numbers back use cube-run-query; to browse workbooks, dashboards and reports use cube-explore-content.

★ 4
cube-js
cube-js/cube-agent-skills

cube-explore-content

Find and inspect saved content in a Cube workspace — workbooks, dashboards, reports, folders and scheduled notifications — using the Cube CLI, or the Cube MCP tools for content you already have a link to. Use whenever someone wants to know what already exists rather than build something new: locate a dashboard, list reports, see what a report queries, find who a notification goes to, or check what saved content references a model field before renaming it. Triggers on "what dashboards do we have", "find the revenue report", "where is that workbook", "what's in this folder", "who gets this scheduled report", "is anything using this field". To create or edit content use cube-build-content; to inspect the semantic model itself use cube-explore-model.

★ 4
cube-js
cube-js/cube-agent-skills

cube-embed

Set up and debug Cube embedded analytics — embed sessions, embed tokens, embeddable dashboards and embed tenants — using the Cube CLI. Use whenever someone is shipping Cube analytics inside their own product: mint a session for an end user, enable a dashboard for embedding, set up multi-tenant isolation so each customer sees only their data, or debug why an embedded view is empty or unauthorized. Triggers on "embed this dashboard", "embedded analytics", "our customers need to see", "multi-tenant analytics", "the iframe is blank", "embed token", "sign the embed URL", "customer-facing dashboard". For internal access control use cube-admin; for the dashboards themselves use cube-build-content.

★ 4
cube-js
cube-js/cube-agent-skills

cube-deploy

Manage Cube deployments and their lifecycle — create deployments, deploy a project, check build status, manage environments and environment variables, connect a GitHub repo, and tail logs — using the Cube CLI. Use whenever someone wants to ship, configure or debug a deployment rather than change the model inside one. Triggers on "deploy this", "did the build pass", "why did the build fail", "set an environment variable", "create a deployment", "connect our repo", "show me the logs", "what regions are available", "the deployment is down". To change model files use cube-build-model; for users and access use cube-admin.

★ 4
cube-js
cube-js/cube-agent-skills

cube-build-model

Author and change a Cube semantic model — add or edit cubes, views, measures, dimensions, joins and pre-aggregations in YAML — on a dev-mode branch through the Cube MCP tools or the Cube CLI, then commit and build. Use whenever someone wants to add a metric, define a measure or dimension, create a cube or view, join two cubes, fix a model error, rename a field, or expose a field to business users. Triggers on "add a metric", "define revenue", "create a view for", "expose this field", "join orders to customers", "fix the model", "add a pre-aggregation". Read the model first with cube-explore-model. To run a query against the result use cube-run-query; to deploy or check build status use cube-deploy.

★ 4