Vale linting skill

Run Vale style linting against documentation files to check for style guide violations.

Before linting

Check for vale.ini

Before running Vale, check if a .vale.ini or vale.ini exists in the project root:

ls .vale.ini vale.ini 2>/dev/null

If neither exists, create a temporary config in /tmp/ and use it for the lint run:

cat <<'EOF' > /tmp/vale-temp.ini
StylesPath = .vale/styles
MinAlertLevel = suggestion
Packages = RedHat

[*.adoc]
BasedOnStyles = RedHat

[*.md]
BasedOnStyles = RedHat
EOF

Use --config=/tmp/vale-temp.ini when running Vale, and remove the temp config when done.

Inform the user that no project-level .vale.ini was found and a temporary config was used.

Sync styles

Always run vale sync before linting to ensure style packages are up to date:

vale sync

This downloads and updates the style packages defined in .vale.ini (e.g., the RedHat package).

Supported file types

Vale supports many file formats:

• Markup: Markdown (.md), AsciiDoc (.adoc, .asciidoc), reStructuredText (.rst), HTML (.html), XML (.xml, .dita)
• Source code comments: Python, Go, JavaScript, TypeScript, C, C++, Java, Ruby, Rust, and more
• Other: Org mode (.org), plain text (.txt)

Usage

Run Vale directly against files or directories:

# Single file
vale README.md
vale doc.adoc
vale guide.rst

# Multiple files
vale file1.md file2.adoc file3.rst

# Directory (lints all supported files)
vale docs/

# Specific file patterns
vale --glob='*.md' docs/
vale --glob='*.{md,adoc,rst}' docs/

Common options

# Use a specific config file
vale --config=/path/to/.vale.ini docs/

# Match specific file types
vale --glob='**/*.md' path/to/files
vale --glob='**/*.{adoc,md}' path/to/files

# Only show errors and warnings (skip suggestions)
vale --minAlertLevel=warning docs/

# Only show errors
vale --minAlertLevel=error docs/

# JSON output for programmatic use
vale --output=JSON docs/

# Exclude certain files
vale --glob='!**/*-generated.md' docs/

# Lint source code comments
vale --glob='*.py' src/
vale --glob='*.go' pkg/

Presenting results

After running Vale, organize the output for the user:

1. Lead with errors. Errors are must-fix violations. Present them first with the file, line, and what to change.
2. Group warnings and suggestions separately. Warnings need attention; suggestions are optional improvements.
3. Summarize by file when linting multiple files. Show a table with error/warning/suggestion counts per file so the user can prioritize.

4. Flag likely false positives. Common RedHat Vale false positives include:

   • Technical terms not in the dictionary (e.g., "repo", "docstrings", "deduplicated")
   • Proper nouns and product names flagged by spelling rules (e.g., "Kubernetes", "Zensical")
   • Content inside fenced code blocks incorrectly linted (Vale parser limitation)
   • Acronyms in headings flagged by capitalization rules (e.g., "CLI", "API")
   • Passive voice in conditionals and prerequisites (e.g., "if no files are found", "must be installed")

   When you spot a likely false positive, note it as such rather than recommending the user change correct text.

5. Do NOT auto-fix source files. Report findings and let the user decide what to change.

Example invocations

• "Lint the docs/ folder"
• "Check style on README.md"
• "Run Vale against all Markdown files"
• "Validate the AsciiDoc modules"
• "Show only errors in the documentation"
• "Lint Python docstrings in src/"
• "Check style guide compliance for all documentation"

Output format

docs/guide.md:15:3: error: Style.Spelling - 'kubernetes' should be 'Kubernetes'
docs/guide.md:23:1: warning: Style.PassiveVoice - Avoid passive voice
modules/intro.adoc:45:10: suggestion: Style.SentenceLength - Consider shortening this sentence

Prerequisites

Vale must be installed:

# Fedora/RHEL
sudo dnf copr enable mczernek/vale && sudo dnf install vale

# macOS
brew install vale

# Other platforms
# See: https://vale.sh/docs/install