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

name, description, metadata

name	description	metadata
vale-config	Use when installing or configuring Vale, the cross-platform prose/style linter — setting up .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run Vale and interpret its output on existing config — use vale-run for that.	category version source_keys lint 0.1.0 context7-websites-vale-sh

Gotchas

• Installing the vale binary installs no styles, but only package styles need fetching. A fresh .vale.ini naming a style in BasedOnStyles that is declared in Packages will fail or find nothing until vale sync downloads it. A built-in style (Vale) or a style whose YAML rule files are already committed under StylesPath lints immediately, with no Packages entry and no sync.
• .vale.ini is order-sensitive: global (core) settings first, then the optional [formats] section, then glob sections ([*], [*.md], …). Settings in a glob section only apply to files matching that glob.
• Packages (top-level, fetched by vale sync) and BasedOnStyles (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
• A rule scoped to text.frontmatter.<key> (e.g. text.frontmatter.description) matches reliably when that field's value is a single physical line, and breaks on most — not all — multi-line forms. Confirmed against Vale 3.15.2 with a deliberately-bad fixture: a > folded block scalar, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars each yield 0 findings and exit 0, silently and with no error; a | literal block scalar spanning the same 2+ lines lints normally and exits 1. Do not assume | and > behave alike — reproduce both against your own config before trusting a frontmatter-scoped rule in production. If the field is commonly authored in one of the broken forms, flatten it to one physical line ahead of the vale call rather than relying on the scope alone.

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 download needed, it always works.
• 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), 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. See references/configuration-reference.md for the full rule header field table.