{"items":[{"id":"cmugymqdg02gyqu06ql0bl03o","slug":"kaelio-ktx-ktx","name":"ktx","description":"Installs and configures ktx, the open-source context layer for data agents — runs ktx setup non-interactively with hidden CLI flags, configures database connections and embeddings, installs agent integration, and verifies readiness. Use when the user asks an agent to add ktx to a project, connect data sources, install agent rules, ingest schema, or troubleshoot a local ktx install.","authorId":"gh:kaelio","authorName":"Kaelio","version":"0.1.0","category":"Prompt","securityLevel":"Sandbox","downloadsCount":0,"githubStars":1601,"pricePerCall":0,"manifest":{"name":"ktx","tools":[],"category":"Prompt","entrypoint":{"type":"prompt"},"description":"Installs and configures ktx, the open-source context layer for data agents — runs ktx setup non-interactively with hidden CLI flags, configures database connections and embeddings, installs agent integration, and verifies readiness. Use when the user asks an agent to add ktx to a project, connect data sources, install agent rules, ingest schema, or troubleshoot a local ktx install.","permissions":[],"systemPrompt":"# ktx\n\nInstall and configure **ktx**, the open-source context layer for data agents.\nUse this skill when a user wants an agent to add **ktx** to a project, connect\ndata sources, build initial context, install agent integration, or troubleshoot\na local **ktx** setup.\n\n## Operating rules\n\n- Act autonomously when the user asks you to install or configure **ktx**.\n  The non-interactive scripted flow below is the canonical path — bare\n  `ktx setup` is interactive (clack prompts) and an agent cannot drive it.\n- Setup's non-interactive flags are intentionally hidden from `--help`. Use the\n  flags listed below; verify uncommon flags against the docs at\n  `https://docs.kaelio.com/ktx/` or this skill — not against `--help` output.\n- Ask only for values you cannot infer: project directory, connection targets,\n  credentials, account identifiers, and source selections.\n- Prefer `file:/abs/path` secret refs over `env:VAR_NAME`. `env:` refs are\n  re-resolved against the process environment on **every** `ktx` run, so a var\n  exported only in the setup shell is gone when `ktx ingest` or `ktx mcp start`\n  runs later — the secret silently resolves to empty and the connection fails.\n  `file:` refs read from disk and survive across shells. The same caveat\n  applies to `--*-api-key-env` flags: the named var must be present in every\n  shell that runs `ktx`, including the `ktx mcp` daemon's environment.\n- A literal database URL is safe to pass — `ktx setup` auto-externalizes it\n  into `.ktx/secrets/<id>-url` and rewrites `ktx.yaml` to a `file:` ref (see\n  workflow step 2). Source credential refs are **not** auto-externalized: write\n  the secret to a file under `.ktx/secrets/` (`chmod 600`) and pass a `file:`\n  ref. Never ask the user to paste a secret when a `file:` or `env:` ref works.\n- Do not commit `.ktx/secrets/*`.\n- Print each command you run and its result.\n- Setup and ingest can run for many minutes (LLM-heavy source ingests take the\n  longest), and from the outside a slow step looks identical to a stuck one.\n  Don't go silent: say what's about to run and that it may take a while, then\n  post brief progress/liveness updates while it runs (see step 4) so the user\n  never has to wonder whether it stalled — otherwise they may kill it mid-run.\n- If a command fails, identify the cause and change something before retrying.\n\n## Gather inputs once\n\nBefore invoking `ktx setup`, collect in one round:\n\n1. Project directory (default: current working directory).\n2. LLM backend and key strategy. In `--no-input` mode the CLI defaults to\n   `anthropic` and **requires an API key**. When the user is inside Claude\n   Code, pass `--llm-backend claude-code` explicitly; otherwise pass\n   `--llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY`.\n3. Embedding backend (`sentence-transformers` is the local default and needs\n   no key; use `openai` only if the user already has a key, then pass\n   `--embedding-api-key-env OPENAI_API_KEY`).\n4. Database: driver, connection id, URL (or `env:` / `file:` ref), and one or\n   more schemas.\n5. Optional context sources (dbt, Metabase, Looker, LookML, MetricFlow,\n   Notion). Add each one with a follow-up `ktx setup --source …` run (see\n   [Add context sources](#add-context-sources)); use `--skip-sources` only\n   when the user has none.\n\nDo not discover these inputs across multiple setup runs.\n\n## Install workflow\n\n1. **Detect the install path.** If the working directory contains\n   `packages/cli/dist/bin.js` or `pnpm-workspace.yaml` referencing\n   `@kaelio/ktx` you are inside the **ktx** monorepo — build and link the\n   local CLI with `pnpm` and do **not** run `npm install -g`. Otherwise:\n\n   ```bash\n   node --version    # require >= 22; stop and ask the user if older\n   ktx --version || npm install -g @kaelio/ktx\n   ```\n\n2. **Run scripted setup** (canonical path):\n\n   ```bash\n   ktx setup --no-input --yes \\\n     --project-dir <path> \\\n     --llm-backend claude-code \\\n     --embedding-backend sentence-transformers \\\n     --database <driver> --database-connection-id <id> \\\n     --database-url '<raw-url | file:/abs/path>' \\\n     --database-schema <schema> \\\n     --skip-sources \\\n     --skip-agents\n   ```\n\n   - `--database-schema` is required for scope-bearing drivers (Postgres,\n     MySQL, ClickHouse, SQL Server, BigQuery, Snowflake) in `--no-input`:\n     setup fails fast without it unless the connection already has scope in\n     `ktx.yaml`. SQLite needs no scope.\n   - Configure one new database connection per setup invocation. For multiple\n     connections, rerun setup once per connection.\n   - Pasting a literal `--database-url` is safe: the CLI relocates the URL\n     into `.ktx/secrets/<connection-id>-url` and rewrites `ktx.yaml` to a\n     `file:` ref automatically.\n   - `ktx setup` runs agent integration as its **last** step. In `--no-input`\n     mode with neither `--target` nor `--skip-agents`, that step has no input,\n     prints `Run in a TTY, or pass --target <target>.`, and the command exits\n     non-zero **even though every database/LLM/embedding step succeeded**. Pass\n     `--skip-agents` to defer agents to step 5 (as above), or `--target <agent>`\n     to install them inline and exit 0. Judge data-layer success from\n     `ktx status`, not from this exit code.\n\n3. **Resumability and `--skip-*`.** Re-running `ktx setup` against an existing\n   project resumes its config. Use `--skip-llm`, `--skip-databases`,\n   `--skip-sources`, or `--skip-embeddings` to leave a slice unconfigured but\n   let the rest complete instead of aborting on the first failure. **When\n   resuming an existing project to change one slice (e.g. only LLM), still\n   pass the database flags from the previous run** — setup validates current\n   flags, not persisted `ktx.yaml` state.\n\n4. **Build context** if setup did not already complete one:\n\n   ```bash\n   ktx ingest <connection-id> --no-input\n   ```\n\n   `ktx ingest` always builds enriched context and requires a configured model\n   and embeddings (set during setup); a database connection without them fails\n   with an enrichment-readiness error. Note: `ktx ingest` rejects `--yes`\n   together with `--no-input` (*Choose only one runtime install mode*);\n   `ktx setup` accepts both. Use `--no-input` only for ingest.\n\n   Ingest one connection at a time. It can run for many minutes with **no\n   stdout** until it exits (LLM-heavy sources like Metabase are the slowest), so\n   don't assume it hung, and don't pipe it through `tail`/`head` — that buffers\n   all output to the end, so run it raw. Tell the user up front that the step is\n   slow, then keep them posted instead of blocking silently: run the ingest in\n   the background and poll for liveness every minute or so, reporting a one-line\n   update each time (which connection, roughly how long it's been running, and\n   that `.ktx` files are still changing) so a long run never looks stuck:\n\n   ```bash\n   find <path>/.ktx/worktrees <path>/.ktx/ingest-transcripts -type f -mmin -3\n   ```\n\n   On success, the `Ingest finished` summary table shows `done` in the\n   `Source ingest` and `Memory update` columns with no `Failed sources:`\n   section.\n\n5. **Install agent integration:**\n\n   ```bash\n   ktx setup --agents --target <claude-code|claude-desktop|codex|cursor|opencode|universal>\n   ktx mcp start --project-dir <path>\n   ```\n\n   Agent integration is **not usable until `ktx mcp start` is running**. The\n   `--agents` step prints this requirement as `Required before using agents`.\n\n6. **Fall back to bare `ktx setup` only when a human is at the keyboard** —\n   it uses interactive prompts an agent cannot answer.\n\n## Add context sources\n\nContext sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) are added\n**one at a time** — `--source` is not repeatable, so run `ktx setup` once per\nsource. Source setup is resumable against an existing project: pass\n`--skip-databases --skip-llm --skip-embeddings --skip-agents` so only the source\nis configured (the trailing agent step otherwise fails the run — see install\nstep 2). Map Metabase, Looker, and LookML to an existing database connection\nwith `--source-warehouse-connection-id <db-connection-id>` (required for those).\n**dbt ignores `--source-warehouse-connection-id`** — it maps to the warehouse by\ntable name — so omit it for dbt. Use `file:/abs/path` refs for keys and tokens\n(see the secrets rule above); `env:` refs must be exported in every later `ktx`\nshell.\n\n```bash\n# dbt — pick exactly one of --source-path (local) or --source-git-url (remote).\n# No --source-warehouse-connection-id: dbt maps to the warehouse by table name.\nktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \\\n  --source dbt --source-connection-id <id> \\\n  --source-git-url <url> --source-branch <branch>\n\n# Metabase\nktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \\\n  --source metabase --source-connection-id <id> \\\n  --source-url <url> --source-api-key-ref file:/abs/path/metabase-api-key \\\n  --source-warehouse-connection-id <db-connection-id> \\\n  --metabase-database-id <metabase-db-id>\n\n# Notion\nktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \\\n  --source notion --source-connection-id <id> \\\n  --source-auth-token-ref file:/abs/path/notion-token \\\n  --notion-crawl-mode selected_roots --notion-root-page-id <page-id>\n```\n\nNotes:\n\n- `--metabase-database-id` is the **numeric id of the warehouse inside\n  Metabase** (not the ktx connection id). Discover it from the Metabase API\n  (`GET /api/database`) or UI if the user doesn't know it.\n- `--notion-crawl-mode selected_roots` requires at least one\n  `--notion-root-page-id` (repeatable); use `all_accessible` to crawl\n  everything the token can see.\n- After adding sources, ingest each new connection so its context is queryable:\n  `ktx ingest <source-connection-id> --no-input`.\n\n## Files to inspect\n\n- `ktx.yaml`: project configuration.\n- `.ktx/secrets/*`: local secret files. Never commit them.\n- `semantic-layer/<connection-id>/*.yaml`: semantic sources for SQL\n  compilation.\n- `wiki/**/*.md`: project context pages for agents.\n- `.claude/skills/ktx/`, `.agents/skills/ktx/`, `.cursor/rules/ktx.mdc`, and\n  `.opencode/commands/ktx.md`: generated agent integration files.\n\n## Verification\n\nAfter setup, run:\n\n```bash\nktx connection test <connection-id>\nktx status --json --no-input\nktx sl --output plain          # lists compiled semantic sources; `ktx sl` has no --no-input\n```\n\n**Judge readiness from `ktx status --json` fields, not the exit code.**\n`ktx status` exits 1 whenever the LLM is `none` (`verdict: \"blocked\"`), even\nwhen embeddings and every database connection are healthy. Treat success as:\n\n- `verdict: \"ready\"` at the top of the JSON, and\n- every `connections[].status === \"ok\"` (other levels: `warn`, `fail`,\n  `skipped`), and\n- every `ktx connection test <id>` exited 0, and\n- for each ingested source, `localStats.semanticLayer[].sourceCount > 0` and\n  `localStats.wikiPages[].count > 0` — these confirm the source actually\n  produced context. Do **not** rely on `localStats.ingest.perConnection` to\n  confirm source ingests: it reflects only completed warehouse ingest reports\n  and under-reports (often lists just the warehouse connection).\n\nIf the LLM is intentionally left unconfigured, `verdict` is `blocked` and the\nexit is non-zero by design — that is still a usable context layer, so report it\nas \"ready, LLM optional\" and judge the data layer by the connection and\n`localStats` fields above rather than retrying setup.\n\n## Troubleshooting\n\nFor known failure signatures (`invalid ELF header`,\n`Native CLI binary for <plat> not found`, `Missing Anthropic API key`,\n`claude-code` probe failure, `ktx cannot work without a database` on resume,\n`Run in a TTY, or pass --target <target>.` with a misleading exit 1, and a\nsecret that resolves empty only during `ktx ingest`/`ktx mcp`), see\n[troubleshooting.md](troubleshooting.md).\n\n## Final report\n\nEnd setup work with a concise report:\n\n```text\nktx SETUP COMPLETE\n\nProject:     <path>\nLLM:         <backend> / <model>\nEmbeddings:  <backend> / <model>\nConnections: <name> (<driver>) status=<ok|warn|fail>\nSources:     <list or none>\nVerdict:     <ready|needs action>\n\nNext:\n1. <copy-pasteable command or action>\n2. <copy-pasteable command or action>\n\nRESULT: PASS\n```","schemaVersion":1},"repoUrl":"https://github.com/Kaelio/ktx/tree/main/skills/ktx","tags":["agent","agent-skills","agents","ai-agent","ai-agents","analytics","analytics-engineering","business-intelligence","claude","claude-code","claude-skills","codex"],"stats":{"installVelocity7d":0,"retentionRate":0,"executions":0,"rating":null},"origin":"github","source":{"repo":"ktx","audit":{"files":["package.json","pnpm-lock.yaml","pyproject.toml","uv.lock"],"binaries":[],"findings":[],"packages":0,"auditedAt":"2026-09-25T12:51:46.554Z","lockfiles":["pnpm-lock.yaml","uv.lock"]},"forks":107,"owner":"Kaelio","stars":1601,"topics":["agent","agent-skills","agents","ai-agent","ai-agents","analytics","analytics-engineering","business-intelligence","claude","claude-code","claude-skills","codex","context-layer","data-analysis","data-engineering","llm","mcp","memory","semantic-layer","skills"],"license":"Apache-2.0","fullName":"Kaelio/ktx","homepage":"https://docs.kaelio.com/ktx","language":"TypeScript","pushedAt":"2026-09-11T04:03:45Z","avatarUrl":"https://avatars.githubusercontent.com/u/189464497?v=4","crawledAt":"2026-09-25T12:51:44.696Z","openIssues":53,"manifestFile":"SKILL.md","manifestPath":"skills/ktx/SKILL.md","defaultBranch":"main"},"readme":"# ktx\n\nInstall and configure **ktx**, the open-source context layer for data agents.\nUse this skill when a user wants an agent to add **ktx** to a project, connect\ndata sources, build initial context, install agent integration, or troubleshoot\na local **ktx** setup.\n\n## Operating rules\n\n- Act autonomously when the user asks you to install or configure **ktx**.\n  The non-interactive scripted flow below is the canonical path — bare\n  `ktx setup` is interactive (clack prompts) and an agent cannot drive it.\n- Setup's non-interactive flags are intentionally hidden from `--help`. Use the\n  flags listed below; verify uncommon flags against the docs at\n  `https://docs.kaelio.com/ktx/` or this skill — not against `--help` output.\n- Ask only for values you cannot infer: project directory, connection targets,\n  credentials, account identifiers, and source selections.\n- Prefer `file:/abs/path` secret refs over `env:VAR_NAME`. `env:` refs are\n  re-resolved against the process environment on **every** `ktx` run, so a var\n  exported only in the setup shell is gone when `ktx ingest` or `ktx mcp start`\n  runs later — the secret silently resolves to empty and the connection fails.\n  `file:` refs read from disk and survive across shells. The same caveat\n  applies to `--*-api-key-env` flags: the named var must be present in every\n  shell that runs `ktx`, including the `ktx mcp` daemon's environment.\n- A literal database URL is safe to pass — `ktx setup` auto-externalizes it\n  into `.ktx/secrets/<id>-url` and rewrites `ktx.yaml` to a `file:` ref (see\n  workflow step 2). Source credential refs are **not** auto-externalized: write\n  the secret to a file under `.ktx/secrets/` (`chmod 600`) and pass a `file:`\n  ref. Never ask the user to paste a secret when a `file:` or `env:` ref works.\n- Do not commit `.ktx/secrets/*`.\n- Print each command you run and its result.\n- Setup and ingest can run for many minutes (LLM-heavy source ingests take the\n  longest), and from the outside a slow step looks identical to a stuck one.\n  Don't go silent: say what's about to run and that it may take a while, then\n  post brief progress/liveness updates while it runs (see step 4) so the user\n  never has to wonder whether it stalled — otherwise they may kill it mid-run.\n- If a command fails, identify the cause and change something before retrying.\n\n## Gather inputs once\n\nBefore invoking `ktx setup`, collect in one round:\n\n1. Project directory (default: current working directory).\n2. LLM backend and key strategy. In `--no-input` mode the CLI defaults to\n   `anthropic` and **requires an API key**. When the user is inside Claude\n   Code, pass `--llm-backend claude-code` explicitly; otherwise pass\n   `--llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY`.\n3. Embedding backend (`sentence-transformers` is the local default and needs\n   no key; use `openai` only if the user already has a key, then pass\n   `--embedding-api-key-env OPENAI_API_KEY`).\n4. Database: driver, connection id, URL (or `env:` / `file:` ref), and one or\n   more schemas.\n5. Optional context sources (dbt, Metabase, Looker, LookML, MetricFlow,\n   Notion). Add each one with a follow-up `ktx setup --source …` run (see\n   [Add context sources](#add-context-sources)); use `--skip-sources` only\n   when the user has none.\n\nDo not discover these inputs across multiple setup runs.\n\n## Install workflow\n\n1. **Detect the install path.** If the working directory contains\n   `packages/cli/dist/bin.js` or `pnpm-workspace.yaml` referencing\n   `@kaelio/ktx` you are inside the **ktx** monorepo — build and link the\n   local CLI with `pnpm` and do **not** run `npm install -g`. Otherwise:\n\n   ```bash\n   node --version    # require >= 22; stop and ask the user if older\n   ktx --version || npm install -g @kaelio/ktx\n   ```\n\n2. **Run scripted setup** (canonical path):\n\n   ```bash\n   ktx setup --no-input --yes \\\n     --project-dir <path> \\\n     --llm-backend claude-code \\\n     --embedding-backend sentence-transformers \\\n  ","createdAt":"2026-09-25T12:51:46.564Z","updatedAt":"2026-09-25T12:51:46.564Z"}],"total":1,"limit":24,"offset":0}