During validation of /generate-feature-docs on 2026-04-30, two consecutive slash command invocations loaded a pre-amendment cached version of .claude/skills/generate-feature-docs/SKILL.md even though the on-disk file had been updated and committed (commits 637e4624, 61e84a44). The skill executor (Claude) had to recognize the staleness and follow the disk version instead of the loaded version, otherwise the new readiness gates added in Section 16 of the design spec would not have fired.
Concretely:
- The on-disk
SKILL.md was 408 lines and contained Step 1.7a (verification-rate threshold) and Step 1.7b (branch-state heuristic).
- The slash command system message that the harness sent to Claude on each invocation showed a 365-line version that ended at Step 1.9 with no Step 1.7a or 1.7b.
- Claude verified the on-disk content via direct file read (
grep -n "Step 1.7a" returned a match) and chose to follow the on-disk version.
This may be session-scoped caching, a marketplace-cache layer, or some other mechanism worth understanding. Risk: a team member updating a skill in their repo may not see the new behavior fire on subsequent invocations within the same session, leading to confusion or trust issues with skill updates.
Worth investigating before relying on slash-command-driven skill rollouts.
During validation of
/generate-feature-docson 2026-04-30, two consecutive slash command invocations loaded a pre-amendment cached version of.claude/skills/generate-feature-docs/SKILL.mdeven though the on-disk file had been updated and committed (commits637e4624,61e84a44). The skill executor (Claude) had to recognize the staleness and follow the disk version instead of the loaded version, otherwise the new readiness gates added in Section 16 of the design spec would not have fired.Concretely:
SKILL.mdwas 408 lines and contained Step 1.7a (verification-rate threshold) and Step 1.7b (branch-state heuristic).grep -n "Step 1.7a"returned a match) and chose to follow the on-disk version.This may be session-scoped caching, a marketplace-cache layer, or some other mechanism worth understanding. Risk: a team member updating a skill in their repo may not see the new behavior fire on subsequent invocations within the same session, leading to confusion or trust issues with skill updates.
Worth investigating before relying on slash-command-driven skill rollouts.