Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add zernie/vigiles --skill add-a-linter -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/add-a-linter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/add-a-linter/

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

Similar skills

All skills for Code review and refactoring →

From the same set19

The whole set →
enforce-rules-format enforce-rules-format is a Claude Code skill that checks rule enforcement classes and suggests fixes for projects managing instructions with Vigiles. CX Codex +1 433installs generate-logo generate-logo generates logo variations for the vigiles project using the ImageRouter API. Useful when experimenting with visual branding or iterating on icons. CX Codex +1 410installs code-quality code-quality — a skill for refactoring TypeScript and JavaScript: tightens types, removes impossible states, and separates logic from IO. CX Codex +1 392installs audience-check audience-check reviews your README or documentation through six reader personas to reveal confusion points, missing definitions, and early drop-offs. CX Codex +1 387installs verify-docs-findable verify-docs-findable is a Claude Code skill that checks whether repo docs answer reader questions. Haiku agents read only the docs and show where answers get lost. CX Codex +1 340installs screenshot The screenshot skill renders local pages in Chromium and saves full-page desktop and mobile captures. Use it to inspect a landing page, report, or local dev server. CX Codex +1 337installs landing-site landing-site — a skill with UX and design rules for the vigiles.sh landing page. The agent reads it before editing site components, hero, or copy and checks every change against the standard. CX Codex +1 295installs dogfood-cli dogfood-cli audits the vigiles CLI against itself using parallel agents, traces bugs to exact lines, and applies direct fixes. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open