From e4abe23560dddb96b5ffa49eaee1ac1bffe0bd00 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Thu, 23 Jul 2026 19:11:38 +0000 Subject: [PATCH] feat(lint): add vale-config skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn --- .../docs/research/docs/vale/cli-reference.md | 0 .../docs/research/docs/vale/configuration.md | 0 .../docs/research/docs/vale/examples.md | 0 .../docs/research/docs/vale/installation.md | 0 .../docs/research/docs/vale/overview.md | 0 .../docs/research/docs/vale/sources.md | 0 .../research/docs/vale/troubleshooting.md | 0 plugins/lint/skills/vale-config/README.md | 23 ++++++ plugins/lint/skills/vale-config/SKILL.md | 62 +++++++++++++++ .../references/configuration-reference.md | 78 +++++++++++++++++++ .../skills/vale-config/references/sources.md | 9 +++ 11 files changed, 172 insertions(+) rename plugins/{kyberforge => lint}/docs/research/docs/vale/cli-reference.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/configuration.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/examples.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/installation.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/overview.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/sources.md (100%) rename plugins/{kyberforge => lint}/docs/research/docs/vale/troubleshooting.md (100%) create mode 100644 plugins/lint/skills/vale-config/README.md create mode 100644 plugins/lint/skills/vale-config/SKILL.md create mode 100644 plugins/lint/skills/vale-config/references/configuration-reference.md create mode 100644 plugins/lint/skills/vale-config/references/sources.md diff --git a/plugins/kyberforge/docs/research/docs/vale/cli-reference.md b/plugins/lint/docs/research/docs/vale/cli-reference.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/cli-reference.md rename to plugins/lint/docs/research/docs/vale/cli-reference.md diff --git a/plugins/kyberforge/docs/research/docs/vale/configuration.md b/plugins/lint/docs/research/docs/vale/configuration.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/configuration.md rename to plugins/lint/docs/research/docs/vale/configuration.md diff --git a/plugins/kyberforge/docs/research/docs/vale/examples.md b/plugins/lint/docs/research/docs/vale/examples.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/examples.md rename to plugins/lint/docs/research/docs/vale/examples.md diff --git a/plugins/kyberforge/docs/research/docs/vale/installation.md b/plugins/lint/docs/research/docs/vale/installation.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/installation.md rename to plugins/lint/docs/research/docs/vale/installation.md diff --git a/plugins/kyberforge/docs/research/docs/vale/overview.md b/plugins/lint/docs/research/docs/vale/overview.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/overview.md rename to plugins/lint/docs/research/docs/vale/overview.md diff --git a/plugins/kyberforge/docs/research/docs/vale/sources.md b/plugins/lint/docs/research/docs/vale/sources.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/sources.md rename to plugins/lint/docs/research/docs/vale/sources.md diff --git a/plugins/kyberforge/docs/research/docs/vale/troubleshooting.md b/plugins/lint/docs/research/docs/vale/troubleshooting.md similarity index 100% rename from plugins/kyberforge/docs/research/docs/vale/troubleshooting.md rename to plugins/lint/docs/research/docs/vale/troubleshooting.md diff --git a/plugins/lint/skills/vale-config/README.md b/plugins/lint/skills/vale-config/README.md new file mode 100644 index 0000000..2a5d0bc --- /dev/null +++ b/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 | diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md new file mode 100644 index 0000000..2d52429 --- /dev/null +++ b/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. diff --git a/plugins/lint/skills/vale-config/references/configuration-reference.md b/plugins/lint/skills/vale-config/references/configuration-reference.md new file mode 100644 index 0000000..d2bca35 --- /dev/null +++ b/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 `/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"). diff --git a/plugins/lint/skills/vale-config/references/sources.md b/plugins/lint/skills/vale-config/references/sources.md new file mode 100644 index 0000000..854fe15 --- /dev/null +++ b/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`