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:listDeploymentsreturns each deployment's agents.cube:chatwith the devbranchNameruns 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-modelfixes 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:
- Is the model right? A wrong measure produces a wrong answer no amount
of instruction fixes. Verify with
cube-run-query. - Is the field exposed? If it is not in a view, the agent cannot use it.
- Is there a conflicting rule? Read every rule, not just the relevant one. Contradictory rules are common and the symptom is inconsistency.
- 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-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.
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.
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.
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.
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.
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.