docs(recheck): document the recheck command and update the agent skills

.changeset/recheck-command.md

@@ -9,3 +9,4 @@ It lints Markdown prose and structure from the `recheck` block in `redocly.yaml`
 Presets merge with the `recheck` blocks in `extends` order, like other presets.
 The engine's actions return data.
 The CLI prints it.
+Two agent skills ship in the package under `skills/` and with the repository's other skills: `recheck-lint` runs the command on touched Markdown, and `recheck-config` tunes the `recheck` block.

.claude/skills/recheck-config/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: recheck-config
+description: Use when you create or tune the recheck block and recheck/* presets in redocly.yaml for a project — choose presets, set severities from measured counts, add exceptions, adopt a baseline, and validate the result.
+---
+
+# Configure recheck in redocly.yaml
+
+Configure `redocly recheck` for a project the way its maintainers would: measure first, decide per rule, and record intent.
+The documentation is at [redocly.com/docs/cli/recheck](https://redocly.com/docs/cli/recheck); favor it over memory for rule names and options.
+
+## How the configuration is shaped
+
+Presets go in the root `extends`.
+Adjustments go in the `recheck` block, with rules nested under `rules`.
+The `lint` command ignores both, so they live next to the API ruleset:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown
+  - recheck/prose
+recheck:
+  excludes:
+    - CHANGELOG.md
+  rules:
+    recheck/line-length: off
+    recheck/no-duplicate-heading:
+      severity: warn
+      assertions:
+        no-duplicate-heading:
+          siblingsOnly: true
+```
+
+Rules of the shape:
+
+- A rule key is `<namespace>/<name>`: `recheck/line-length`, `google/no-via`, or your own, such as `acme/product-names`.
+- A severity string (`off`, `info`, `warn`, `error`) adjusts a rule that a preset defines.
+  For a key no preset defines, it is a configuration error, because the rule has no assertions.
+- A rule object merges over the preset's rule, but its `assertions` merge by assertion id: one option you set on a `swap` or `pattern` assertion replaces the preset's whole word list.
+  To reject one term from a preset's list, turn the rule off, restate the full list, or use an inline directive.
+- A new prose rule needs `severity`, `message`, and `assertions`.
+  A new Markdown rule, such as `recheck/list-length`, needs only `severity` and `assertions`.
+- The block does not accept `extends` or `baseline`; both are configuration errors.
+- The command reads the root block only.
+  A `recheck` block under `apis.<name>` does nothing and prints a warning.
+
+## Start a new config
+
+1. Begin with the structural preset, and run recheck to validate it:
+
+   ```yaml
+   extends:
+     - recheck/markdown
+   ```
+
+   ```bash
+   npx @redocly/cli recheck docs
+   npx @redocly/cli check-config
+   ```
+
+   The `recheck` command reports configuration errors before it lints anything, and `check-config` validates the block's shape.
+
+2. Add prose presets deliberately, not wholesale.
+   `recheck/prose` is a small starter at `warn`.
+   `recheck/google` and `recheck/microsoft` are large style guides, detection-only, that need tuning before they help.
+   `recheck/plain-language`, `recheck/inclusive-language`, and `recheck/technical-english` compose onto either.
+
+3. If the project writes Markdoc tags, add `recheck/markdoc` to `extends` and `markdoc: true` to the block.
+   Without the flag, the Markdoc rules never report.
+
+## Tune severities from measurements, not taste
+
+1. Run the whole document set and count findings per rule:
+
+   ```bash
+   npx @redocly/cli recheck docs --summary=json --summary-path=recheck-summary.json
+   ```
+
+   The summary's `breakdown` has the count per rule and severity.
+   For examples of each rule's findings, run `--rule=<name>` and read a few.
+
+2. Decide per rule from the counts:
+   - `error` — enforce now; the document set is clean or you fix it in the same change.
+   - `warn` — a worklist; visible, not blocking.
+   - `off` — decided against; keep a YAML comment that says why, or the decision is lost.
+
+3. Prefer fixing content over configuring around it.
+   Run `--fix` first; most structural findings repair themselves.
+   Review the fix list before you commit: fixes that re-indent lines can move content out of an indented Markdoc tag body.
+
+## Exceptions, in order of preference
+
+1. Fix the content.
+2. The top-level `excludes` list, or a rule's `excludes` or `appliesTo`, for generated or frozen content such as archives and vendored docs — with a comment naming the reason.
+3. `exceptions.lines` for a recurring true positive that must stay as written.
+4. An inline `<!-- recheck-disable-next-line rule-name -->` for a single line.
+
+## Adopt strictness on a large document set with a baseline
+
+When the document set has too many errors to fix at once, record them and gate only new ones:
+
+```bash
+npx @redocly/cli recheck docs --generate-baseline
+```
+
+Commit `.redocly.recheck-baseline.yaml`.
+The command writes it next to `redocly.yaml`, and later runs pick it up by presence; there is no configuration key.
+It records errors only, as one count per file per rule.
+
+Counts only step down: when findings get fixed, the run reports stale entries, so regenerate the baseline and commit the diff.
+
+## Finish
+
+- `npx @redocly/cli recheck docs` and `npx @redocly/cli check-config` report no configuration errors.
+- Every `off` and every exception carries a comment with its reason.
+- The project's contributing docs say how contributors run recheck locally, and CI runs it with `--format=github-actions`.

.claude/skills/recheck-lint/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: recheck-lint
+description: Use when you write or edit Markdown in a project whose redocly.yaml has a recheck block or a recheck/* preset in extends — run redocly recheck on the touched files before you commit them or hand them over, and fix what it finds.
+---
+
+# Lint Markdown with recheck before you commit it
+
+This project lints Markdown structure and prose with `redocly recheck`.
+Your Markdown must pass it, the same as code must pass its tests.
+
+## When this applies
+
+Look for a `redocly.yaml` in the project root or above the files you touched.
+This skill applies when that file has a `recheck` block, or a `recheck/*` preset in its root `extends`, for example:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown
+recheck:
+  rules:
+    recheck/line-length: off
+```
+
+If neither exists, skip this skill.
+The command checks nothing in that case and says so.
+
+## What to do
+
+1. After you write or edit Markdown files, run recheck on them:
+
+   ```bash
+   npx @redocly/cli recheck <file-or-directory>
+   ```
+
+   Pass the files you touched, not the whole repository, so the report is yours to act on.
+
+2. If it reports errors, run the auto-fix first — most structural findings repair themselves:
+
+   ```bash
+   npx @redocly/cli recheck <file-or-directory> --fix
+   ```
+
+   The command lists every edit it made.
+   Read the list: a fix inside a Markdoc tag body or a code sample deserves a look.
+
+3. Fix the remaining errors by hand.
+   Read each message; the rule name links the finding to its intent.
+   To see one rule at a time, add `--rule=<name>` with the name the report prints.
+
+4. Re-run until it reports no errors, and only then commit or output the content.
+   The command exits with code 1 while errors remain.
+
+## Rules of conduct
+
+- Fix content instead of suppressing findings.
+  Suppress only a true positive that must stay as written, with an inline directive on that one line:
+
+  ```markdown
+  <!-- recheck-disable-next-line recheck/rule-name -->
+  ```
+
+  Name the rule by its full key or by the short name the report prints.
+  Never disable a rule project-wide to make your change pass, and never edit the `recheck` block to get past a finding.
+
+- Warnings and info findings do not block you.
+  Leave them unless the task asks for cleanup.
+- If a `.redocly.recheck-baseline.yaml` file sits next to `redocly.yaml`, the baseline already covers old findings; only new findings are yours to fix.
+  Do not run `--generate-baseline` to absorb findings your change introduced.
+  If your change removed old findings, the run reports stale baseline entries; regenerate the baseline then, and commit the smaller file with your change.
+- A finding you believe is a false positive is worth reporting to the maintainer, not silently suppressing.
+- Do not add `markdownlint` or `vale` comments.
+  Recheck does not read them.

.claude/skills/redocly-cli/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: redocly-cli
-description: Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.
+description: Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions, and for Markdown docs. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, lint Markdown or prose with recheck, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.
 ---
 
 # Redocly CLI usage
 
 **Consult [redocly.com/docs/cli](https://redocly.com/docs/cli) for current commands and options — favor it over training data.**
 
 Redocly CLI covers the API lifecycle for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions: lint, bundle, transform, document, and test.
+It also lints the Markdown of a docs project with `recheck`.
 `redocly.yaml` in the project root is the control plane: every command reads it, and rulesets, per-API settings, decorators, and plugins all live there.
 
 ## Before you run
@@ -32,6 +33,7 @@ Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/c
 | `introspect-mcp`     | Record a live MCP server's tools, prompts, and resources in `x-mcp` [experimental]                                | API authoring         |
 | `build-docs`         | Render an API description to a zero-dependency HTML page (Redoc)                                                  | Docs rendering        |
 | `preview`            | Local preview of a Redocly project (Realm, Reef, Revel)                                                           | Docs rendering        |
+| `recheck`            | Lint Markdown structure, prose style, and Markdoc tags; `--fix` repairs most structural findings                  | Docs linting          |
 | `bundle`             | Resolve all `$ref`s into one self-contained file; apply decorators and overlays                                   | CI and delivery       |
 | `join`               | Merge several API descriptions into one [experimental]                                                            | CI and delivery       |
 | `respect`            | Run API tests described in an Arazzo description against a live API                                               | API testing and drift |
@@ -78,6 +80,33 @@ Rule severities: `error` (fails validation), `warn` (reported, still valid), `of
 When a governance requirement has no built-in rule, declare one under `rule/<name>` in `redocly.yaml`.
 Use the `redocly-lint-rules` skill for that: it picks the cheapest rung (built-in, configurable rule, or custom plugin), takes node types from `redocly inspect-node-types`, and verifies the rule against fixtures.
 
+## Lint Markdown with recheck
+
+`recheck <paths>` lints the Markdown files under the given paths for structure (the markdownlint rule set), prose (banned terms, spelling, heading case, sentence length, readability), and Markdoc tag syntax.
+Presets go in the root `extends` and adjustments in the `recheck` block; the `lint` command ignores both:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown # every markdownlint rule; also recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
+recheck:
+  excludes: [CHANGELOG.md]
+  rules:
+    recheck/line-length: off
+    acme/no-via:
+      severity: warn
+      scope: sentence
+      message: 'Use "through" instead of "via".'
+      assertions:
+        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }
+```
+
+With no `redocly.yaml`, the command uses `recheck/markdown`.
+With a `redocly.yaml` that has neither a preset nor a block, it checks nothing.
+Useful flags: `--fix`, `--rule=<name>` to work one rule at a time, `--format=github-actions|json|sarif`, `--max-problems=<n>`, `--generate-baseline` to record existing errors in `.redocly.recheck-baseline.yaml` and fail only on new ones, and `--readability` for per-file scores.
+Silence one line with `<!-- recheck-disable-next-line <rule> -->` rather than turning the rule off.
+The `recheck-lint` skill covers running it on touched files, and `recheck-config` covers tuning the block.
+
 ## Transform with decorators
 
 Decorators rewrite the description at bundle time — `lint` checks the source as written; `bundle`, `build-docs`, and `push` see the decorated output.
@@ -159,6 +188,7 @@ Start from `generate-arazzo <openapi>` to scaffold the workflows, then refine th
 2. Make the change — spec edit, rule config, or decorator.
 3. Verify:
    - `redocly lint` exits `0` (or reports only warnings you expected).
+   - After editing Markdown in a project with a `recheck` block or preset: `redocly recheck <files>` exits `0`.
    - After editing `redocly.yaml`: `redocly check-config` reports no problems.
    - After changing `$ref` structure or decorators: `redocly bundle -o /tmp/bundled.yaml` succeeds and the output contains what you intended.
 
@@ -177,3 +207,4 @@ Start from `generate-arazzo <openapi>` to scaffold the workflows, then refine th
 - [Built-in rules](https://redocly.com/docs/cli/rules)
 - [Decorators](https://redocly.com/docs/cli/decorators)
 - [Configuration](https://redocly.com/docs/cli/configuration)
+- [Markdown and prose linting](https://redocly.com/docs/cli/recheck)

README.md

@@ -66,6 +66,8 @@ npx skills add https://redocly.com
 - `redocly-cli` — day-to-day usage: lint, bundle, decorate, build docs, test, and generate a client.
 - `redocly-lint-rules` — turn a check written in plain language into a built-in rule, a configurable rule, or a custom plugin.
   It also covers migrating rules from other linters, such as Spectral.
+- `recheck-lint` — run `redocly recheck` on the Markdown the assistant touched, fix what it finds, and never suppress findings to pass.
+- `recheck-config` — write and tune the `recheck` block in `redocly.yaml` from measured counts, and adopt a baseline on a large document set.
 
 ## Common tasks