feat(lint): add vale-config skill

Covers Vale install and .vale.ini setup — StylesPath, built-in/
third-party/custom styles, BasedOnStyles activation. Setup half of
Vale support; vale-run (running/interpreting) is a separate skill.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn

plugins/lint/docs/research/docs/vale/cli-reference.md

@@ -0,0 +1,29 @@
+---
+topic: cli-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Invocation
+
+```bash
+$ vale README.md
+```
+
+Lints the given file(s)/glob against the styles configured in `.vale.ini`.
+
+## Key Flags and Subcommands
+
+| Command/Flag | Purpose |
+|---|---|
+| `vale sync` | Downloads and installs packages/styles declared in `.vale.ini`. Run after install and whenever `Packages` changes. |
+| `vale ls-config` | Prints the currently active, fully-resolved configuration as JSON. Useful for debugging what settings actually apply to a file. |
+| `--output=<style>` | Sets the output format/template: `line`, `JSON`, `CLI` (default), or a custom template. |
+| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
+| `--ignore-syntax` | Treats input as plain, unformatted text, skipping syntax-aware parsing (Markdown/HTML/etc). |
+| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). |
+| `--version` | Prints the Vale binary version. |
+
+## Exit Codes
+
+By default, `vale` exits non-zero when it finds any alert at or above `MinAlertLevel` — this is what makes it usable as a CI gate. Pass `--no-exit` to always exit `0` regardless of findings.

plugins/lint/docs/research/docs/vale/configuration.md

@@ -0,0 +1,106 @@
+---
+topic: configuration
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## `.vale.ini` Structure
+
+Configuration is INI-formatted with three sections, in order:
+
+```ini
+# Core settings appear at the top
+# (the "global" section).
+
+[formats]
+# Format associations appear under
+# the optional "formats" section.
+
+[*]
+# Format-specific settings appear
+# under a user-provided "glob"
+# pattern.
+```
+
+Core (global) settings apply application-wide; glob sections (`[*]`, `[*.md]`, etc.) scope settings to files matching that pattern.
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+Example:
+
+```ini
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[*.md]
+BasedOnStyles = Vale
+```
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser. This is an extension-level substitution only — it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Packages
+
+Third-party style packages are declared via `Packages` and then activated per glob with `BasedOnStyles`:
+
+```ini
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google, write-good
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |

plugins/lint/docs/research/docs/vale/examples.md

@@ -0,0 +1,52 @@
+---
+topic: examples
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Project Initialization Walkthrough
+
+```bash
+$ cd some-project
+# create .vale.ini with StylesPath + BasedOnStyles
+$ vale sync         # downloads declared packages/styles into StylesPath
+$ ls styles          # confirms styles were installed
+$ vale README.md     # lint a file
+```
+
+The `.vale.ini` file must exist before `vale sync` — it declares which packages to fetch.
+
+## Typical Project Config
+
+```ini
+StylesPath = styles
+MinAlertLevel = error
+
+[*.md]
+BasedOnStyles = ProjectStyle
+```
+
+## pre-commit Integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI Output for Machine Parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.

plugins/lint/docs/research/docs/vale/installation.md

@@ -0,0 +1,41 @@
+---
+topic: installation
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Package Managers
+
+Vale is distributed via standard OS package managers:
+
+```bash
+brew install vale      # macOS
+snap install vale      # Linux
+```
+
+```powershell
+choco install vale      # Windows
+```
+
+## Docker
+
+An official image is available on Docker Hub:
+
+```bash
+docker pull jdkato/vale
+```
+
+## Post-Install: Syncing Styles
+
+Installing the `vale` binary alone does not install any styles. After install, run `vale sync` to download and install the styles/packages declared in `.vale.ini`:
+
+```bash
+$ vale sync
+```
+
+## Format-Specific Extras
+
+Some input formats need an external converter installed separately before Vale can process them:
+
+- reStructuredText: `pip install docutils` (provides `rst2html`)
+- MDX: `npm install -g mdx2vast`

plugins/lint/docs/research/docs/vale/overview.md

@@ -0,0 +1,43 @@
+---
+topic: overview
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## What Vale Is
+
+Vale is a cross-platform command-line tool that brings code-like linting to prose. Rather than checking general grammar, it enforces project-specific writing style rules — consistency of terminology, phrasing, and formatting — the same way a linter enforces a code style guide.
+
+## Styles, Rules, and Checks
+
+Vale's configuration model has three layers:
+
+- **Styles** — a named collection of rules (e.g. the built-in `Vale` style, or third-party styles like `Google` or `write-good`). A project can apply multiple styles at once via `BasedOnStyles`.
+- **Rules** — individual YAML files that define one specific check (e.g. flag a term, enforce a heading capitalization pattern). Each rule `extends` a check and sets a `message`, `level`, and other header fields.
+- **Checks** — the underlying functions a rule extends to perform analysis: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").
+
+## Styles Directory Layout
+
+Styles live under `StylesPath` in a nested folder structure, one subdirectory per style, each holding YAML rule files:
+
+```
+styles/
+├── base/
+│   ├── ComplexWords.yml
+│   ├── SentenceLength.yml
+├── blog/
+│   ├── TechTerms.yml
+└── docs/
+    ├── Branding.yml
+```
+
+This lets a project mix a shared base style with format- or section-specific styles, all activated per-glob in `.vale.ini`.

plugins/lint/docs/research/docs/vale/sources.md

@@ -0,0 +1,8 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md
+- **Status:** `extracted`

plugins/lint/docs/research/docs/vale/troubleshooting.md

@@ -0,0 +1,56 @@
+---
+topic: troubleshooting
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Suppressing False Positives Inline
+
+Vale supports inline markup comments to disable checks for a section of content. Syntax varies by format:
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a Specific Rule for Specific Matches
+
+Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+This is the preferred fix for recurring false positives on specific terms — it keeps the rule active everywhere else instead of disabling it project-wide.
+
+## Ignoring Words in Spell Check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so known project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-Text Fallback
+
+If a file's syntax-aware parsing produces noisy/incorrect results (e.g. an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI Failing Unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it.

plugins/lint/skills/vale-config/README.md

@@ -0,0 +1,23 @@
+# vale-config
+
+Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`.
+
+## What it does
+
+Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that.
+
+## Usage
+
+```
+/vale-config
+```
+
+Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference |
+| `references/sources.md` | Research sources backing the Vale configuration guidance |

plugins/lint/skills/vale-config/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: vale-config
+
+description: >
+  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.
+
+metadata:
+  category: lint
+  version: "0.1.0"
+  source_keys:
+    - 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.
+- Declaring `StylesPath` and `Packages` alone activates nothing. A style only lints files once it's listed in `BasedOnStyles` under a glob section that matches those files — this is the step people forget.
+- `Packages` (top-level, for `vale sync` to fetch) and `BasedOnStyles` (per-glob, to activate) are two different keys serving two different purposes. Both are required for a third-party style to actually run.
+
+## 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:
+  ```ini
+  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`:
+  ```ini
+  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.

plugins/lint/skills/vale-config/references/configuration-reference.md

@@ -0,0 +1,78 @@
+---
+topic: configuration-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser — an extension-level substitution only, it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |
+
+## Checks
+
+The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules, usable without `vale sync`:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").

plugins/lint/skills/vale-config/references/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, installation across package managers and Docker.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/configuration-reference.md
+- **Status:** `extracted`