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`