Redocly/redocly-cli / .claude/skills/recheck-config
recheck-config
UnverifiedUse 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; 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:
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 asacme/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
assertionsmerge by assertion id: one option you set on aswaporpatternassertion 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, andassertions. A new Markdown rule, such asrecheck/list-length, needs onlyseverityandassertions. - The block does not accept
extendsorbaseline; both are configuration errors. - The command reads the root block only.
A
recheckblock underapis.<name>does nothing and prints a warning.
Start a new config
-
Begin with the structural preset, and run recheck to validate it:
extends: - recheck/markdownnpx @redocly/cli recheck docs npx @redocly/cli check-configThe
recheckcommand reports configuration errors before it lints anything, andcheck-configvalidates the block's shape. -
Add prose presets deliberately, not wholesale.
recheck/proseis a small starter atwarn.recheck/googleandrecheck/microsoftare large style guides, detection-only, that need tuning before they help.recheck/plain-language,recheck/inclusive-language, andrecheck/technical-englishcompose onto either. -
If the project writes Markdoc tags, add
recheck/markdoctoextendsandmarkdoc: trueto the block. Without the flag, the Markdoc rules never report.
Tune severities from measurements, not taste
-
Run the whole document set and count findings per rule:
npx @redocly/cli recheck docs --summary=json --summary-path=recheck-summary.jsonThe summary's
breakdownhas the count per rule and severity. For examples of each rule's findings, run--rule=<name>and read a few. -
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.
-
Prefer fixing content over configuring around it. Run
--fixfirst; 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
- Fix the content.
- The top-level
excludeslist, or a rule'sexcludesorappliesTo, for generated or frozen content such as archives and vendored docs — with a comment naming the reason. exceptions.linesfor a recurring true positive that must stay as written.- 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:
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 docsandnpx @redocly/cli check-configreport no configuration errors.- Every
offand 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |