setup-qlty-toml

name	setup-qlty-toml
description	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.
metadata	{"stage":"production"}

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

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