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 |