holocron/plugins/lint/skills/vale-config/SKILL.md

name, description, metadata

name	description	metadata
vale-config	Use when installing or configuring Vale, the prose/style linter — writing a `.vale.ini` whose styles are fetched and actually activated — even when the user says only "set up prose linting". Not running Vale on an existing config -> `vale-run`.	category version source_keys lint 0.1.2 context7-websites-vale-sh house-vale-3-15-2-repro

Gotchas

• A style in BasedOnStyles that is neither built-in nor a directory under StylesPath fails hard, not silently: E100 [loadStyles], exit 2, nothing linted.
• vale sync alone does not clear that E100. Sync fetches only what the top-level Packages key declares, so against a BasedOnStyles-only name it reports Synced 0 package(s) and exits 0, fetching nothing. Add the style to Packages, then sync. A style lints only once it is in both keys — and the reverse case is silent, exiting 0.
• Only package styles need fetching: built-in Vale, and any style whose YAML is already committed under StylesPath, lint with no Packages entry and no sync.
• .vale.ini order is enforced, not stylistic: put core settings first, then [formats], then glob sections. A core setting (StylesPath, MinAlertLevel, Vocab, IgnoredScopes, SkippedScopes) written below a [glob] header is a hard error — E201 ... 'StylesPath' is a core option; it should be defined above any syntax-specific options, exit 2, nothing linted. Packages is the exception, and the worse one: below a glob header it is accepted with no error, then ignored — vale sync reports Synced 0 package(s) and downloads nothing.
• An .mdx file covered by one of your globs takes the whole run down unless [formats] maps it. Vale 3.15.2 has no built-in MDX support: unmapped, it shells out to an external mdx2vast binary, and with that absent from PATH the invocation dies on E100 [lintMDX] Runtime error / mdx2vast not found, exit 2 — every other file in the same command goes unlinted, with no output of its own. Default to the mapping — a [formats] section holding mdx = md, above the glob sections — which needs nothing installed; npm install -g mdx2vast is the alternative. The choice also inverts the inline-suppression syntax vale-run uses, so record which one the config took.
• A rule scoped to text.frontmatter.<key> silently matches nothing when the field spans multiple lines in most YAML forms. If you scope a rule to frontmatter, read references/configuration-reference.md first.

Setup workflow

• Install the vale binary: brew install vale (macOS), snap install vale (Linux), choco install vale (Windows), or docker pull jdkato/vale.

• Pick a StylesPath (conventionally styles) and create it. This is where all styles, dictionaries, and vocab live.

• Write .vale.ini at the project root with at minimum:

  StylesPath = styles
  MinAlertLevel = suggestion
  
  [*.md]
  BasedOnStyles = Vale
  

  Vale here is the built-in style (Vale.Spelling, Vale.Terms, Vale.Avoid, Vale.Repetition): no Packages entry and no vale sync. It still needs the StylesPath directory to exist — declare StylesPath = styles without creating styles/ and even a Vale-only config dies with E201 ... The path '...' does not exist, exit 2. That is why the previous step creates the directory.

  Settings in a glob section only apply to files matching that glob. BasedOnStyles under [*.md] governs .md and nothing else: a .mdx, .rst or .txt in the same tree has no style active, is skipped without being counted, and a run over only such files reports 0 files and exits 0 — indistinguishable from clean. Give every extension you mean to lint a glob that covers it.

• Add third-party styles (optional) by declaring them in Packages, then activating them in the same or another glob's BasedOnStyles:

  Packages = Google, write-good
  
  [*.md]
  BasedOnStyles = Vale, Google, write-good
  

• Sync: run vale sync to download everything listed in Packages into StylesPath.

• Verify activation: confirm every style named in Packages also appears in at least one glob's BasedOnStyles — an unreferenced package downloads but never lints anything.

For the full .vale.ini field reference (formats mapping, vocab, local overrides, custom rule header fields) and the verified style-resolution matrix — which error each misconfiguration raises, and the two that exit 0 while linting nothing — read references/configuration-reference.md.

Custom styles

A custom style is just a new subdirectory under StylesPath, holding one YAML file per rule:

styles/
└── MyStyle/
    └── NoJargon.yml

Each rule file needs extends (the check it implements, e.g. existence) and message at minimum. Activate the style the same way as any other: add MyStyle to BasedOnStyles for the relevant glob. If a rule needs a field beyond those two, read references/configuration-reference.md for the full rule header field table.