holocron/plugins/lint/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. A fresh .vale.ini with BasedOnStyles set will fail or find nothing until vale sync runs and downloads the Packages it declares.
• .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) only reliably matches when that field's value is a single physical line. If it's a YAML block scalar (>/|) spanning 2+ physical lines, the scope silently stops matching — no error, just 0 findings — confirmed against Vale 3.15.2. Verify with a deliberately-bad multi-line fixture before trusting a frontmatter-scoped rule in production; if the field is commonly authored as a multi-line block scalar, flatten it to one 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.