SkillAgentSearch skills...

ktx

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

Install / Use

npx skills add Kaelio/ktx --skill ktx

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

92/100

Supported Platforms

Universal

Our assessment of ktx

ktx scores 92/100 on our quality scale, 289th of 947 AI & Machine Learning skills we index (top 31%).

Its SKILL.md is 12 KB long, well organised into 13 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

With 1,601 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so ktx is actively maintained.
  • Our last check on 2026-10-27 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

ktx compared with similar skills

All 4 of these similar skills score higher than ktx; compare them before choosing.

SkillScoreStarsUpdatedFormat
ktx (this skill)by Kaelio921.6k2mo agoSKILL.md
claude-memby thedotmack100117.6ktodayCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
CowAgentby zhayujie10048.0ktodayCLAUDE.md

Frequently asked questions

How do I install ktx?
Run npx skills add Kaelio/ktx --skill ktx. The install tabs above show the steps for each supported agent.
Which AI agents does ktx work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is ktx safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is ktx still maintained?
The repository was last updated about 2 months ago, so ktx is actively maintained.

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.

ktx

Install and configure ktx, the open-source context layer for data agents. Use this skill when a user wants an agent to add ktx to a project, connect data sources, build initial context, install agent integration, or troubleshoot a local ktx setup.

