agentleFS
zerniezernie/vigiles/.claude/skills/add-a-linter/SKILL.md

add-a-linter

Skill15 starsChanged 5 months agoMITView on GitHub

Add a new linter to vigiles's cross-referencing engine as one cohesive, type-enforced unit — a LinterAdapter in the LINTERS registry, with the conformance test enforcing docs + site parity so no site is forgotten

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add a linter to vigiles's cross-referencing engine (the enforce("eslint/...") moat).

    line 8
  2. Very specific:

    Name it (the single source): Add the lowercase name to BUILTIN_LINTERS in src/core/spec.ts.

    line 33
  3. Very specific:

    Run npm test (or at least npx vitest run src/core/linter-contract.test.ts src/core/linters.test.ts + tsc --noEmit).

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add a linter to vigiles's cross-referencing engine (the enforce("eslint/...") moat). This is a contributor task, not a third-party extension point: the LINTERS registry is a Record<BuiltinLinter, LinterAdapter> — a closed set baked into core — so a linter is added by editing vigiles itself, and the type system + the conformance test make the parity un-forgettable.

The whole reason this skill exists: a linter used to be smeared across ~7 scattered sites (existence check, config checker, CLI-tool map, suggestion enumerator, generate-types discoverer, docs, site) with nothing enforcing that you touched all of them — miss one and it failed silently. Now tsc fails if the registry entry is missing, and src/core/linter-contract.test.ts fails if the docs table or the marketing site drifts. Follow the steps; let the gates catch what you forget. See research/linter-adapter-architecture.md.

The one invariant

A linter is one LinterAdapter in one registry. Everything else — existence, config-enabled, suggestions, type-gen, docs, site — is a field or a method on that adapter, cross-checked by the conformance test. You never again hunt for "the other place this linter is registered."

Steps

Work in this order — each step's gate tells you the next is needed.

  1. Name it (the single source). Add the lowercase name to BUILTIN_LINTERS in src/core/spec.ts. BuiltinLinter derives from this array, so the moment you save, tsc fails on LINTERS in linters.ts with "property <name> is missing" — that error is your to-do list.
  2. Pick the existence-check kind (LinterCapabilities.existenceCheck in src/core/linter-adapter.ts) — this decides which helper builds the adapter:
    • node-api — the rule set is resolved from an installed npm package (eslint, stylelint). Use nodeApiAdapter(name, resolver, configEnabled, discover).
    • cli — a real command asks the tool whether a rule exists (ruff, clippy, pylint, rubocop, detekt, ktlint, checkstyle, golangci-lint). Use cliAdapter(name, cliTool, checkExists, configEnabled, discover, enumerate?).
    • filesystem — presence in a project file counts, no tool (cedar). Write a literal adapter (see cedar in linters.ts).
    • format-only — only the reference shape is validated, no tool exists to list rules (ktlint's catalog is unlistable). Still a cli adapter, just omit the enumerate arg; the existence check is the qualified-shape rule.
  3. Implement the discoverer discover<Name>Rules(basePath): DiscoveredRules | null in linters.ts — reads the project's real linter config and returns its enabled rules for generate-types (fail open: return null, never flag every rule, when you can't enumerate). If it's a cli linter, also write its <name>CheckExists existence probe (throws when the rule is unknown) and, for a real config-enabled read, its <name>ConfigEnabled checker — plain named functions the adapter references directly in the LINTERS registry (there is no separate map to touch). Parse structured config with a real parser (js-yaml / @iarna/toml / the shared markdown-it helper), never a hand-rolled regex — see the parse-structured-input-with-a-real-parser rule; detekt's parseDetektConfig (js-yaml) is the model.
  4. Register it in LINTERS (linters.ts) via the matching helper. tsc goes green here — the registry is now complete.
  5. Document it — docs/linter-support.md: add a row to the ## Supported Linters table AND a ## <Linter> section (config conventions, rule-prefix, any capability caveat like "format-only" or "whitelist-only"). The conformance test set-matches the table against the registry, so a missing row fails CI.
  6. The site updates itself — the vigiles.sh chip strip (Wedge.tsx) DERIVES from BUILTIN_LINTERS, so a new linter appears automatically; there's no array to edit. Optionally add a display label to LINTER_LABELS in Wedge.tsx if it needs special casing (e.g. ESLint, RuboCop); with no entry it renders under its lowercase name. The conformance test guards that the derivation stays in place (a revert to a hand-typed list fails CI).
  7. If it's a cli linter, make CI actually run it — no silent skips. The real-binary tests are describe.skipIf(!hasBinary("<tool>")) in src/core/linters.test.ts; a binary absent from CI means those tests skip silently (a hidden gap — the no-silent-skips rule). Install the tool in the test job of .github/workflows/ci.yml (pin a version via a job env, cache it) AND add it to the command -v sanity loop so a missing binary fails the build instead of skipping. Then write the two complementary tests: a real-binary test (describe.skipIf(!hasBinary)) and a missing-binary honest-error test (it.skipIf(hasBinary)) — one always runs, the pair is loud either way.
  8. Add the parity test data. The conformance loop in src/core/linter-contract.test.ts is generic (it iterates the registry), so it covers the new linter automatically — but add a targeted config-parse/discover unit test in linters.test.ts for the new linter's own parser, and a per-linter capability assertion if it has an unusual variance (e.g. format-only, alwaysEnabled).

The gates that make this safe

Run npm test (or at least npx vitest run src/core/linter-contract.test.ts src/core/linters.test.ts + tsc --noEmit). You are done only when:

  • tsc is clean — the registry entry exists (completeness).
  • linter-contract.test.ts is green — key === name, every capability flag matches its method's presence, existenceCheck === "cli" ⟺ cliTool present, and the registry keys set-match BUILTIN_LINTERS and docs/linter-support.md and the site chip list (docs + site parity).
  • The new linter's config-parse unit test passes with no binary, and its real-binary test runs in CI (installed + sanity-gated), not skipped.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.