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

name, description, metadata

name	description	metadata
vale-run	Use when running Vale (a prose/style linter) against files or directories in an already-configured project — one that already has a .vale.ini — and interpreting or reporting its results: choosing an output format for humans vs. CI, filtering by severity, handling Vale's exit codes in scripts, or resolving common runtime issues like false positives and unexpected CI failures. Use even if the user doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run the style linter", "why is CI failing on the docs check". Do not use when the project has no .vale.ini yet, or needs styles installed/configured — that's the vale-config skill.	version category source_keys 0.1.0 lint context7-websites-vale-sh

Gotchas

• Vale exits non-zero whenever it finds an alert at or above MinAlertLevel — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
• vale ls-config prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in .vale.ini.
• Inline suppression syntax is format-specific: Markdown/MDX uses {/* vale off */} / {/* vale on */}, Org mode uses # vale off / # vale on. Don't assume one syntax works across formats.

Running vale

Default invocation:

vale <path-or-glob>

Key flags:

Flag	Purpose
--output=<style>	Output format/template: CLI (default, human-readable), line (compact, one alert per line, good for grep/piping), JSON (for programmatic parsing), or a custom template.
--minAlertLevel=<suggestion|warning|error>	Overrides MinAlertLevel from .vale.ini for this run only, without editing config.
--no-exit	Forces exit code 0 regardless of findings. Use in CI stages that should surface lint output without hard-failing the build.
--ignore-syntax	Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results.

vale sync downloads the packages/styles declared in .vale.ini — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, that's a sign vale sync hasn't been run yet, not a vale-run problem.

Prefer --output=JSON whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — CLI and line are for humans reading the terminal.

Fixing false positives

Scope the fix as narrowly as possible, in this order:

1. One-off: inline-suppress the specific text run with the format's vale off/vale on markup.
2. Recurring known-exception string, one rule: disable that specific rule for that specific match inline (e.g. {/* vale Style.Redundancy["ACT test","OTHER"] = NO */} ... = YES), rather than the whole rule.
3. Known project term failing spell check: add it to the style's ignore list, not an inline suppression.

Never disable a rule project-wide to fix one false positive — editing .vale.ini/BasedOnStyles is vale-config's job, and it silences the rule everywhere, not just the false-positive case.

If output looks wrong because Vale mis-parsed a file's format, rerun with --ignore-syntax before assuming the rule itself is broken.

For CI that fails solely because Vale returned non-zero on found alerts — not because the content is wrong for that pipeline stage — add --no-exit rather than disabling the rule.

If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read references/troubleshooting.md.