Skip to content

Add skillfile doctor to diagnose common setup problems #62

@eljulians

Description

@eljulians

Every good CLI has a doctor command (brew doctor, flutter doctor). Right now if something's off with your setup (missing token, stale cache, git not on PATH) you only find out when a command fails with a cryptic error. A doctor command that checks everything upfront would save a lot of headaches.

$ skillfile doctor
  ✓ Skillfile found
  ✓ Skillfile.lock found (8 entries)
  ✗ GitHub token not configured (60 req/hr limit)
    → Run: skillfile init (or set GITHUB_TOKEN)
  ✓ git found on PATH (needed for resolve)
  ✓ Install targets: claude-code (global), cursor (local)
  ✗ cursor not detected on system
    → Cursor skills dir ~/.cursor/skills/ doesn't exist
  ✓ .skillfile/cache/ exists (8 entries cached)
  ✗ 2 entries missing from cache
    → Run: skillfile sync
  ✓ No active conflicts

Things it should check:

  • Skillfile + lock file exist
  • GitHub token configured (env var, gh CLI, or config file)
  • git on PATH (needed for resolve)
  • Install targets point to valid platforms
  • Target directories actually exist on disk
  • Cache state (entries cached, any missing)
  • No stale conflict state (.skillfile/conflict)
  • Patch files are well-formed

Pure read-only, no network calls, no side effects. Just diagnostics + actionable suggestions when something's wrong.

Implementation lives in cli/src/commands/doctor.rs. Most of the building blocks already exist: token detection (sources/src/http.rs), adapter lookup (deploy/src/adapter.rs), lock/cache reading (core/src/lock.rs). It's mostly wiring them together and formatting the output

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions