Skill Vale

skill-vale

Reference for diagnosing Vale configuration and lint issues: config file resolution, style loading, package sync, format detection, and common error messages.

How Vale resolves configuration

Vale searches for .vale.ini starting from the directory of the file being linted and ascending the directory tree until it finds one. A --config flag overrides this search entirely.

# Use an explicit config — bypasses auto-discovery
$VALE_QDOC_BIN --config=/path/to/.vale-qdoc.ini <files>

Common mistake: running Vale from a directory that has its own .vale.ini higher up the tree. The wrong config is picked up silently. Use ls-config to confirm which config is active:

$VALE_QDOC_BIN ls-config

This prints the fully resolved configuration as JSON, including the absolute StylesPath, loaded styles, and MinAlertLevel. Use it as the first debugging step whenever output looks wrong.

StylesPath

StylesPath is the directory Vale searches for style folders and packages. It must be set correctly in .vale.ini or Vale cannot find any rules.

StylesPath = styles

Relative paths are resolved from the location of the .vale.ini file, not from the working directory. If ls-config shows an unexpected StylesPath, check the path relative to the config file.

Symptoms of a wrong StylesPath:

• Zero alerts on files that should trigger rules
• unknown style error in output
• vale sync downloads to a different location than expected

vale sync — downloading style packages

vale sync downloads and installs all packages listed under Packages in .vale.ini into StylesPath. Always run it from the directory containing the config file, or use --config:

cd <vale_linter_config-path>
$VALE_QDOC_BIN --config=.vale-qdoc.ini sync

What sync does:

• Style-only packages (e.g. Microsoft): extracts the style folder into StylesPath/Microsoft/
• Config-only packages: adds files to StylesPath/.vale-config/
• Complete packages: merges both

Sync does not run automatically — if styles/Microsoft/ is absent, rules from that package silently produce no alerts.

Check after sync:

ls <StylesPath>/Microsoft/

If the directory is empty or missing, re-run sync with the correct config.

Rule files not found

Vale loads rules by looking up StylesPath/<Style>/<Rule>.yml for each entry in BasedOnStyles.

Rule is silently skipped if:

• The file has a .yaml extension instead of .yml — Vale only detects .yml
• The style folder name does not exactly match the name in BasedOnStyles
• StylesPath points to the wrong directory

Confirm a rule exists:

ls <StylesPath>/Qt/QDocBrief.yml

Confirm a rule's severity:

grep 'level:' <StylesPath>/Qt/QDocBrief.yml

Note: --output=line does not include severity in its output. Always look it up from the rule YAML directly.

Format detection and the [formats] section

Vale determines how to parse a file from its extension. Extensions not recognised by Vale default to plain text (no markup parsing).

Map unknown extensions to a supported format in .vale.ini:

[formats]
qdoc    = md
qdocinc = md
cpp     = qdoc

The patched Vale build adds qdoc as a built-in format. Standard Vale does not recognise .qdoc or .qdocinc files — they are treated as plain text, meaning markup-scoped rules (headings, paragraphs) do not fire.

Verify format routing:

$VALE_QDOC_BIN ls-config | grep -A5 '"Formats"'

MinAlertLevel

Controls which severity levels appear in output.

MinAlertLevel = warning   # shows warning, error (suppresses suggestion)
MinAlertLevel = suggestion # shows all levels
MinAlertLevel = error      # shows error only

If expected alerts are missing and the rule YAML shows level: suggestion, the alert is suppressed by MinAlertLevel. Lower the threshold to expose it.

Exit codes

Exit code 2 indicates a configuration or runtime problem, not a lint result. Check stderr for the error message.

Common diagnostic commands

Common error messages

unknown style 'X'

BasedOnStyles references a style folder that does not exist under StylesPath. Check that the folder name matches exactly (case-sensitive on Linux) and that vale sync has been run.

No output / zero alerts

Possible causes (check in order):

1. VALE_QDOC_BIN or VALE_CONFIG_PATH is unset — hook exits 0 silently
2. MinAlertLevel is set higher than the rule's level:
3. StylesPath is wrong — rules not loaded
4. File extension not mapped in [formats] — parsed as plain text
5. Rule file uses .yaml extension instead of .yml — silently skipped

could not find .vale.ini

Vale searched from the current directory up to the filesystem root and found no config file. Use --config to point directly to the correct .vale.ini.

Rule fires twice on the same line

Known parser bug in Vale's GetComments for broad-scoped rules applied to \brief, \title, and \section* lines. Deduplicate by (file, line, col, check) before presenting results — this is not fixable from config.

YAML rule authoring pitfalls

• Extension must be .yml, not .yaml — Vale silently ignores .yaml
• Regex patterns must be quoted — unquoted patterns may be misread by the YAML parser; prefer single quotes ('pattern')
• \b word boundaries are added automatically by existence and substitution rules; set nonword: true to disable
• Scope raw applies a rule to the unprocessed source file, bypassing markup parsing — useful when a rule needs to match markup syntax itself

Version History

• v1.0 (2026-03-30): Initial version
  • Vale config file resolution and ls-config debugging
  • StylesPath resolution and common symptoms of misconfiguration
  • vale sync package download procedure
  • Rule file detection (.yml vs .yaml, style folder matching)
  • Format detection and the [formats] section
  • MinAlertLevel and exit codes
  • Common diagnostic commands table
  • Common error messages: unknown style, zero alerts, config not found, duplicate rule-fires
  • YAML rule authoring pitfalls