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

Files

Defame1297 57654c4b02 docs(lint): correct the Vale scalar, size-ceiling and release-gate claims

Four claims in shipped agent-facing docs did not match verified behaviour.
These are read as ground truth by agents in other repos, so each was
reproduced against vale 3.15.2 before rewriting:

- CONTEXT.md and `vale-config/SKILL.md` said both `>` and `|` block scalars
  break the description scope. `|` does not — it lints normally and fires every
  alert, while `>` yields zero. An agent following the old text would rewrite a
  working `|` description into a plain multi-line scalar, which genuinely does
  break, inverting the intended remediation. Both now name the forms that do
  break and state that `|` does not.
- CONTEXT.md and ADR-0013 described the size hook as failing only above 500
  lines, omitting the 2900-word gate it also enforces. Both now describe the
  pair and state that `validate.sh` checks the same two.
- ADR-0014 recorded an accepted residual — a wholesale `assets/` deletion going
  unflagged — that commit 14c2c91 closed. Left as the point-in-time record and
  amended with an update describing the union-with-tag-manifest mechanism,
  following the amendment precedent in ADR-0005.
- `vale-config/SKILL.md` asserted a fresh `.vale.ini` fails until `vale sync`
  runs, contradicting its own note that built-in styles need no download. The
  claim is now scoped to package styles; this repo's two configs declare no
  packages and lint clean with zero syncs.

Also repoints AGENTS.md at the seven `gitea:*` skills — the `bin:gitea` route
it named no longer exists.

Refs: #85

2026-08-09 15:44:28 +00:00

4.1 KiB

Raw Blame History

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.

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.

4.1 KiB Raw Blame History

Gotchas

Setup workflow

Custom styles

4.1 KiB

Raw Blame History