用途
本技能用于配置 Cube 产品内的 AI 智能体，检查和调优它的规则（rules）、认证查询（certified queries）以及 Agent Skills。整体上更偏重方法论（know-how）而非命令：只有两次 CLI 调用用于读取当前状态，其余工作都是把 Markdown 写入数据模型，因此需要配合 cube-build-model 的 dev-mode 工作流。
主要能力
- 通过 Cube MCP 工具或 CLI 查看部署中已配置的智能体与技能元数据。
- 在数据模型的 agents/ 目录下编写规则、认证查询和技能。
- 在 dev-mode 分支上测试规则、认证查询和技能，再提交变更。
- 诊断智能体给出错误答案的原因。
使用方式
选择路径
Cube MCP 工具在文中写作 cube:<tool>，指本插件捆绑的 cube 服务器。通过 Cube 连接器使用时，同样的工具会带上连接器的名称。
如果 Cube MCP 工具可用（本插件的 cube 服务器或 Cube 连接器），可以像编辑其他模型文件一样编辑智能体配置，使用 cube-build-model 循环：cube:startDataModelEdit，然后在 agents/ 下用 cube:readDataModelFile 和 cube:writeDataModelFile，最后 cube:commitDataModelChanges。MCP 路径有两点更好：
- cube:listDeployments 返回每个部署的智能体。
- cube:chat 配合 dev 分支的 branchName，让 Cube 的智能体针对该分支的规则、认证查询和技能运行。在两次独立对话中分别询问修改前和修改后出错的同一个问题——一次对话会停留在它开始时的分支上。
CLI 的 cube agents skills 一次调用即可列出技能元数据；通过 MCP 则列出 agents/skills/ 下的文件。
预检（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
查看已有配置
cube agents list <deployment>
cube agents skills <deployment>
cube agents skills <deployment> --space <space> --branch <branch>
cube agents skills 返回 name、title 和 description——即智能体用于匹配的元数据。它不返回指令内容；指令需从下面的模型文件中读取。
智能体配置位于数据模型中
在项目的 agents/ 目录下——设置放在 YAML，其余均为 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
2026 年 4 月 30 日之前创建的部署，只有在设置了 CUBE_CLOUD_AGENTS_CONFIG_ENABLED=true 时才会读取这些文件——可用 cube variables list <deployment> 或 MCP 的 cube:getDeploymentEnv 检查。没有该设置时，在此处的写入不会生效，且是静默的。当存在多个智能体时，规则、认证查询和技能也可以放在按 space 划分的子目录中，例如 agents/rules/<space>/。
在 dev-mode 分支上使用 cube data-model 读写：
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>
文件名即身份。weekly-revenue-report.md 会成为技能 weekly-revenue-report。由于这些是项目文件，它们继承项目的 git 流程、评审和访问策略——dev 分支上的规则在到达任何人之前都是可测试的。
该用哪一种
这是本技能存在的判断核心。
| 使用 | 何时 |
|---|---|
| 规则（Rule） | 应适用于每个答案的事实或约束。"Revenue excludes refunds." "Never show data before 2024." 始终在上下文中，因此保持少而短。 |
| 认证查询（Certified query） | 有唯一正确查询的特定问题。固定答案，让智能体不再重新推导。 |
| 技能（Skill） | 一个人否则需要反复输入的可重复多步工作流。"Weekly revenue report"——拉取、拆分、比较、总结。 |
常见错误是把本应是技能的东西写成规则。规则始终被加载，因此每条规则都会计入每次对话；规则列表过长会稀释所有规则。如果某条指令只在有人请求特定内容时才重要，那它就是技能。
写好规则
- 陈述事实，而非行为。"Active user means logged in within 28 days" 优于 "always calculate active users correctly"。
- 一条规则一个想法。拆分复合规则；它们更易评审，过时后也更易删除。
- 优先修复模型。解释命名不佳的度量含义的规则是一种变通——用 cube-build-model 重命名该度量可为所有消费者修复，而不仅是智能体。
写好技能
- Frontmatter 的 title 和 description（均为必填），Markdown 正文写指令。description 是智能体用来匹配自由文本请求的依据，因此要按用户提问的方式写，而不是按你归档的方式写。
- 给步骤编号。说明输出应是什么样子。如果某步骤依赖某个认证查询或特定视图，请点名。
诊断错误答案
当有人说智能体答错了，按此顺序检查：
- 模型对吗？错误的度量会产生错误答案，再多指令也修不好。用 cube-run-query 验证。
- 字段暴露了吗？如果不在某个视图中，智能体就无法使用它。
- 有冲突的规则吗？读每一条规则，而不只是相关的那条。矛盾规则很常见，症状就是不一致。
- 只有到这时才添加规则或认证查询。
跳过第 4 步之前，正是部署最终积累三十条规则来掩盖四个模型问题的原因。
出错时
| 症状 | 原因 |
|---|---|
| 技能不出现 | 不在对话使用的分支上，或该分支尚未构建 |
| 写入被拒绝 | 不在 dev-mode 分支上——见 cube-build-model |
| cube agents skills 返回空 | 未编写技能，或 --space/--branch 错误 |
适用场景
- 需要为 Cube 产品内 AI 智能体配置规则、认证查询和技能时。
- 需要诊断智能体给出错误答案的原因时。
- 需要在 dev-mode 分支上测试智能体配置变更时。
限制
- 2026 年 4 月 30 日之前创建的部署，需设置 CUBE_CLOUD_AGENTS_CONFIG_ENABLED=true 才会读取 agents/ 下的文件，否则写入静默无效。
- cube agents skills 只返回元数据，不返回指令内容。
- 写入需在 dev-mode 分支上进行，否则会被拒绝。
- 一次对话会停留在它开始时的分支上。