# Setup Qlty Toml

> Configure and fine-tune qlty.toml for static analysis using the Qlty CLI and Qlty Cloud. Use this skill when a user wants to set up Qlty for the first time, improve an existing qlty.toml configuration, choose which linters and security scanners to enable, configure plugin modes (block/comment/monitor), set code smell thresholds, or tune exclude patterns. Handles single repos and monorepos. Supports all Qlty-supported languages: JavaScript, TypeScript, Python, Ruby, Go, Java, Kotlin, PHP, Rust, Swift, Shell, CSS, SQL, Terraform, Docker, and more. Do NOT use for code coverage setup (use setup-coverage instead), writing or running tests, or general CI/CD changes unrelated to Qlty analysis.

- Skill: `qltysh/setup-qlty-toml` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add qltysh/setup-qlty-toml`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qltysh/setup-qlty-toml/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: qltysh (https://skillmd.com/u/qltysh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qltysh/setup-qlty-toml

---


# Set Up qlty.toml

You are a senior software engineer configuring Qlty static analysis for this repository. Work through these phases in order.

**Scope constraint:** This skill only creates or modifies files inside `.qlty/`. Never touch anything else in the repository — no source files, no existing tool configs, no CI workflows, nothing outside `.qlty/`. Files generated by `qlty init` itself (e.g. `.qlty/.gitignore`) are acceptable.

When configuring plugins, apply this decision tree — never copy or modify files outside `.qlty/`:
- **Plugin config exists in the repo at a non-standard path** → use `config_files` to point to it in place
- **Plugin requires extra packages** (parsers, plugins, extensions) → use `extra_packages`
- **No config exists anywhere in the repo** → create one in `.qlty/configs/` and reference it via `config_files`
- **Plugin cannot be configured without touching files outside `.qlty/`** → comment it out with a note explaining what the user would need to do manually

For all plugin configuration options (`config_files`, `extra_packages`, `prefix`, `drivers`, `version`, `affects_cache`, etc.): https://docs.qlty.sh/cli/linter-extensions

---

## Phase 1: Analyze the Repository

**Check Qlty state — this determines your mode for the entire run:**

- **No `.qlty/qlty.toml`** → run `qlty init` to generate the baseline. Plugin selection is `qlty init`'s job — do not second-guess which plugins it enables. Your job is to fine-tune the generated config (Phases 2–4).
- **Existing `.qlty/qlty.toml`** → read it carefully. You are refining, not replacing. After fine-tuning, scan for plugins that are clearly absent but strongly signaled by the repo (e.g. a tool config file with no matching plugin block). Surface at most 2–3 recommendations in the PR description — do not add them automatically.

**Catalog the repo:**
- Languages, file types, and primary tooling — scan for linter/formatter configs and identify which tools the team already uses
- Existing tool configs to read — note extensions, parsers, or plugins in use; these inform `extra_packages`
- Generated, vendored, and minified directories — check `.gitignore` for hints. See https://docs.qlty.sh/cli/excluding-files.md
- Multiple language manifests in subdirectories → monorepo
- CI config: note whether `qlty check` is already in `.github/workflows/`

Produce a brief summary of findings before moving on.

---

## Phase 2: Fetch Documentation

Fetch only what you need — do not read everything upfront.

**Primary source of truth — the Qlty plugins repo:**
`https://github.com/qltysh/qlty/tree/main/qlty-plugins/plugins`

Each individual linter lives under `linters/{plugin-name}/`. Fetch these two files for every plugin you're enabling:

1. **`plugin.toml`**: `https://raw.githubusercontent.com/qltysh/qlty/main/qlty-plugins/plugins/linters/{plugin-name}/plugin.toml`
   Ground truth for Qlty integration: known good version, valid driver values, auto-detected config files, required packages, cache invalidation files.

2. **`README.md`**: `https://raw.githubusercontent.com/qltysh/qlty/main/qlty-plugins/plugins/linters/{plugin-name}/README.md`
   How the plugin behaves in Qlty: known issues, version notes, usage examples, caveats.

**Secondary sources — fetch only when needed:**

3. **Plugin source repo README**: upstream URL is in `plugin.toml` (`homepage` field). Fetch when you need to understand the tool's own config format, available rules, parsers, or extensions.

4. **qlty.toml field reference**: https://docs.qlty.sh/cli/qlty-toml.md

---

## Phase 3: Fine-Tuning

