# Qlint Snippet

> Lint a single q/qSQL code snippet using KX qlint. Reads code from stdin or argument and prints the raw lint table. Use when the user says "qlint this snippet", "lint this q code", "check syntax of <code>", "qlint snippet", or wants quick lint feedback on a piece of q code. Also trigger whenever Claude has just generated q code and should validate it before presenting to the user.

- **Type:** Skill
- **Install:** `agentstack add skill-kxsystems-kx-skills-qlint-snippet`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KxSystems](https://agentstack.voostack.com/s/kxsystems)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [KxSystems](https://github.com/KxSystems)
- **Source:** https://github.com/KxSystems/kx-skills/tree/main/plugins/q-knowledge/skills/qlint-snippet

## Install

```sh
agentstack add skill-kxsystems-kx-skills-qlint-snippet
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# qlint-snippet

Run KX qlint on a single q/qSQL code snippet via the `scripts/run.sh` script bundled with this skill (sibling `scripts/` directory next to this SKILL.md). Useful for:

- ad-hoc syntax checks on a code block pasted into the chat
- Claude auto-validating q code it just generated before presenting it to the user

## Prerequisites

`QLINT_DIR` must point to the directory containing KX's `qlint.q_` — there is no default; the wrapper exits with code 2 and a clear stderr message if it is unset or the file is missing. `q` is expected on `PATH`; override with the `Q` env var if not. If you don't have KX Developer installed, see this plugin's [README](../../README.md) for the recommended setup.

**If `QLINT_DIR` is unset or `qlint.q_` is missing (exit 2), ASK THE USER for the correct path.** Do **not** run `find /` or other filesystem-wide searches to locate it unless the user explicitly requests — they are slow and the user already knows where it lives. A narrow check in obvious places (e.g. `~/.kx`, the plugin's own directory) is fine as a one-shot, but anything broader should be a question.

## Gather parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `CODE` | required | The q snippet to lint. Take it from the user's message (fenced block, inline quote, or explicit `myCode` variable). Strip any markdown fences before passing. |

## Execute

Invoke the `scripts/run.sh` script bundled with this skill (under the `scripts/` directory sibling to this SKILL.md). Pass the snippet via argument **or** stdin. **Stdin (heredoc) is strongly preferred for multi-line code** — see the gotcha below.

```bash
# Stdin form (preferred for multi-line — quoted heredoc disables all expansion)
scripts/run.sh 
EOF

# Argument form (one-liner, single-line code)
scripts/run.sh ''
```

Use the absolute path to `scripts/run.sh` (resolved from the skill's own directory) so it works regardless of the caller's current working directory.

### Multi-line via argument — pick one of these three

**❌ Do NOT write `'… \n …'`.** In bash single quotes, `\n` is literally two characters (`\` + `n`), NOT a newline. The wrapper will pass `\n` to q, q's parser sees a bare `\` (its system-command prefix), and you get `CANNOT_PARSE error: "\\"`.

If you must use the argument form on multi-line code, choose **one** of:

| Form | Example | Note |
|------|---------|------|
| Real newline inside `'…'` | `'getTrades:{…};` (Enter) `getTrades[…]'` | Single quotes preserve literal newlines fine |
| ANSI-C quoting `$'…'` | `$'getTrades:{…};\n getTrades[…]'` | `$` goes **before** the opening quote; `\n` is then interpreted |
| Heredoc | see Stdin form above | Cleanest — no escaping at all |

Default to heredoc unless the snippet is genuinely one line.

## Output

The wrapper prints the full `.qlint.lintItem` table (one row per finding) to stdout. Each row has:

| Field | Meaning |
|-------|---------|
| `label` | Rule name, e.g. `DECLARED_AFTER_USE`, `UNDECLARED_VAR`, `UNUSED_VAR` |
| `errorClass` | ``` `error ```, ``` `warning ```, or ``` `note ``` |
| `description` | One-line human description of the rule |
| `problemText` | The token / variable / expression that triggered it |
| `errorMessage` / `startLine` / `startCol` / `endLine` / `endCol` | Position info |

Exit codes:

| Code | Meaning |
|------|---------|
| `0` | No `errorClass=`error` rows. Snippet is acceptable. Warnings may still be present. |
| `1` | At least one error-level row. Snippet has a real qlint failure. |
| `2` | Environment misconfig (missing `qlint.q_` or missing `q` binary). **Ask the user for the path; don't filesystem-search unless they explicitly request.** |

After running, report to the user: (a) any error-level rows verbatim, (b) a one-line summary of warnings, (c) the exit code.

## Notes

- The wrapper shows every finding raw — no policy filtering. If you want to suppress specific rules (e.g. `UNINDENTED_CODE`, or `DECLARED_AFTER_USE` against known schema names), filter the output yourself.
- The wrapper writes the snippet to a temp file and loads it inside q via ``"\n" sv read0 `:``, so the user's code never has to be bash-escaped. Only the temp file path is interpolated.
- `q` is found via the `Q` env var (default: `q` on PATH). The wrapper does **not** set `QHOME`/`QLIC` — if your environment needs them set, do so before invoking.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [KxSystems](https://github.com/KxSystems)
- **Source:** [KxSystems/kx-skills](https://github.com/KxSystems/kx-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kxsystems-kx-skills-qlint-snippet
- Seller: https://agentstack.voostack.com/s/kxsystems
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.