doctor
Run Vite Doctor diagnostics for Vite, Vue, Nitro, and Nuxt projects and use stable diagnostic codes to guide fixes. Use before review on framework projects, when Doctor/Vite Doctor/Nuxt Doctor/diagnostics are requested, or when framework-specific runtime issues are suspected.
How do I install this agent skill?
npx skills add https://vite-doctor.onmax.me --skill doctorIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
Doctor
Quick Start
Run Doctor from the target project root:
pnpm dlx vite-doctor . # or npx/bunx/yarn dlx
For Nuxt projects, the recommended workflow is:
pnpm add -D vite-doctor
export default defineNuxtConfig({
modules: ["vite-doctor/nuxt"],
});
pnpm nuxt doctor
pnpm nuxt doctor --max-warnings 0 fails a CI job on Nuxt 4.6 and later. Nuxt 4.1
to 4.5 exit 0 after nuxt doctor whatever Doctor finds; there, use
pnpm vite-doctor . --host-extensions --max-warnings 0 and pnpm vite-doctor migrate .
when the exit code matters. Add --strict (or "extends": "strict" in config) to run
every activated Rule Pack's strict preset, which adds noisier and opinionated Rules.
The standalone CLI also works for Nuxt one-off runs, CI fallback, or monorepo scans.
Never run pnpm doctor or npm doctor to run Doctor. Both commands run the package manager's own health check, which passes without running Doctor. If the project defines a doctor package script, run pnpm run doctor or npm run doctor. Otherwise run pnpm vite-doctor ..
In a Nuxt project, a report that names a missing .nuxt/doctor.manifest.json ignored the project's doctor options. Run nuxt prepare, then rerun. Doctor does not need a build.
Workflow
- Use
vite-doctor . --changed --format agentfor uncommitted work. Usevite-doctor . --since <base-ref> --format agentfor a committed branch or pull request. Run Doctor without either scope flag when Git is unavailable or the user asks for a project audit. - Read
status,scope, and every Diagnostic's code, message, remediation, confidence, relative location, evidence, and optional edit plan. - Work only on Diagnostics owned by the requested change. Do not widen the task to unrelated findings.
- Apply the smallest fix that satisfies the remediation and preserves project conventions. Treat structured edit plans as proposed edits, not permission to skip review.
- Replace the
<rule>item incommandArgs.verifywith the Diagnostic's Rule ID. Execute the first array item with the remaining items as literal arguments, without a shell, fromproject.cwd. - Execute
commandArgs.rerunthe same way before finishing. Report remaining Diagnostics or incomplete evidence exactly. If only shell execution is available,commandscontains quoted POSIX command templates; replace placeholders with correctly quoted literal arguments before running them. - Use the Diagnostic Reference URL when the inline remediation is ambiguous or framework behavior needs confirmation. Routine fixes should not require network access.
Rules
- Use
vite-doctorfor Vite, Vue, Nitro, and Nuxt projects; do not invent framework-specific packages or binaries. - Treat Rule IDs as execution/filtering selectors.
- Treat Diagnostic Codes as the stable remediation identity for docs, fixes, and user-facing explanations.
- Diagnostic Codes with non-built-in prefixes (anything other than
DOC,NITRO,NUXT,PKG,SHAD,TS,VITE,VUE) come from Doctor Extensions shipped by libraries or the project. Use thedocsURL in the Diagnostic; do not look for them in the Doctor Diagnostic Reference. - In Nuxt projects, Nuxt modules can register Doctor Extensions.
nuxt doctorloads them; with the direct CLI, add--host-extensionsto see the same Diagnostics. Keep that flag incommandArgsreruns. - To write or test custom Rules, follow https://vite-doctor.onmax.me/extending (
vite-doctor/extension,vite-doctor/testkit). - When you will run Doctor several times in one project, set
VITE_DOCTOR_SERVER=1for those commands. Later runs reuse a long-lived Doctor process and print the same report;vite-doctor server stopends it. - Prefer
--format agentfor remediation work. Use JSON for full run metadata and SARIF for code-scanning integrations. - An explicit
--formatis deterministic. Do not depend on automatic runtime recognition in scripts. - Use Doctor terms consistently: Doctor, Rule, Rule Pack, Diagnostic Code, and Diagnostic.
- Keep code edits scoped to reported Diagnostics unless the user asks for broader cleanup.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vite-doctor.onmax.me/doctor">View doctor on skillZs</a>