Skip to content

Build KB Command /build-kb

Overview

/build-kb is a thin shortcut that asks the active chat agent to follow the bundled build-kb skill and build the project's vector-indexed knowledge base — semantic_models, metrics, and reference_sql (the LanceDB-backed stores). It is the heavy companion to the lightweight /init: where /init writes the AGENTS.md inventory plus the cheap file-based stores (knowledge / memory), /build-kb runs the expensive generation and then refreshes the AGENTS.md KB index.

The skill walks the agent through:

  1. Resolving the scope from any free-text hints you pass — specific files (globs/paths), tables, datasources, or business domains. With no hints it covers the whole project. If AGENTS.md already exists, it reuses that inventory instead of re-scanning the whole tree.
  2. Scanning and classifying the in-scope files plus database metadata into business domains. A validated-query corpus is enumerated pair by pair (never sampled) so every (question, SQL) example is indexed.
  3. Exploring each domain in parallel with read-only explore subagents (at most 3 at a time).
  4. Presenting a Generation Manifest — the resolved scope and one row per artifact to generate — then stopping for your confirmation. Reply to confirm, or correct the scope / any row.
  5. After you confirm, routing every artifact to its store via the storage-classify skill: semantic models, metrics, and reference SQL, each generated by its matching subagent (one gen_sql_summary call per SQL). Each (question, SQL) pair is dual-routed — to reference_sql (the example) and to extract-knowledge (the rule behind it).
  6. Refreshing the AGENTS.md KB index — updating ## Semantic Models / ## Metrics / ## Reference SQL with counts + retrieval tools, and appending any newly mined ## Knowledge entries. It does not rewrite the inventory sections /init owns. If AGENTS.md is missing, it writes the full file.

Because /build-kb runs through the standard chat pipeline, you get the usual UX — streamed ActionHistory events, Ctrl+O to expand trace details, ESC to interrupt, and multi-turn refinement.

The skill source lives at datus/resources/skills/build-kb/SKILL.md and is loaded directly from the installed package. Override it at ./.datus/skills/build-kb/SKILL.md (project-local, takes precedence) or ~/.datus/skills/build-kb/SKILL.md (user-global).

Basic Usage

> /build-kb
> /build-kb orders + order_items tables and queries/*.sql, sales domain only
> /build-kb only the analytics datasource

/build-kb accepts an optional free-text scope. Anything after the command is forwarded verbatim to the skill, which parses it into in-scope files / tables / datasources / domains. With no arguments it covers the whole project, scoped to the currently active datasource — when several are configured it builds only that one unless your hints name others. Switch with /datasource <name> first to target a different datasource.

When the agent runs, you'll see: load_skill, scoped filesystem and database scans, parallel task calls for the explore subagents, a pause at the Generation Manifest, then — after you confirm — batched generation task calls (gen_semantic_model, gen_metrics, gen_sql_summary, extract-knowledge) and a final edit_file on AGENTS.md.

Prerequisites

  • A configured LLM. Run /model first if no model is active.
  • A non-empty ~/.datus/conf/agent.yml with datasources configured via /datasource.
  • Recommended: run /init first so AGENTS.md and the initial knowledge/memory exist; /build-kb then reuses that inventory and only adds the vector stores. It also works standalone (it will create AGENTS.md if missing).

Relationship to /init and /bootstrap

  • vs /init — /init is the lightweight, confirmation-free pass (inventory + file-based knowledge/memory). /build-kb is the heavy, confirmation-gated pass that builds the retrieval-backed stores. Typical flow: /init, then /build-kb (optionally scoped).
  • vs /bootstrap — /bootstrap is a separate deterministic, Python TUI flow for bootstrapping the KB (schema / sql / semantic / metrics / knowledge). /build-kb is the agentic, skill-driven equivalent that understands free-text scope hints and routes through storage-classify. Use /bootstrap when you want the guided TUI; use /build-kb when you want the agent to scope and reason about what to generate.

Customizing Output

The skill is the single source of truth. To change behavior, edit:

  • Project-local override: ./.datus/skills/build-kb/SKILL.md
  • User-global override: ~/.datus/skills/build-kb/SKILL.md
  • Built-in fallback: datus/resources/skills/build-kb/SKILL.md

Project-local skills shadow user-global skills, which shadow the packaged built-in.

See also: /init, /model, /datasource (in the slash command reference), Skills Integration.