The react-doctor skill is a thin wrapper that runs npx react-doctor@latest and reads its score, and that is its main design decision: the rules live in a CLI, not in the prompt. The SKILL.md is 732 words, uses version: "1.2.0", and its longest section explains which flags to pass rather than how to review React. On skills.pub it comes from a repository with 15,164 stars.
What does the skill actually run?
Four commands, each mapped to a situation:
| Situation | Command | What you get |
|---|---|---|
| Just changed React code | npx react-doctor@latest --verbose --scope changed | Issues introduced vs. the base branch |
| General cleanup | npx react-doctor@latest --verbose | Full-codebase scan, errors then warnings |
| UI design audit | npx react-doctor@latest design --verbose | Only design-tagged rules |
| Runtime perf problem | npx react-doctor@latest scan <url> --format json | A recorded DevTools trace |
The first row is the one that changes behaviour. The skill does not ask the agent to review a diff; it asks the agent to run a command and compare a number: "Run npx react-doctor@latest --verbose --scope changed and check the score did not regress. If the score dropped, fix the regressions before committing."
That converts code review into a regression check with a pass/fail signal. The output is a 0–100 health score, which the SKILL.md states in its opening paragraph.
What does the score measure?
Four categories, named in the description rather than the body: security, performance, correctness, and architecture — plus lint, accessibility and bundle size in the trigger conditions. The design subcommand carves out a subset: UI composition, typography, interaction, accessibility and motion.
The score is the interface. It is coarse enough that an agent can reason about "did this get worse" without reading every finding, which is exactly the property that makes it usable inside a commit loop.
Why does it fetch a playbook over the network?
This is the unusual part. For the full /doctor triage workflow, the skill tells the agent to run:
curl --fail --silent --show-error \ --header 'Cache-Control: no-cache' \ https://www.react.doctor/prompts/react-doctor-agent.md and then "follow every step in it". The stated reason is maintainability: "Updating the prompt at its source updates every agent on its next fetch — no skill reinstall needed."
| Design choice | Consequence |
|---|---|
| Playbook lives on the web | Fixes reach every installed copy without a reinstall |
Cache-Control: no-cache | Always the current version, never a stale one |
| Per-rule prompts fetched on demand | The playbook pulls the recipe for the rule it is fixing |
| Requires network | The full triage flow cannot run offline |
That is a deliberate trade: freshness purchased with a network dependency. If you work offline or in a locked-down CI, the regression-check path still works because npx needs the registry, but the full triage does not.
What does the runtime-perf mode do that is interesting?
npx react-doctor@latest scan <url> opens "an isolated system Chrome profile", records a DevTools trace while the user reproduces the interaction, and "flashes purple outlines with component names as React renders". It stops when the user presses Enter, and writes a local .json.gz trace.
Two constraints in the skill are worth quoting because they are security-relevant:
- "Never ask for cookies or copy the user's browser profile." If authenticated state is needed, use
--cdp <remote-debugging-url>with a Chrome already running under remote debugging. - "Treat the trace as sensitive local application data and never upload it without explicit permission."
A performance trace contains URLs, possibly tokens in query strings, and the full component tree. Marking it as non-uploadable by default is the right call, and it is stated as a rule rather than a suggestion.
How does rule configuration work?
Through the CLI, not the prompt: npx react-doctor@latest rules explain <rule>, then rules disable, rules set, rules category, or rules ignore-tag. These edit doctor.config.* or the reactDoctor field in package.json.
That means the skill never invents its own configuration format. Whatever the CLI writes is what a human reviewer would also see in the repo — a property worth checking in any skill that wraps a tool.
The scope flags are the real feature
| Flag | Behaviour |
|---|---|
--scope changed | Only issues introduced vs. the base branch |
--scope contextual | Findings in modified functions, JSX elements or files |
--scope lines | Only the changed lines |
--scope full | The default when no scope is given |
The difference between changed and contextual is subtle and the skill documents it with a concrete example: for exhaustive-deps, an edit inside the hook call can surface a finding on an unchanged dependency array, because the rule owns a wider node than the changed line. That level of detail about its own scoping is what makes the flag usable instead of mysterious.
--scope contextual --base origin/main is the recommended setting when a team wants existing findings in code they are actively editing.
Is the skill or the CLI the product?
The CLI. The skill contributes three things the CLI cannot do alone: it triggers on the right moment ("when finishing a feature, fixing a bug, before committing React code"), it tells the agent to fix regressions before committing, and it routes to the right subcommand based on what the user asked for.
That is a good division. The rules are testable and versioned in one place; the skill is a small amount of judgement about when to run them.
Two details that are easy to miss
Version drift. The skill declares version: "1.2.0" while the npm package it shells out to is 0.9.23. The playbook pins the runtime it expects through an environment variable, not through the skill's version field, so the two numbers are not meant to match. That is fine as long as the playbook is the thing that decides, but it means the skill's version: tells you nothing about which CLI behaviour you will get.
The license is not plain MIT. GitHub reports NOASSERTION for this repository, and reading the LICENSE file explains why: it is MIT plus two clauses that require written permission — one for using the code as machine-learning training or evaluation data, and one for selling it as a paid, hosted, or managed service. If you plan to vendor the detector into a commercial product, read the LICENSE first.
The installed copy may be stale. The repository ships the same skill twice. skills/react-doctor/ is the current 732-word version with the runtime-performance section, --scope contextual, --baseline, and the GitLab warning-status section. .agents/skills/react-doctor/ is a 377-word older copy missing all of those. Both claim version: "1.2.0". Check which one your install actually produced before relying on the flags described above.
What to check before adopting it
- Run
npx react-doctor@latest --scoreon a clean tree and record the number. That is your baseline; every later comparison is relative to it. - Run with
--scope changedafter a one-line edit and confirm the score moves. If it does not, the scoping is not picking up your changes. - Try the full
/doctorflow with the network off. It should fail at thecurlstep — confirm it fails visibly rather than continuing with a partial playbook. - Confirm
doctor.config.*is committed, so rule changes are reviewable.
The command set, flags, version, network behaviour and the two security constraints were read from the repository on 2026-11-20: SKILL.md and the playbook it fetches. The scoring internals are inside the published npm package and were NOT VERIFIED beyond what the skill file states.