React Doctor Skill

A CLI is only useful if it actually runs. So we spent a lot of time on the part that makes React Doctor run at the right moment: the skill.

The idea is simple. Instead of you remembering to run a linter, your coding agent knows to run React Doctor when it matters. After finishing a feature, after fixing a bug, after touching React code. Then it acts on what it finds.

This is how it got here, and how to use it today.

Why a skill?

Agents are great at writing code and bad at remembering process. You can tell an agent "run the CLI when you're done" and it works once, then forgets next session.

A skill makes that stick. It lives in the project, the agent reads it as part of its context, and the quality loop just happens.

The skill itself is about as minimal as it gets. A tiny plain-Markdown file that tells the agent when and how to run React Doctor. No plugin, no SDK, just text the agent already knows how to read.

How it works

Install it into any supported agent:

npx react-doctor@latest install

The installer finds your agents (Claude Code, Cursor, and others), asks which ones to install for, and drops the skill into the right project directory.

The skill is plain Markdown. It tells the agent to run one diff-scoped command during normal coding:

npx react-doctor@latest --verbose --diff

That's the whole loop. The agent makes changes, runs React Doctor on the diff, reads the findings, and fixes them. You don't paste instructions every time.

Full triage on demand

The skill also gives your agent a /doctor command. Instead of a single scan, it pulls React Doctor's canonical playbook and walks the whole triage: scan, group by severity, fix the errors first, re-run, and stop when the score stops moving. Reach for it when you want a deliberate cleanup pass rather than the background loop.

Why it works

The skill only works because of what's underneath it. React Doctor's output is deterministic and machine-readable, so the same commit always gives the same findings. That's the property an agent needs before it'll trust the loop.

There's also a lot for it to find. React Doctor ships native ports of the React, jsx-a11y, react-hooks, and "you might not need an effect" rule sets, over a hundred rules in all, each with a built-in recommendation. So when the agent reads a diagnostic, it gets a real fix to make, not just a label (announced on X).

Hooks, when you want them

The skill covers the in-session loop. For everything around it, React Doctor can install hooks too.

A non-blocking Git pre-commit hook keeps findings visible without blocking your commits:

react-doctor --staged --fail-on none

Native Claude Code and Cursor hooks run after agent edits and feed findings straight back into the session, so the agent reacts right away:

npx react-doctor@latest install --agent-hooks

Native hooks are opt-in. Use them when you want aggressive self-correction, leave them off when you'd rather keep context usage low and scan by hand.

Try it

Install the skill and let your agent do its thing:

npx react-doctor@latest install --yes

The best part is you mostly stop thinking about it. The agent runs the scan, reads the score, fixes what it can, and your codebase trends in the right direction without anyone remembering to look.