kb-setup

KB Setup

Goal: from "plugin installed" to "kb_search answers from this repo's docs" with as little user effort as possible. Work through the steps in order; each is idempotent, so re-running the skill on a half-configured repo is safe.

0. Locate the plugin checkout

Some fallbacks below need the plugin's own files:

KB_PLUGIN="${CLAUDE_PLUGIN_ROOT:-$(ls -d ~/.claude/plugins/cache/agent-grounding/agent-kb/*/ 2>/dev/null | sort -V | tail -1)}"

1. Preflight

uv --version          # required — stop and tell the user to install uv if missing
docker info >/dev/null 2>&1 || echo "DOCKER-DOWN"

If Docker is down/absent, stop: Qdrant needs it (or the user must provide a reachable Qdrant and set QDRANT_HOST/QDRANT_GRPC_PORT).

2. Qdrant

Check, then start only if needed (idempotent):

curl -s -o /dev/null -w '%{http_code}' http://localhost:6333/healthz   # 200 = already up
docker run -d --name qdrant \
  -v qdrant_storage:/qdrant/storage \
  -p 6333:6333 -p 6334:6334 qdrant/qdrant

If the container name exists but is stopped: docker start qdrant.

3. kb.yaml

If the repo root already has one, skip ahead. Otherwise author it:

1. Survey the repo briefly: where does prose documentation live (docs/, doc/, documentation/, a wiki subtree)? Is there a Makefile with target: ## description comments? Is there an ontology directory (rare on first setup — don't invent one)?

2. Draft a minimal config — markdown sources for real doc trees, plus make_targets only if documented targets exist:

   project: <repo-name>
   sources:
     docs:
       type: markdown
       root: docs
   

3. Confirm the draft with the user before writing (one question: doc roots to include). Then write it to <repo-root>/kb.yaml.

Full field reference: $KB_PLUGIN/kb.example.yaml.

4. First index

Preferred — through the MCP tools if the agent-kb server is connected: call kb_reindex per source (or ask it to run all), then kb_list_sources.