`bsk doctor` reports "agent skill up to date" even when the installed skill differs from upstream main - no version or source visibility

[i-iooi-i]

Environment

• bsk CLI: 0.2.1 (bsk-v0.2.1-x86_64-pc-windows-msvc.zip), published 2026-09-09T06:34:56Z
• OS: Windows 11 x64
• Agent harness: WorkBuddy (~/.workbuddy/skills/browser-skill/SKILL.md)
• Extension connected, daemon protocol 1.1, the rest of doctor is fully green

Summary

bsk doctor prints:

ok    agent skill up to date       up to date in 1 harness(es)

As far as I can tell, "up to date" here means only "the bundled skill is installed and CLI-managed". It does not mean "the installed skill matches upstream main". No version, commit, or provenance is shown anywhere, so an agent (or a human) reading doctor has no way to notice that the skill it is following is a week behind the repository.

Evidence

What	Size	Notes
skill/SKILL.md at tag cli-v0.2.1	9562 B	the version bundled into the 0.2.1 binary
Installed on disk	9746 B	9562 B + 184 CRLF (the file is 184 lines, all CRLF) -> byte-identical to the tag
skill/SKILL.md on main today	15126 B	+5380 B vs installed

The section structure is not a small edit, it is a rewrite:

installed (cli-v0.2.1)                    main (today)
---------------------------------------   -------------------------------
## Required lifecycle                     ## Before starting a session
## Work toward one observable goal        ## Task workflow
## Observe, act, observe                  ## Read and interact
## Respect the Agent Window boundary      ## Borrowing and browser settings
## Ask the human when needed              ## Human steps and recovery
## Command inventory                      ## Screenshots and Canvas
## File transfer                          ## Files and other tools
## Recover without wandering

skill/SKILL.md kept changing after the CLI release - the most recent commits touching it are c8f9d63 (2026-09-16T11:47Z, "docs: reuse existing daemons and verify startup readiness"), b433d37 (2026-09-16T11:30Z) and 3af3fe3 (2026-09-15T11:15Z).

What I tried

I installed the upstream main file over the bundled one:

bsk install-skill --harness workbuddy --source <main SKILL.md> --force

On-disk size went 9746 -> 15126 B, and doctor still reported:

ok    agent skill up to date       synced 1 harness(es): workbuddy

So the check compares installed content against neither the bundled copy nor upstream. (I restored the bundled version afterwards and doctor went back to up to date in 1 harness(es).)

Why this matters for agents

The skill file is the operating manual the agent follows, and doctor is the only health signal it gets. When the two drift apart the failure mode is silent:

• The agent trusts doctor and assumes it holds the current instructions.
• An operator reading the repository sees different instructions than the agent is actually following, and reports stop reproducing.
• The concrete trap I hit: main documents bsk screenshot --session <id> --full-page --out page.png (around lines 199-218), but bsk 0.2.1 screenshot --help has no --full-page flag at all (only --json --session --quiet --tab-id --ref -v --out), so the call fails with unexpected argument. Nothing in doctor hints at that mismatch.

Suggestions

Any one of these would have saved me the guesswork, roughly in the order I would value them:

1. Stamp the skill with provenance. Write a version/commit into the installed skill (frontmatter, or a sidecar file under ~/.bsk/), and have doctor show it, e.g. ok agent skill browser-skill 0.2.1 (bundled, cli-v0.2.1).
2. Narrow the wording or add an explicit check mode. agent skill installed or skill present would not imply "current". A bsk install-skill --check that reports bundled vs installed vs upstream without writing would be ideal for agents.
3. Offer an update path. --source <path> already works, it just requires the caller to fetch the file. Something like bsk install-skill --from-upstream (or having bsk upgrade also refresh the skill) would close the loop.
4. Version-gate the docs. Where main documents a flag that older CLIs lack (--full-page here), a "requires CLI >= x.y" note would avoid the unexpected argument dead end.

Severity

Low - this is an observability gap rather than a broken flow, and everything else has been solid. Filing it mainly because doctor is the one command every agent runs, so its wording carries a lot of weight. Also related to #265, which I filed earlier today.