Skill/CLI version drift between npm and Claude Code plugin install paths

[ankitranjan7]

Why this issue exists

Webcmd ships skills through more than one install path. A user can update the npm CLI while still running older skills from an agent plugin/cache path.

This issue predates the 2026-08-20 eval issues. It is still relevant because skill text affects agent behavior, and stale skill text can make agents call commands or flags that no longer match the installed CLI.

Related PR:

• fix: detect skill/CLI version drift between npm and Claude Code plugin installs #289: fix: detect skill/CLI version drift between npm and Claude Code plugin installs is still open.

Current Webcmd state

As of origin/main 22974697bb3fe784bad5ef5a208f2d6ee5a272a8 (webcmd-v0.7.4-2-g2297469):

• webcmd skills add/update/remove/list exists for linked skill installs.
• Linked skills are refreshed by webcmd update unless --skip-skills is passed.
• Codex and Claude plugin manifests also bundle skills/ directly.
• Docs now warn not to install both plugin-bundled skills and webcmd skills add copies.
• Claude docs say plugin updates are version-gated and separate from webcmd update.
• There is still no merged drift detector in webcmd doctor for plugin-cache skills versus the running CLI.

Observed agent/user behavior

The risky state is:

1. User installs Webcmd as an agent plugin.
2. Plugin copies skills into an agent-owned versioned cache.
3. User later runs webcmd update and upgrades only the npm CLI.
4. The agent still reads older plugin-bundled skill text.
5. The skill can recommend stale commands, flags, or workflows against the newer CLI.

This is especially costly because agents trust skill text as authoritative.

What went wrong

The system treats CLI version and plugin-bundled skill version as separate update surfaces, but the user-facing mental model is one product: Webcmd.

Docs reduce the chance of duplicate installs, but they do not detect or repair an already-drifted environment.

Solution directions

Product-first options:

1. Add a webcmd doctor drift check that reports the running CLI version, linked skill version, and plugin-cache skill version when detectable.
2. Make the warning actionable: which command refreshes which install path.
3. Keep webcmd update behavior simple. It can refresh linked skills, but plugin-cache updates may need to stay with the host agent's plugin manager.
4. Consider a docs/contributing note that skill changes require a release-triggering commit type so plugin users receive them.

Open questions for senior review

• Should webcmd update try to invoke claude plugin update, or should it only diagnose and print instructions?
• Which plugin caches can be detected reliably across Claude, Codex, and other agents?
• Is fix: detect skill/CLI version drift between npm and Claude Code plugin installs #289 the right implementation shape, or should the scope shrink to doctor only?

Acceptance criteria

• webcmd doctor can identify a likely CLI/skill version drift state.
• The diagnostic distinguishes linked skills from plugin-bundled cached skills.
• The message tells the user exactly how to refresh the stale side.
• The fix does not duplicate skills or mutate agent plugin caches unexpectedly.

Non-goals

• No automatic writes into third-party plugin caches unless explicitly chosen.
• No broad agent-plugin manager abstraction.
• No requirement that npm and every agent plugin update through the same command.

[ayushsingh82]

hey @ankitranjan7 would love to work on this