Running doctor
Diagnose config, auth, agents, links, gitignore, and lockfile health — and read the per-check status and suggested fix.
When something feels off — installs aren't showing up in an agent, git status
isn't clean, or auth is acting strange — skillhub doctor is the first thing to
run. It checks the health of a scope end to end and, for each check, tells you the
status and a suggested fix.
skillhub doctorWhat it checks
Doctor runs a fixed set of checks and reports each one:
| Check | What it verifies |
|---|---|
config | Your configuration is present and readable. |
auth | You're authenticated with the registry. |
agents | Detected agents and their skills directories. |
links | Symlink (or copy) health for installed skills. |
gitignore | The managed .gitignore block is intact. |
lockfile | The lockfile matches what's actually on disk (no drift). |
Reading the report
Doctor reports an overall status — ok, warn, or fail — plus a
per-check breakdown. Each check carries:
- a
status(ok|warn|fail), - a
detailexplaining what it found, and - a
fix(when there's a suggested next step) — ornullwhen nothing needs doing.
Work top to bottom: any check that isn't ok comes with a detail and usually a
fix telling you exactly what to run or change.
The gitignore, links, and lockfile checks exist to protect the core
guarantee that SkillHub never dirties your repo. If any of them flags,
run its suggested fix to restore the managed .gitignore block and re-align
links with the lockfile.
Checking the global scope
By default doctor checks the project you're in. Add --global to diagnose the
machine-global scope instead:
skillhub doctor --globalJSON output
With --json, skillhub doctor returns a data object containing:
scope—project|global.status—ok|warn|fail.checks[]— each{ id (config | auth | agents | links | gitignore | lockfile), label, status (ok | warn | fail), detail, fix (string | null) }.