Redocly/redocly-cli / .claude/skills/recheck-lint
recheck-lint
UnverifiedUse 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:
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
-
After you write or edit Markdown files, run recheck on them:
npx @redocly/cli recheck <file-or-directory>Pass the files you touched, not the whole repository, so the report is yours to act on.
-
If it reports errors, run the auto-fix first — most structural findings repair themselves:
npx @redocly/cli recheck <file-or-directory> --fixThe command lists every edit it made. Read the list: a fix inside a Markdoc tag body or a code sample deserves a look.
-
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. -
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:
<!-- 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
recheckblock 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.yamlfile sits next toredocly.yaml, the baseline already covers old findings; only new findings are yours to fix. Do not run--generate-baselineto 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
markdownlintorvalecomments. Recheck does not read them.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |