From qlty-skills
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.
npx claudepluginhub qltysh/qlty-skills --plugin qlty-skillsThis skill uses the workspace's default tool permissions.
You are a senior software engineer configuring Qlty static analysis for this repository. Work through these phases in order.
Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.
Guides root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Writes implementation plans from specs for multi-step tasks, mapping files and breaking into TDD bite-sized steps before coding.
You are a senior software engineer configuring Qlty static analysis for this repository. Work through these phases in order.
Check Qlty state — this determines your mode for the entire run:
.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)..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 .golangci.yml with no golangci-lint block). Surface at most 2–3 recommendations in the PR description — do not add them automatically.Catalog the repo:
.rubocop.yml, pyproject.toml, .eslintrc*, biome.json, .golangci.yml, etc.). For each tool config found, locate its Qlty plugin via the registry at https://github.com/qltysh/qlty/tree/main/qlty-plugins/plugins — each plugin's plugin.toml lists the config files it recognizesextra_packagesvendor/, node_modules/, dist/, build/, target/, generated/, minified files, .d.ts files. Also check .gitignoreqlty check is already in .github/workflows/Produce a brief summary of findings before moving on.
Fetch only what you need — do not read everything upfront.
Plugin availability (always): https://github.com/qltysh/qlty/tree/main/qlty-plugins/plugins — each subdirectory is a valid plugin name. Do not add a plugin not listed here.
Per-plugin README (fetch for each plugin you're about to enable):
https://raw.githubusercontent.com/qltysh/qlty/main/qlty-plugins/plugins/{plugin-name}/README.md
This is the authoritative source for extra_packages, config_files, valid field values, version constraints, and config format requirements.
qlty.toml field reference (fetch only if you encounter an unfamiliar field):
Qlty-internal behavioral caveats (always read — it's small): references/plugin-registry.md
Captures non-obvious Qlty behaviors not in plugin READMEs: config file handling, cache quirks, cloud vs. local differences, plugins with known issues in the current CLI.
Before writing the config, send the user one compact prompt with all tunable decisions. Present fixed options and a clear default for each. Do not explain each option at length — the options speak for themselves.
If running autonomously (eval or non-interactive context): skip the prompt entirely and apply all defaults.
Populate the plugin names from Phase 1 findings, then send this as a single message:
Here are the key configuration choices for this repo. Reply with any changes or just say "all defaults" to proceed.
You can always fine-tune any of these later by updating qlty.toml.
Security scanners ({e.g. trivy, osv-scanner, trufflehog}):
block (recommended) / comment / monitor
Language linters ({e.g. eslint, golangci-lint, rubocop}):
comment (recommended) / block / monitor
Code smells & complexity:
enable in comment mode (recommended) / enable in monitor mode / disable
Complexity thresholds:
default (recommended) / strict / relaxed
Monorepo scoping (different language stacks per subdirectory):
yes / no (recommended)
Apply the user's choices (or defaults) and proceed directly to Phase 4 — no further confirmation needed.
prefix to scope plugins to subdirectories with different language stacks; same-language workspaces do not need itcommentpackage.json devDependencies where possible; use extra_packages (not package_filters) for scoped npm packages (@scope/pkg)**/config/**.qlty/qlty.tomlCRITICAL — these all cause "Build errored":
[cli] or [settings] sections from qlty init output[[sources.community]] format — use [[source]] name = "default" default = true[plugins.enabled] / [[plugins.enabled]] format — use [[plugin]] blocksexclude_patterns as a section — it must be a top-level array[[source]] block is required — without it Qlty cannot resolve plugins. Do NOT set directory to a URLField reference: https://docs.qlty.sh/qlty-toml
qlty check --sample
Catches runtime crashes that TOML syntax validation misses. For each plugin that errors: read the debug .yaml Qlty prints, check https://qlty.sh/d/lint-error, attempt a fix. If not fixable, comment out the [[plugin]] block with a one-line explanation above it. Do not open the PR while any plugin is erroring — one erroring plugin causes "Build errored" for the entire cloud build.
qlty-setupextra_packages and why, any plugins disabled during verification and why, any manual steps neededreferences/plugin-registry.md if you learned something newIf a plugin is missing from the public registry, causes a build error, or has a caveat not already recorded, add it inline — do not wait for a separate evolve run.
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}
Disabled during verification: {plugin} — {reason}
Tell the user what to verify in Qlty Cloud (requires the web UI, not qlty.toml):
https://qlty.sh/gh/<org> — confirm the repo is listed; if not, install the Qlty GitHub Apphttps://qlty.sh/gh/<org>/projects/<repo>/settings/review — confirm block-mode plugins are set to fail the gatehttps://qlty.sh/gh/<org>/projects/<repo>qlty check to CI if not already thereqlty-ignore comments (see https://docs.qlty.sh) rather than broadening global config