Skip to main content
Agent skill

Strategic Compact

Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction. Use when a session is approaching a context limit and a task phase is a natural place to compact.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Strategic Compact when an AI agent needs a reusable SKILL.md workflow for this job: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction. Use when a session is approaching a context limit and a task phase is a natural place to compact.

When not to use it

Skip Strategic Compact when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/strategic-compact
# Save SKILL.md to ~/.claude/skills/strategic-compact/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/strategic-compact/SKILL.md. For a shared project, commit the folder at .claude/skills/strategic-compact/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Strategic Compact skill for this task: Use Strategic Compact when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

67/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
75/100
Practical detail
58/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Strategic Compact Skill

Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.

## When to Activate

- Running long sessions that approach context limits (200K+ tokens) - Working on multi-phase tasks (research → plan → implement → test) - Switching between unrelated tasks within the same session - After completing a major milestone and starting new work - When responses slow down or become less coherent (context pressure)

## Why Strategic Compaction?

Auto-compaction triggers at arbitrary points: - Often mid-task, losing important context - No awareness of logical task boundaries - Can interrupt complex multi-step operations

Strategic compaction at logical boundaries: - **After exploration, before execution** — Compact research context, keep implementation plan - **After completing a milestone** — Fresh start for next phase - **Before major context shifts** — Clear exploration context before different task

## How It Works

The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and combines two signals:

1. **Context size (primary)** — Reads the latest `usage` record from the session transcript (`transcript_path` in the hook payload) and sums `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` (the true context size of the turn). Suggests `/compact` at a window-scaled threshold — 160k tokens on a 200k window, 250k on a 1M window (detected from a `[1m]` model marker, or inferred when observed tokens already exceed 200k) — and re-reminds after every additional 60k tokens of context growth. A valid native compaction budget can lower the default reminder threshold to 80% of that budget; model-capacity percentages still use the resolved model window 2. **Tool-call count (secondary)** — Counts tool invocations in session; suggests at a configurable threshold (default: 50 calls), then every 25 calls after

Tool count alone is a weak proxy for window pressure: a few large file reads or MCP responses can fill the window in very few calls, while many tiny calls can cross 50 with a near-empty window. The context-size signal fires when it actually matters.

## Hook Setup

**Installed as a plugin?** No setup is needed. The plugin's `hooks/hooks.json` already registers `suggest-compact.js` (hook id `pre:edit-write:suggest-compact`, active in the `standard` and `strict` hook profiles). Do not copy the block below into `~/.claude/settings.json` — `~/.claude/scripts/` does not exist on plugin installs, and duplicating a plugin hook causes double execution.

**If installed manually** (`./install.sh`), add to your `~/.claude/settings.json`:

```json { "hooks": { "PreToolUse": [ { "matcher": "Edit", "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }] }, { "matcher": "Write", "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }] } ] } } ```

## Configuration

