add-a-linter — Claude Code skill: what it does, how to install
The add-a-linter skill guides contributors through adding a linter to vigiles, including its adapter, registry entry, docs, tests, and CI checks.
MIT 120 installs ★ 16 updated 2026-10-14
npx skills add zernie/vigiles --skill add-a-linter -a claude-codeWhat add-a-linter does
The skill walks an agent through adding a linter to vigiles itself. It covers choosing how the tool checks rule existence, implementing an adapter and rule discoverer, then adding the entry to LINTERS. The registry is a closed set, so this is a change to the project rather than a third-party extension.
The workflow also covers the support table and linter section in docs/linter-support.md, config parsing tests, and CI setup for CLI-based linters. A conformance test checks registry, docs, and site parity. Structured configuration needs a real parser such as js-yaml or @iarna/toml; a hand-written regex is not the intended approach.
This work touches TypeScript, tests, and CI. If the CLI binary is not installed in CI and checked with command -v, its real-binary tests can be skipped silently.
What it helps with
- add a linter to vigiles’ closed registry
- choose an adapter for checking whether rules exist
- read enabled rules from a project configuration
- keep the docs and site list aligned with the registry
- configure CI so CLI linter tests cannot silently skip
Example prompts for the agent
- Add biome to vigiles as a linter and follow the skill’s workflow.
- Integrate checkov as a CLI linter, including its adapter, tests, and CI setup.
- Add a linter to vigiles and verify registry, docs, and site parity.
How to install add-a-linter
1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill add-a-linter -a claude-code2Manually: put the files in place
~/.claude/skills/add-a-linter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/add-a-linter/
1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill add-a-linter -a codex2Manually: put the files in place
.agents/skills/add-a-linter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill add-a-linter -a cursor2Manually: put the files in place
.cursor/skills/add-a-linter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zernie/vigiles .claude/skills/add-a-linter2Manually: put the files in place
.github/skills/add-a-linter/SKILL.md1Skills CLI (Vercel)
npx skills add zernie/vigiles --skill add-a-linter -a gemini-cli2Platform CLI
gemini skills install https://github.com/zernie/vigiles --path .claude/skills/add-a-linterManually: put the files in place
.devin/skills/add-a-linter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zernie/vigiles --skill add-a-linter -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about add-a-linter
How do I install add-a-linter in Claude Code?
Run npx skills add zernie/vigiles --skill add-a-linter -a claude-code. The skill file is placed at ~/.claude/skills/add-a-linter/SKILL.md.
What does the add-a-linter skill do?
It guides the agent through adding a linter to vigiles, from its adapter and registry entry to config parsing, documentation, and tests. For CLI linters, it also covers CI installation and checks that prevent silent test skips.
Does the site’s linter list need a manual update?
No. The site list derives from BUILTIN_LINTERS. Add an entry to LINTER_LABELS only when the linter needs a special display name.
Source text
SKILL.md · MIT
---
name: add-a-linter
description: 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
disable-model-invocation: true
argument-hint: <linter name, e.g. "biome" or "checkov">
---
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.
© zernie · MIT · zernie/vigiles