Teaching Claude Code to speak KX: Open-source plugins for q, PyKX, KDB-X, and KDB.AI

Ask a general-purpose coding assistant to write you some q and watch what happens. There’s a good chance it hands you back 2*3+4 and confidently tells you the answer is 10. In q, it’s 14. There is no operator precedence, evaluation runs right to left, and that single fact quietly breaks a startling amount of generated code.

That’s the small version of a bigger problem. The models are genuinely good now at the languages they’ve seen a million times. q is not one of those languages. Neither is the PyKX Column API, or the KDB.AI filter syntax, or the difference between use and \l when you load a KDB-X module. The assistant doesn’t know what it doesn’t know, so it pattern-matches from Python and gets you something that looks right and runs wrong.

So we built a fix and made it open source. KX has released a set of Claude Code plugins that teach the assistant how KX tools actually behave. They live in a public marketplace, the knowledge is plain markdown, and they trigger themselves when you start doing KX work. This post covers what’s in them and how to get set up in about five minutes.

Why AI coding assistants struggle with q, PyKX, KDB-X, and KDB.AI

When you point a coding assistant at KX technology, the failures cluster into a few categories:

Wrong language defaults

The model reaches for Python or SQL habits. It writes % expecting modulo; in q that’s division. It uses = to compare two lists; that’s element-wise, not a structural match. It assumes negative indexing works; it doesn’t.

Plausible-but-wrong API shapes

PyKX, KDB.AI, and the KDB-X AI libraries all have specific call signatures the model has barely seen. It guesses, and the guess compiles into a runtime error or, worse, silently wrong results.

No feedback loop

Even when the model could check its work, it has no way to run a linter over the q it just wrote before handing it to you.

None of these are reasoning failures. They’re knowledge failures. Claude is clever and persistent, it will often run into these issues and find a way around them, but there’s no point in wasting time and tokens every session.

How Claude Code plugins improve KX code generation

A Claude Code plugin packages one or more Skills. A Skill is a folder of markdown that Claude loads automatically when it recognizes a relevant task. You don’t invoke it. You just start writing q, or building a vector table in KDB.AI, and the matching knowledge slides into context.

We shipped four plugins, organized around four products:

• q-knowledge: idiomatic q/kdb+, qSQL, IPC, the right-to-left traps, and a /qlint-snippet command backed by KX qlint.
• pykx-knowledge: the PyKX Column API, IPC connection types, type conversions, and on-disk DB management.
• kdbx-knowledge: the KDB-X module system, the AI libraries including HNSW, BM25, TSS, and DTW, GPU compute, and aimeta annotation authoring and discovery.
• kdbai-knowledge: KDB.AI schema design, hybrid search, time-series similarity, reranking, and the filter API gotchas that catch everyone.

The design principle across all four is the same: put the dangerous, easy-to-get-wrong patterns inline where the model sees them first, and push the deep reference material into files that load only when needed. The model gets the trap warnings every time and the encyclopedia on demand.

That structure buys you three things. The obvious ones are accuracy and efficiency: the model writes correct q the first time instead of round-tripping through errors you have to catch. The less obvious one is tokens. A Skill carries the handful of things most likely to trip the model up and leaves the rest in reference files that load only when needed, so more of the context window stays free for your actual code.

Step 1: Install the KX Skills Marketplace in Claude Code

Everything lives in one public repo, KxSystems/kx-skills, under Apache-2.0. Inside a Claude Code session, register it as a plugin marketplace:

/plugin marketplace add KxSystems/kx-skills

This doesn’t install anything yet. Think of it like adding a package registry: you now have access to browse the catalog, but you still choose what to pull down.

Step 2: Install q, PyKX, KDB-X, and KDB.AI Claude Code plugins

Install all four, or just the ones that match your stack:

/plugin install q-knowledge@kx-skills
/plugin install pykx-knowledge@kx-skills
/plugin install kdbx-knowledge@kx-skills
/plugin install kdbai-knowledge@kx-skills

If you’d rather browse interactively, run /plugin on its own and pick from the Discover tab. To pull updates later, run /plugin marketplace update kx-skills.

The q, pykx, kdbx, and kdbai knowledge skills work immediately after install. No external dependencies, no configuration. They’re pure knowledge, so the moment Claude detects you’re working with one of these tools, the right skill loads.

Step 3: Optional: Enable q Linting in Claude Code

One skill does more than carry knowledge. The qlint-snippet skill inside q-knowledge shells out to KX qlint so Claude can lint q before it ever reaches you. This one needs two things on your machine:

• q on your PATH, or the Q environment variable pointed at the binary.
• QLINT_DIR set to the directory containing KX’s qlint.q_. There is no default; without it the wrapper exits cleanly with a message telling you so.

