/skill-doctor fails on Remote Control, gives a false explanation, then returns an empty report even when run correctly

Status Open
Maintainer reply None cached
Activity 0 comments · opened Sep 12, 2026

Summary

/skill-doctor (announced in the Sept 11 Claude Code newsletter, docs at
https://code.claude.com/docs/en/skills#find-unused-skills) failed for me four times in a row
across three environments. Three of the failures are arguably user error / documented behavior
(see below), but the fourth — done exactly as the documentation instructs — returned an empty
report with no usable information, and one of the earlier failures produced a confidently wrong
explanation from the assistant despite the correct explanation already being printed in the same
turn.

Environment

  • Claude Code v2.1.269 (Sonnet 5, high effort, Claude Max)
  • macOS, both a native terminal and a Claude Code session running as the VS Code extension
  • Also tested via the Claude mobile app (Remote Control)

Attempt 1 — Claude app on phone (Remote Control)

Ran /skill-doctor. Claude Code correctly printed the documented Remote Control message:

Skill usage reports are not available on this connection.

This matches the documented behavior at
https://code.claude.com/docs/en/errors#skill-usage-reports-are-not-available-on-this-connection
exactly, word for word — so the system got this right.

However, the assistant's own reply in that same turn ignored that correct, just-printed system
message and asserted instead:

There's no skill-doctor command installed — nothing by that name in the public, example, or plugin skill directories.

It went on to recommend skill-creator as "the closest thing available" and offered to build a
skill-doctor skill from scratch, as if the command didn't exist at all. This is a materially
wrong diagnosis, produced immediately after — and contradicting — the correct, documented output
sitting one line above it in the same response.

Attempt 2 — terminal opened from inside the phone app

Same failure as attempt 1 (this is presumably still routed as a Remote Control connection, even
though it's "a terminal").

Attempt 3 — Claude Code session running as the VS Code extension

Same failure. Not obviously "Remote Control from your phone or browser" by any plain reading, but
apparently still doesn't qualify as "the terminal on the machine where the session is running."

Attempt 4 — native terminal, after updating to latest

After updating ("Got 68 features, 412 bugfixes, and 153 other changes"), ran /skill-doctor in an
actual local terminal window. This time it correctly routed to the Plugins → Stats tab, with a
note: "/skill-doctor moved — skill usage and context costs now live in this Stats tab." Under
"Skills loaded this session," it reported:

(no skills loaded)

That was the entire report — no cost figures, no usage counts, nothing to act on. The newsletter's
pitch was "see what each of your skills costs you in context and how often Claude actually
invokes it" — language that reads like a usage history, not a per-session-so-far tally of zero
because the session had just started. Four attempts in, I still have no way to tell which of my
skills are worth keeping, which was the entire point of running the command.

What I'd like clarified / fixed

  1. Should a VS Code extension session and/or a terminal launched from inside the mobile app be

treated the same as "the terminal on the machine where the session is running"? If not, the
docs and/or the in-product messaging could say so explicitly, since both looked like valid
local sessions to me.

  1. When /skill-doctor is blocked by the Remote Control connection check, the assistant should

not go on to contradict that correct system output with a fabricated explanation in the same
reply.

  1. The Stats tab report should make clear what window it's counting (this session only vs. a

longer usage history) — "no skills loaded" reads very differently depending on which one it
means, and nothing in the UI disambiguates it.

Wrote up the full walkthrough with screenshots here, if useful for context:
https://mistertranslation.com/notebook/not-available-on-this-connection.html

View original on GitHub ↗