Before writing the config, use the `AskUserQuestion` tool to present all tunable decisions as interactive buttons in a single call (up to 4 questions). Populate plugin names from Phase 1 findings. Always put the recommended option first with "(Recommended)" in the label.

**If running autonomously** (eval or non-interactive): skip the prompt and apply all defaults.

Questions to ask:

1. **Security scanners** (`{trivy, osv-scanner, trufflehog, …}`)
   - Block — fails the Quality Gate (Recommended)
   - Comment — posts a review comment, non-blocking
   - Monitor — visible on Qlty Cloud only

2. **Language linters** (`{eslint, golangci-lint, rubocop, …}`)
   - Comment — review feedback, non-blocking (Recommended)
   - Block — fails the Quality Gate
   - Monitor — visible on Qlty Cloud only

3. **Code smells & complexity** — see https://docs.qlty.sh/code-smells.md and https://docs.qlty.sh/complexity.md
   - Enable in comment mode (Recommended)
   - Enable in monitor mode
   - Disable

4. **Complexity thresholds**
   - Default (Recommended)
   - Strict — tighten thresholds ~30%
   - Relaxed — loosen thresholds ~30%

Add to each question description: "You can always fine-tune these later by updating qlty.toml."

Apply choices (or defaults if dismissed) and proceed to Phase 4 — no further confirmation.

**Always apply autonomously (not in the prompt):**
- Formatters: always `comment`
- Extra packages and config files: follow the decision tree at the top — see https://docs.qlty.sh/cli/linter-extensions
- Exclude patterns: see https://docs.qlty.sh/cli/excluding-files.md
- Test patterns: see https://docs.qlty.sh/cli/qlty-toml.md
- Triage rules: skip on first run unless a plugin is clearly too noisy — see https://docs.qlty.sh/cli/qlty-toml.md

---

## Phase 4: Implement and Open PR

### 1. Write `.qlty/qlty.toml`

Full field reference: https://docs.qlty.sh/cli/qlty-toml.md

**CRITICAL — these all cause "Build errored":**
- Do NOT include `[cli]` or `[settings]` sections from `qlty init` output
- Do NOT use the old `[[sources.community]]` format — use `[[source]] name = "default" default = true`
- Do NOT use the old `[plugins.enabled]` / `[[plugins.enabled]]` format — use `[[plugin]]` blocks
- Do NOT nest `exclude_patterns` as a section — it must be a top-level array
- The `[[source]]` block is required — without it Qlty cannot resolve plugins. Do NOT set `directory` to a URL

### 2. Verify locally

```bash
qlty check --sample
```

Catches runtime crashes that TOML syntax validation misses. For each plugin that errors: read the debug `.yaml` Qlty prints, check https://docs.qlty.sh/cli/debugging, attempt a fix. If not fixable, comment out the `[[plugin]]` block with a one-line explanation. **Do not open the PR while any plugin is erroring** — one erroring plugin causes "Build errored" for the entire cloud build.

### 3. Open PR

- Branch: `qlty-setup`
- Commit only files inside `.qlty/`
- PR description: every plugin enabled with its mode, any plugins disabled during verification and why, any manual steps needed

### 4. Print a configuration rundown

```
Plugins enabled: N
  BLOCK   {plugin} — {what it covers}
  COMMENT {plugin} — {what it covers}
  MONITOR {plugin} — {what it covers}

Smells: {enabled/disabled}, {mode}, {any non-default thresholds}

Skipped or commented out: N
  {plugin} — {reason; what the user would need to do to enable it}

Plugin configs created in .qlty/configs/: N
  {file} — used by {plugin}
```

---

## Phase 5: Qlty Cloud Guidance

Tell the user what to verify in Qlty Cloud (requires the web UI, not qlty.toml):

1. **Project visible**: `https://qlty.sh/gh/<org>` — confirm the repo is listed; if not, install the Qlty GitHub App
2. **Quality Gate**: `https://qlty.sh/gh/<org>/projects/<repo>/settings/review` — confirm block-mode plugins fail the gate
3. **After merging**: first full analysis runs automatically; results at `https://qlty.sh/gh/<org>/projects/<repo>`
4. **Follow-up**: review monitor-mode findings, promote useful ones to comment/block; add `qlty check` to CI if not already there
5. **Inline silencing**: for specific false positives use `qlty-ignore` comments — see https://docs.qlty.sh/cli/silencing-issues.md