If you have KX Developer installed, that’s usually all you need:

export QLINT_DIR="$HOME/developer/ws"

Add that to your ~/.bashrc and the wrapper picks it up in every shell. Once it’s set, you can say “lint this q snippet” and Claude runs qlint, reads back the findings, and reports any error-level rows verbatim. The more useful behavior is automatic: when Claude generates q for you, the skill prompts it to validate that code before presenting it. You get linted q by default, not q you have to paste into a linter yourself.

Step 4: Just start working

There’s no step four, really. That’s the point. Open a session, start a KX task, and the skills do their job. Let’s look at what that actually feels like.

Results: Watching the skills earn their keep

Here are a few real patterns the plugins catch. In each case the “before” is what a general assistant tends to produce and the “after” is what you get with the skill loaded.

Example 1: How Claude handles q’s right-to-left evaluation

Ask for a quick calculation and the q skill keeps the evaluation order straight:

In q there's no operator precedence and evaluation runs right to left, so 2*3+4 evaluates as 2*(3+4) = 14, not 10. If you want 10, parenthesize: (2*3)+4.

Small, but this is the single most common way generated q goes quietly wrong.

Example 2: How Claude writes correct PyKX column API filters

Ask to filter a PyKX table for AAPL trades over $150 and the pykx skill writes the operator form, not a string:

table.select(where=(kx.Column('sym') == 'AAPL') & (kx.Column('price') > 150))

The instinct most models have is where='price > 150' or joining conditions with Python’s and. Neither works against Column objects. The skill knows to reach for &, |, and ~ with parentheses around each condition.

Example 3: How Claude formats KDB.AI filters correctly

Building a query against a KDB.AI table, the kdbai skill gets the filter tuple order right:

filter=[("=", "fiscal_year", 2024)]

Everyone, model and human alike, wants to write ("fiscal_year", "=", 2024). It reads more naturally and it’s wrong. Operator comes first. This is exactly the kind of fact that’s invisible until it bites you.

Example 4: How Claude loads KDB-X modules correctly

Ask to load the Parquet module in KDB-X and the kdbx skill uses use, never \l:

.pq:use`kx.pq

Reaching for \l here is the reflex, and it produces an nyi error because \l doesn’t bind the native functions. The skill carries that distinction and the error table that goes with it.

Example 5: How Claude builds CAGRA GPU Indexes in KDB.AI

This is the showpiece, because it’s where generic knowledge fails hardest. Ask the kdbai skill to create a CAGRA GPU index and it knows the one thing the docs make you learn the hard way:

indexes = [
    {"name": "idx", "type": "cagra", "column": "vector",
     "params": {"metric": "CS"}}  # no dims
]

CAGRA infers dimensionality from the data and rejects a dims parameter, the opposite of HNSW and Flat, which require it. The skill also knows CAGRA needs the cuVS Docker image and carries the full cuvsCagraIndexParams and cuvsCagraSearchParams knobs, including graph_degree, itopk_size, and the rest, when you go deeper. That’s the difference between a five-minute setup and an afternoon of reading error messages that just echo a parameter name back at you.

What are the limitations of KX Claude Code plugins?

These plugins are knowledge, not magic. A few honest caveats:

• They make Claude better at KX-specific patterns. They don’t make it an oracle. You still review the code.
• The knowledge reflects the products as of release. APIs move; the skills will need to move with them. That’s exactly why they’re plain markdown in a public repo.
• The qlint-snippet skill is the only one with a setup cost, and it’s optional.
• If you work mostly in one product, install just that plugin. There’s no benefit to loading kdbai-knowledge if you never touch the vector database.

Why skills are different from traditional documentation

The interesting thing about this project isn’t that we taught a model some q syntax. It’s that the knowledge of how to use these tools correctly no longer sits in documentation waiting to be found. It travels with the task. A Skill is a checklist, a set of traps, and a worked example, all in markdown, all version-controlled, all loaded at the exact moment the work calls for it.

That’s a different shape than documentation. Documentation waits for you to come find it. A Skill shows up when you need it and stays quiet when you don’t.

The repo is open source, and we want it to grow. If you work with these tools and you know a better pattern, a missing checklist item, or a common mistake we haven’t documented yet, open an issue or a pull request. The skills are plain markdown; improving them takes no code, just the hard-won knowledge you already have in your head.

Get started with the open-source KX Skills Marketplace

Ready to stop debugging AI-generated KX code? Install the KX Skills marketplace and give Claude the product knowledge it needs to generate accurate q, PyKX, KDB-X, and KDB.AI code from the start. Explore the KX Skills Marketplace on GitHub

If you have feedback please let us know on GitHub or in our Slack community.