
react-doctor
Use when finishing a feature, fixing a bug, before committing React code, or when the user types /doctor, asks to scan, triage, or clean up React diagnostics. Covers lint, accessibility, bundle size, architecture. Includes a regression check and a full local-triage workflow that fetches the canonical playbook.
- Installs
- 20.7K
- Last 24h
- +213
- Trending rank
- #1209
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/millionco/react-doctor --skill react-doctor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads react-doctor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
React Doctor
Scans React codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score.
After making React code changes:
Run npx react-doctor@latest --verbose --scope changed and check the score did not regress.
If the score dropped, fix the regressions before committing.
For general cleanup or code improvement:
Run npx react-doctor@latest --verbose (the default --scope full) to scan the full codebase. Fix issues by severity — errors first, then warnings.
For a focused UI design audit:
Run npx react-doctor@latest design --verbose. This selects only design-tagged UI composition, typography, interaction, accessibility, and motion rules, including focused rules that remain opt-in during a general health scan.
For runtime performance problems:
Run npx react-doctor@latest scan <url> --format json in an interactive terminal. React Doctor opens an isolated system Chrome profile, records a DevTools trace while the user reproduces the slow interaction, and flashes purple outlines with component names as React renders. It stops when they press Enter. Read the structured summary first, then inspect the returned local .json.gz trace for CPU, browser, and React component evidence.
If the user needs their authenticated browser state, use --cdp <remote-debugging-url>. This requires Chrome to already be running with remote debugging. Never ask for cookies or copy the user's browser profile. Treat the trace as sensitive local application data and never upload it without explicit permission.
/doctor — full local triage workflow
When the user types /doctor, says "run react doctor", or asks for a full triage / cleanup pass (not just a regression check), fetch the canonical local-triage playbook and follow every step in it:
curl --fail --silent --show-error \
--header 'Cache-Control: no-cache' \
https://www.react.doctor/prompts/react-doctor-agent.md
The playbook is the single source of truth — a scan → filter → triage → fix → validate loop that edits the working tree directly (never commits, never opens PRs). Updating the prompt at its source updates every agent on its next fetch — no skill reinstall needed.
Pair it with the matching per-rule prompts at https://www.react.doctor/prompts/rules/<plugin>/<rule>.md (fetched on demand inside the playbook) so each fix uses the canonical, reviewer-tested recipe.
Use --scope contextual --base origin/main when a team wants existing findings
in the code it is editing. Rules can select an element, function, file, or an
explicit set of related nodes. For exhaustive-deps, edits in the hook call or a
resolved local callback can surface a finding on an unchanged dependency array.
Rules without wider ownership keep changed-line filtering.
Configuring or explaining rules
When the user wants to understand a rule, disagrees with one, or wants to disable / tune which rules run (not fix code), read references/explain.md and follow it. Start with npx react-doctor@latest rules explain <rule>, then apply the narrowest control via npx react-doctor@latest rules disable|set|category|ignore-tag …, which edits your doctor.config.* (or package.json#reactDoctor).
Command
npx react-doctor@latest --verbose --scope changed
| Flag | Purpose |
|---|---|
. | Scan current directory |
--verbose | Show affected files and line numbers per rule |
--scope changed | Only report issues introduced vs the base branch (default: full) |
--scope contextual | Report findings in modified functions, JSX elements, or files, as selected by each rule |
--scope lines | Only report issues on the changed lines |
--score | Output only the numeric score |
design | Run only the focused UI design diagnostics |
Reuse a base scan
Save a complete --json scan, then pass --baseline base-report.json to report only new findings. This also works with --scope changed. Use the same version and rules for both scans. Findings are grouped by rule and file path, following Git renames. Only increases in each group's count are reported; groups without an increase skip location matching. Fingerprints, message similarity, and Git-adjusted line distance select the added findings. Formatting and edits that keep the same counts report no new findings. Saved reports must use the same textComponents, rawTextWrapperComponents, and respectInlineDisables settings. Regenerate the base report after changing these settings, or use a Git comparison. Older reports without fingerprints or sourceFilterConfigHash must be regenerated.
GitLab warning status
For GitLab CI, --warning-exit-code 123 returns 123 for non-blocking warnings. Pair it with allow_failure: { exit_codes: 123 }. Errors still return 1. Accepts integers from 2 to 255. --blocking warning still returns 1. --blocking none or --score skips this warning signal.
FAQ
What does the react-doctor skill do?
Use when finishing a feature, fixing a bug, before committing React code, or when the user types /doctor, asks to scan, triage, or clean up React diagnostics. Covers lint, accessibility, bundle size, architecture. Includes a regression check and a full local-triage workflow that fetches the canonical playbook.
How do I install react-doctor?
Run npx skills add https://github.com/millionco/react-doctor --skill react-doctor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/react-doctor/ (personal) or .claude/skills/react-doctor/ (project).
Which AI agents can use react-doctor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is react-doctor safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains react-doctor?
It is published by millionco in millionco/react-doctor. It has 20,673 recorded installs.
More from millionco/react-doctor
improve-react
millionco/react-doctor
Survey a whole React codebase as a senior React engineer, using React Doctor's scan as evidence, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the React code", "audit this codebase", "make this app faster / more robust", or wants a roadmap of fixes rather than a review of a single diff. For a regression check or a fix-it-now pass, use the react-doctor skill instead.
deslop
millionco/react-doctor
Simplify and refine recently modified code while preserving functionality. Use when asked to "deslop", "clean up code", "simplify code", or after making changes that could benefit from refinement.
rule-validate
millionco/react-doctor
Validate an implemented React Doctor rule before merge. Use after focused tests pass to review detector correctness, inspect open-source hits, run pull request parity, add regression coverage, prepare a changeset, write pull request copy, or address review findings.
find-similar-functions
millionco/react-doctor
Use truffler to find similar or pre-existing JavaScript/TypeScript symbols before implementing new code, especially helpers, utilities, parsers, formatters, scanners, fuzzy matchers, and other reusable functions. Agents should use this skill whenever they are about to add or refactor functionality in a JS/TS repository and need to avoid duplicating existing code, even if the user does not explicitly mention deduplication.
rule-research
millionco/react-doctor
Define a precise React Doctor rule contract before implementation. Use when validating a rule idea, collecting official or open-source evidence, identifying false-positive traps, choosing detector precision, or setting first-version boundaries.
rule-writing
millionco/react-doctor
Implement React Doctor rules from a validated contract. Use when writing oxlint rules, planning syntax or control-flow detection, designing adversarial tests, reusing syntax tree utilities, or updating rule registration.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
ui-taste
uizze.sh
Give your coding agent better UI taste. Build and polish web and iOS interfaces with Uizze's anti-ui-slop playbooks and optional real-product references. Use for UI design, implementation, redesign, critique, or a final visual review in Claude Code, Codex, Cursor, or Copilot.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.