lint

Lint

Deterministic hygiene, run before any model-based review. The linters answer questions that have exact answers — unused name, unreachable branch, uninitialised read, malformed table, misspelt word, unformatted file — so no reviewer attention should be spent on them, and no reviewer's opinion is needed to settle them.

This skill exists because LLM reviewers are measurably bad at this class. Across five supervised runs of one plan, 11 of ~14 non-code-correctness findings were mechanical, and both commissioned reviewers missed every one of them while correctly finding subtle semantic defects. Lint is the cheap deterministic floor under review, not a replacement for it.

The one rule that makes this usable: differential by default

A gate that demands absolute cleanliness fails on arrival in any real repository, because pre-existing findings are not the current change's fault and fixing them is usually unauthorized scope.

So the default question is not "is this code clean?" but:

Does this change introduce a finding that was not there before?

check --base <ref> lints the changed files at the current head, lints the same files at <ref> in a throwaway worktree, and reports only the difference. Pre-existing debt cannot block; a newly added unused import cannot pass.

Use --all for absolute mode when you genuinely want every finding — a standalone audit, or a repo you are cleaning up.

Invariants

These are load-bearing. Do not work around them.

1. check never installs anything. Installing mutates the machine. install is a separate, explicit, human-run subcommand, dry-run unless --yes is passed. An agent that finds a tool missing reports it and lets the human decide — it never runs install --yes on its own initiative, in any mode. check and detect name the missing binaries and print the install command so the human knows exactly what is needed.
2. A missing linter is unavailable coverage, never a pass. The report names every language present with no tool available. --require-coverage turns that into exit 3 so an automated caller cannot mistake absence of findings for absence of problems.
3. A failed run is an error, not a pass. A linter that exits unexpectedly with nothing parseable did not lint anything — an invalid ruff config exits 2 with empty output, which must never read as "0 findings". The same applies at the base ref, where a failure would make every pre-existing finding look new.
4. Defects, not taste. The tool set is deliberately limited to findings with an objective answer. It carries no complexity metric, no naming opinion, and no architectural rule. A project's own conventions win: the linters read the project's own config files first, and config/ruff.toml and config/markdownlint.jsonc supply defect-focused defaults only when the project has none. Both exist because the tools' own defaults are broader than this rule allows — ruff's default set flags import ordering and rewrites config = dict(...) to a literal, which on one calibration repo was the documented convention of the project being linted. Shellcheck is capped at --severity=info for the same reason, dropping only its presentational style tier; a project's .shellcheckrc still selects which rules apply and shellcheck honours it regardless of that flag. If a plan mandates something a generic rule would flag, the plan is right and the rule must be skipped (--skip <tool>).
5. Nothing is mutated. No --fix, no reformat-in-place. This skill reports; the Developer edits. (External tools may still write their own caches.)
6. The comparison is a good heuristic, not an oracle. Signatures are line-insensitive, so a change that removes one finding and adds an equivalent one elsewhere in the same file nets out and is not reported. Tools that emit one finding per file — the formatters — cannot show a second regression in a file already unformatted at base. Absolute mode (--all) is the escape hatch when you need the whole picture.