Environment variables: - `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50) - `COMPACT_CONTEXT_THRESHOLD` — Context tokens before the context-size suggestion (default: 160000 on a 200k window, 250000 on a 1M window, capped at 80% of a valid native compaction budget when earlier). An explicit positive threshold overrides that default cap; `0` disables the context signal. - `COMPACT_CONTEXT_INTERVAL` — Additional context tokens before the suggestion repeats (default: 60000) - `COMPACT_STATE_TTL_DAYS` — Days before stale per-session state files in the temp dir are swept (default: 14) - `ECC_CONTEXT_WINDOW_TOKENS` — Explicit context-window size, in tokens, overriding auto-detection. Set this for large-window models whose reported id lacks a `[1m]` marker (e.g. 400k Opus 4.x, or a new 1M-window model family) so the threshold scales to the real window instead of defaulting to 200k and overstating context usage. - `CLAUDE_CODE_AUTO_COMPACT_WINDOW` — Claude Code's native auto-compact trigger, which may be smaller than the model's context window. For context-window resolution, ECC uses it only as a last-resort fallback, after an explicit ECC override, a `[1m]` model marker, a known large-window model family, and inference from observed tokens above 200k. It is not an exact model-capacity declaration.

> Window precedence is: `ECC_CONTEXT_WINDOW_TOKENS`, then the `[1m]` marker, a known large-window model family, observed tokens above 200k, the native auto-compact fallback, and finally the inferred 200k default. Set `ECC_CONTEXT_WINDOW_TOKENS` when you know the actual window and automatic detection lacks that information; do not treat the native compact trigger as proof of model capacity.

The Stop-hook summary scheduler protects resume state before compaction. It uses the earlier of confirmed capacity and a valid native compaction budget. When capacity is inferred, it uses only a valid native budget, or treats the remaining budget as unknown if none is provided. Model-capacity resolution remains separate. The default `/compact` reminder threshold independently uses the earlier of its window-scaled default and 80% of a valid native compaction budget. An explicit `COMPACT_CONTEXT_THRESHOLD`, including `0`, remains authoritative.

## Compaction Decision Guide

Use this table to decide when to compact:

| Phase Transition | Compact? | Why | |-----------------|----------|-----| | Research → Planning | Yes | Research context is bulky; plan is the distilled output | | Planning → Implementation | Yes | Plan is written down (a file, or the task list if you have one); free up context for code | | Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus | | Debugging → Next feature | Yes | Debug traces pollute context for unrelated work | | Mid-implementation | No | Losing variable names, file paths, and partial state is costly | | After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |

## What Survives Compaction

Understanding what persists helps you compact with confidence:

| Persists | Lost | |----------|------| | CLAUDE.md instructions | Intermediate reasoning and analysis | | Files on disk | File contents you previously read | | Memory files (`~/.claude/memory/`) | Multi-step conversation context | | Git state (commits, branches) | Tool call history and counts | | The task list — **only if you have the todo tools** (see below) | Nuanced user preferences stated verbally |

> ### Don't rely on the task list surviving — it may not exist > > Claude Code **2.1.233 removed the todo/task tools by default** on Opus 4.8, Sonnet 5, > Fable 5, Mythos 5 and newer models (`TodoWrite`, `TaskCreate/Get/Update/List`). > `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` brings them back, but that is a per-machine > environment setting — **it does not travel with this skill**, so you cannot assume the > reader has it. > > This matters because "my todo list survives compaction" is a reason people compact > *instead of* writing state down. If the tools are absent there is no list to survive, > and the plan is simply gone. **Write the plan to a file before compacting** — a file > persists on every version and every model. Treat the task list as a convenience that > may be missing, never as your durable record.

## Best Practices

1. **Compact after planning** — Once the plan is finalized **and written to a file**, compact to start fresh 2. **Compact after debugging** — Clear error-resolution context before continuing 3. **Don't compact mid-implementation** — Preserve context for related changes 4. **Read the suggestion** — The hook tells you *when*, you decide *if* 5. **Write before compacting** — Save important context to files or memory before compacting 6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`

## Token Optimization Patterns

### Trigger-Table Lazy Loading Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:

| Trigger | Skill | Load When | |---------|-------|-----------| | "test", "tdd", "coverage" | tdd-workflow | User mentions testing | | "security", "auth", "xss" | security-review | Security-related work | | "deploy", "ci/cd" | deployment-patterns | Deployment context |

### Context Composition Awareness Monitor what's consuming your context window: - **CLAUDE.md files** — Always loaded, keep lean - **Loaded skills** — Each skill adds 1-5K tokens - **Conversation history** — Grows with each exchange - **Tool results** — File reads, search results add bulk

### Duplicate Instruction Detection Common sources of duplicate context: - Same rules in both `~/.claude/rules/` and project `.claude/rules/` - Skills that repeat CLAUDE.md instructions - Multiple skills covering overlapping domains

### Context Optimization Tools - `token-optimizer` MCP — Automated 95%+ token reduction via content deduplication - `context-mode` — Context virtualization (315KB to 5.4KB demonstrated)

## Related

- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section - Memory persistence hooks — For state that survives compaction - `continuous-learning` skill — Extracts patterns before session ends

Intended uses

  • Use Strategic Compact when this documented workflow matches the task.

Implementation notes

  • Compact after planning — Once the plan is finalized and written to a file, compact to start fresh
  • Compact after debugging — Clear error-resolution context before continuing
  • Don't compact mid-implementation — Preserve context for related changes
  • Read the suggestion — The hook tells you when, you decide if
  • Write before compacting — Save important context to files or memory before compacting
  • Use /compact with a summary — Add a custom message: /compact Focus on implementing auth middleware next

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.