Operating rules

  • Act autonomously when the user asks you to install or configure ktx. The non-interactive scripted flow below is the canonical path — bare ktx setup is interactive (clack prompts) and an agent cannot drive it.
  • Setup's non-interactive flags are intentionally hidden from --help. Use the flags listed below; verify uncommon flags against the docs at https://docs.kaelio.com/ktx/ or this skill — not against --help output.
  • Ask only for values you cannot infer: project directory, connection targets, credentials, account identifiers, and source selections.
  • Prefer file:/abs/path secret refs over env:VAR_NAME. env: refs are re-resolved against the process environment on every ktx run, so a var exported only in the setup shell is gone when ktx ingest or ktx mcp start runs later — the secret silently resolves to empty and the connection fails. file: refs read from disk and survive across shells. The same caveat applies to --*-api-key-env flags: the named var must be present in every shell that runs ktx, including the ktx mcp daemon's environment.
  • A literal database URL is safe to pass — ktx setup auto-externalizes it into .ktx/secrets/<id>-url and rewrites ktx.yaml to a file: ref (see workflow step 2). Source credential refs are not auto-externalized: write the secret to a file under .ktx/secrets/ (chmod 600) and pass a file: ref. Never ask the user to paste a secret when a file: or env: ref works.
  • Do not commit .ktx/secrets/*.
  • Print each command you run and its result.
  • Setup and ingest can run for many minutes (LLM-heavy source ingests take the longest), and from the outside a slow step looks identical to a stuck one. Don't go silent: say what's about to run and that it may take a while, then post brief progress/liveness updates while it runs (see step 4) so the user never has to wonder whether it stalled — otherwise they may kill it mid-run.
  • If a command fails, identify the cause and change something before retrying.

Gather inputs once

Before invoking ktx setup, collect in one round:

  1. Project directory (default: current working directory).
  2. LLM backend and key strategy. In --no-input mode the CLI defaults to anthropic and requires an API key. When the user is inside Claude Code, pass --llm-backend claude-code explicitly; otherwise pass --llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY.
  3. Embedding backend (sentence-transformers is the local default and needs no key; use openai only if the user already has a key, then pass --embedding-api-key-env OPENAI_API_KEY).
  4. Database: driver, connection id, URL (or env: / file: ref), and one or more schemas.
  5. Optional context sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Add each one with a follow-up ktx setup --source … run (see Add context sources); use --skip-sources only when the user has none.

Do not discover these inputs across multiple setup runs.

Install workflow

  1. Detect the install path. If the working directory contains packages/cli/dist/bin.js or pnpm-workspace.yaml referencing @kaelio/ktx you are inside the ktx monorepo — build and link the local CLI with pnpm and do not run npm install -g. Otherwise:

    node --version    # require >= 22; stop and ask the user if older
    ktx --version || npm install -g @kaelio/ktx
    
  2. Run scripted setup (canonical path):

    ktx setup --no-input --yes \
      --project-dir <path> \
      --llm-backend claude-code \
      --embedding-backend sentence-transformers \
      --database <driver> --database-connection-id <id> \
      --database-url '<raw-url | file:/abs/path>' \
      --database-schema <schema> \
      --skip-sources \
      --skip-agents
    
    • --database-schema is required for scope-bearing drivers (Postgres, MySQL, ClickHouse, SQL Server, BigQuery, Snowflake) in --no-input: setup fails fast without it unless the connection already has scope in ktx.yaml. SQLite needs no scope.
    • Configure one new database connection per setup invocation. For multiple connections, rerun setup once per connection.
    • Pasting a literal --database-url is safe: the CLI relocates the URL into .ktx/secrets/<connection-id>-url and rewrites ktx.yaml to a file: ref automatically.
    • ktx setup runs agent integration as its last step. In --no-input mode with neither --target nor --skip-agents, that step has no input, prints Run in a TTY, or pass --target <target>., and the command exits non-zero even though every database/LLM/embedding step succeeded. Pass --skip-agents to defer agents to step 5 (as above), or --target <agent> to install them inline and exit 0. Judge data-layer success from ktx status, not from this exit code.
  3. Resumability and --skip-*. Re-running ktx setup against an existing project resumes its config. Use --skip-llm, --skip-databases, --skip-sources, or --skip-embeddings to leave a slice unconfigured but let the rest complete instead of aborting on the first failure. When resuming an existing project to change one slice (e.g. only LLM), still pass the database flags from the previous run — setup validates current flags, not persisted ktx.yaml state.

  4. Build context if setup did not already complete one:

    ktx ingest <connection-id> --no-input
    

    ktx ingest always builds enriched context and requires a configured model and embeddings (set during setup); a database connection without them fails with an enrichment-readiness error. Note: ktx ingest rejects --yes together with --no-input (Choose only one runtime install mode); ktx setup accepts both. Use --no-input only for ingest.

    Ingest one connection at a time. It can run for many minutes with no stdout until it exits (LLM-heavy sources like Metabase are the slowest), so don't assume it hung, and don't pipe it through tail/head — that buffers all output to the end, so run it raw. Tell the user up front that the step is slow, then keep them posted instead of blocking silently: run the ingest in the background and poll for liveness every minute or so, reporting a one-line update each time (which connection, roughly how long it's been running, and that .ktx files are still changing) so a long run never looks stuck:

    find <path>/.ktx/worktrees <path>/.ktx/ingest-transcripts -type f -mmin -3
    

    On success, the Ingest finished summary table shows done in the Source ingest and Memory update columns with no Failed sources: section.

  5. Install agent integration:

    ktx setup --agents --target <claude-code|claude-desktop|codex|cursor|opencode|universal>
    ktx mcp start --project-dir <path>
    

    Agent integration is not usable until ktx mcp start is running. The --agents step prints this requirement as Required before using agents.

  6. Fall back to bare ktx setup only when a human is at the keyboard — it uses interactive prompts an agent cannot answer.

Add context sources

Context sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) are added one at a time — --source is not repeatable, so run ktx setup once per source. Source setup is resumable against an existing project: pass --skip-databases --skip-llm --skip-embeddings --skip-agents so only the source is configured (the trailing agent step otherwise fails the run — see install step 2). Map Metabase, Looker, and LookML to an existing database connection with --source-warehouse-connection-id <db-connection-id> (required for those). dbt ignores --source-warehouse-connection-id — it maps to the warehouse by table name — so omit it for dbt. Use file:/abs/path refs for keys and tokens (see the secrets rule above); env: refs must be exported in every later ktx shell.

# dbt — pick exactly one of --source-path (local) or --source-git-url (remote).
# No --source-warehouse-connection-id: dbt maps to the warehouse by table name.
ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \
  --source dbt --source-connection-id <id> \
  --source-git-url <url> --source-branch <branch>

# Metabase
ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \
  --source metabase --source-connection-id <id> \
  --source-url <url> --source-api-key-ref file:/abs/path/metabase-api-key \
  --source-warehouse-connection-id <db-connection-id> \
  --metabase-database-id <metabase-db-id>

# Notion
ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings --skip-agents \
  --source notion --source-connection-id <id> \
  --source-auth-token-ref file:/abs/path/notion-token \
  --notion-crawl-mode selected_roots --notion-root-page-id <page-id>

Notes:

  • --metabase-database-id is the numeric id of the warehouse inside Metabase (not the ktx connection id). Discover it from the Metabase API (GET /api/database) or UI if the user doesn't know it.
  • --notion-crawl-mode selected_roots requires at least one --notion-root-page-id (repeatable); use all_accessible to crawl everything the token can see.
  • After adding sources, ingest each new connection so its context is queryable: ktx ingest <source-connection-id> --no-input.

Files to inspect

  • ktx.yaml: project configuration.
  • .ktx/secrets/*: local secret files. Never commit them.
  • semantic-layer/<connection-id>/*.yaml: semantic sources for SQL compilation.
  • wiki/**/*.md: project context pages for agents.
  • .claude/skills/ktx/, .agents/skills/ktx/, .cursor/rules/ktx.mdc, and .opencode/commands/ktx.md: generated agent integration files.

Verification

After setup, run:

ktx connection test <connection-id>
ktx status --json --no-input
ktx sl --output plain          # lists compiled semantic sources; `ktx sl` has no --no-input

Judge readiness from ktx status --json fields, not the exit code. ktx status exits 1 whenever the LLM is none (verdict: "blocked"), even when embeddings and every database connection are healthy. Treat success as:

  • verdict: "ready" at the top of the JSON, and
  • every connections[].status === "ok" (other levels: warn, fail, skipped), and
  • every ktx connection test <id> exited 0, and
  • for each ingested source, localStats.semanticLayer[].sourceCount > 0 and localStats.wikiPages[].count > 0 — these confirm the source actually produced context. Do not rely on localStats.ingest.perConnection to confirm source ingests: it reflects only completed warehouse ingest reports and under-reports (often lists just the warehouse connection).

If the LLM is intentionally left unconfigured, verdict is blocked and the exit is non-zero by design — that is still a usable context layer, so report it as "ready, LLM optional" and judge the data layer by the connection and localStats fields above rather than retrying setup.

Troubleshooting

For

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.6k
CategoryAI
Updated2mo ago
Forks107

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions