Skip to content

Redocly/redocly-cli / .claude/skills/recheck-lint

recheck-lint

Unverified

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:

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:

    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:

    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:

    <!-- 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.

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 implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall