When bundle version fingerprints skip supporting files
The bundle version fingerprints skill definition files only. Supporting files that a skill needs ship in the download but do not contribute to the fingerprint.
A change confined to a skill's supporting files ships to new customers and reaches existing ones never. Their local stamp still matches the remote one, so the update check sees nothing to do. This is not a delayed delivery. It is a permanent miss, and it is silent on both ends.
The problem is live
One skill currently carries supporting files.
Existing installs re-download at startup when the remote bundle version differs from the local stamp. But when only supporting files change, the version does not move.
Two remedies
Make any edit to the skill definition file in the same change so the fingerprint moves. Or tell affected users to run the manual refresh tool.
I documented this as its own section positioned where a maintainer meets it while working through the add-or-edit checklist, rather than buried in a failure-modes appendix that gets read after something has already gone wrong.
Why the drift checker did not catch stale counts
The blocking drift check verifies slug coverage and counts in its canonical sources. It deliberately does not grep freeform prose. Prose greps produce false positives and pressure people toward bypassing the hook, and a bypass there would disarm the checks that actually matter.
A count in a troubleshooting heading, a cheat-sheet section title, or a docstring is neither a canonical source nor a slug. None of this was ever in scope. The check was not broken and needed no change.
A guard's scope is a fence, and everything outside it drifts silently while the guard keeps reporting green. Knowing where the fence is drawn matters as much as the guard passing.
What I corrected
Stale skill counts were corrected in seven documents and two script docstrings. Every one was wrong in the same direction: written when the catalog was smaller and never revisited as it grew.
The distribution document claimed there was no automatic refresh for already activated customers. That was superseded months ago by a startup version probe. The checklist line was the sharper of the two errors. A statement someone reads is merely wrong, but an instruction someone follows while planning work shapes decisions.
I also corrected a self-contradiction on the Pro count, a checklist entry directing maintainers to hand-edit a string that no longer exists, a description of the bundle as shipping only skill definition files when it had been changed to ship whole folders, and roughly a dozen code citations pointing at line numbers that had moved.