Skip to content

Skill Amnesia Mitigation

Problem

During long sessions, Claude Code's context compaction summarizes conversation history, which can lose awareness of available skills. A Vercel study found agents only activate the right skills 79% of the time with explicit instructions, dropping further after compaction.

Symptoms: - Claude forgets which skills are available after compaction - Users must manually re-invoke skills or remind Claude of their existence - Workflow continuity breaks mid-session

Root Cause

Claude Code's three context layers have different compaction behavior:

Layer What Survives Compaction?
System prompt Tool definitions, Skill tool description Yes (always present)
CLAUDE.md / Memory Re-injected each turn Yes (re-injected)
Conversation history Skill invocations, tool results No (summarized)

After compaction, Claude can see skill names (Layer 1) and CLAUDE.md references (Layer 2), but loses detailed instructions from previously invoked skills (Layer 3).

Solution: Three-Layer Defense

Layer 1: CLAUDE.md Skill Inventory (Persistent)

Retired 2026-10-04 (SPEC-220). A compact inventory of all deployed skills sat in the user-global CLAUDE.md (Part 5), re-injected every turn so it survived compaction. By 134 skills it cost ~1,500 tokens per request and repeated the skill listing every session already carries, so the owner dropped it. Skill names now survive through that session listing and Layers 2 and 3.

Layer 2: PreCompact Hook (Enrichment)

The precompact-skill-inventory.sh hook fires before compaction and outputs: - Full list of deployed skills - Active branch and spec - Current workflow phase

This output becomes additionalContext in the compaction summary, enriching what survives.

Layer 3: PostCompact Recovery Hook (Recovery)

The postcompact-recovery.sh hook fires on SessionStart with matcher compact: - Re-injects full skill inventory with workflow groupings - Restores git branch and recent commit context - Lists in-progress specs

Vercel Study Data

Configuration Trigger Rate Pass Rate
Baseline (no docs) N/A 53%
Skill (default) 44% 53%
Skill + explicit instructions 95% 79%
Compressed AGENTS.md (embedded) Always present 100%

Key insight: Embedded persistent context achieves 100% activation vs 79% for skills with explicit instructions.

Files

File Purpose
configs/user-global/CLAUDE.defaults.md (Part 5) Persistent skill inventory — retired by SPEC-220
plugins/vt-base/scripts/precompact-skill-inventory.sh PreCompact hook
plugins/vt-base/scripts/postcompact-recovery.sh Post-compaction recovery
plugins/vt-base/hooks/hooks.json Hook registration