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)

A compact inventory of all deployed skills in the user-global CLAUDE.md (Part 5). Since CLAUDE.md is re-injected every turn, this always survives compaction.

Token budget: < 500 tokens for 67 skills.

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.md (Part 5) Persistent skill inventory
plugins/core-standards/scripts/precompact-skill-inventory.sh PreCompact hook
plugins/core-standards/scripts/postcompact-recovery.sh Post-compaction recovery
plugins/core-standards/hooks/hooks.json Hook registration