Package upgrade leaves installed skill stale — version-mismatch warning never reaches the agent that consumes the skill

[igorregoir-lgtm]

Summary

Upgrading the package (uv tool upgrade graphifyy) leaves the installed skill (~/.claude/skills/graphify/) at the old version. The CLI does print a warning — but the agents that actually consume the skill never see it, so they keep executing stale instructions against the new package.

What happened (0.8.32 → 0.9.11, Windows 11, Claude Code)

1. uv tool upgrade graphifyy bumped the package 0.8.32 → 0.9.11.
2. ~/.claude/skills/graphify/SKILL.md (and references/) stayed at 0.8.32 — .graphify_version confirmed the drift.
3. Running graphify in a terminal shows the (good!) warning:
   warning: skill is from graphify 0.8.32, package is 0.9.11. Run 'graphify install' to update.
4. But the warning never reaches the agent. Claude Code (and Cursor/Windsurf/etc.) load SKILL.md directly from disk — the skill is consumed by the agent host, not through the CLI entry point. Our agent sessions kept following 0.8.32 pipeline instructions (old step semantics, old flags) while shelling out to a 0.9.11 package, and nothing in the session surfaced the mismatch.

The failure mode is silent semantic drift: the more the skill instructions change between versions, the more the agent's behavior diverges from what the installed package expects.

Suggested fixes (any of these would close the gap)

• Self-heal: on any CLI invocation, when the installed-skill version ≠ package version, refresh the installed skill(s) automatically (the platforms are already detected by graphify install; a GRAPHIFY_NO_SELF_UPDATE=1 opt-out keeps it safe for pinned setups).
• Fail loud where the agent can see it: make the version check also write a marker file into graphify-out/ (e.g. .graphify_version_mismatch) that the SKILL.md instructs the agent to check in Step 1 — the mismatch then surfaces inside the session that would be affected by it.
• At minimum, document in the README that uv tool upgrade / pipx upgrade must always be followed by graphify install.

Happy to test a patch on Windows.