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.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- strategic-compact
- license
- MIT
- description
- 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.
03 SKILL.md 正文
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:
- Context size (primary) — Reads the latest
usagerecord from the session transcript (transcript_pathin the hook payload) and sumsinput_tokens + cache_read_input_tokens + cache_creation_input_tokens(the true context size of the turn). Suggests/compactat 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 - Tool-call count (secondary) — Counts tool invocations in session; suggests at a configurable threshold (default: 50 calls), then every 25 calls after
Hook Setup
Add to your ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
},
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/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;0disables the context signal)COMPACT_CONTEXT_INTERVAL— Additional context tokens before the suggestion repeats (default: 60000)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 window-size override, in tokens; honored as a fallback whenECC_CONTEXT_WINDOW_TOKENSis unset.
The context window is otherwise auto-detected from a
[1m]model marker or inferred when observed tokens already exceed 200k. On a large-window model that carries neither signal, set one of the overrides above so the/compactsuggestion fires at the right point.
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=1brings 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
- 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
/compactwith a summary — Add a custom message:/compact Focus on implementing auth middleware next
Related
- The Longform Guide — Token optimization section
- Memory persistence hooks — For state that survives compaction
continuous-learningskill — Extracts patterns before session ends
04 同仓库更多 Skills
test-audit
Audit new or existing tests for behavioral value, duplication, implementation coupling, brittleness, and test-only production seams. Use when writing, changing, reviewing, or pruning tests, including an independent final review of a test diff.
last30days
Research what people actually say about any topic in the last 30 days. Pulls posts and engagement from Reddit, X, YouTube, TikTok, Hacker News, Polymarket, GitHub, and the web. Includes a doctor health check to diagnose broken or missing sources.
karpathy-guidelines
Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
port-github-app-to-origin
Plans the port of an existing GitHub App to a Cursor Origin App. Use when the task is to bring a GitHub App to Origin or compare what it uses against the Origin API. Reads the app's needs out of its code, maps them onto the live Origin spec, and writes a porting brief with feedback for Cursor. Planning only.
origin-api
Routes questions about the Cursor Origin API to the right section of the Origin docs and names the few rules to check first. Use when a task mentions Origin, the Origin API, Origin Apps, or Origin webhooks, including creating an Origin App, authenticating as one, calling Origin endpoints, or handling Origin webhook deliveries.
i-have-adhd
Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible. Invoke with /i-have-adhd; stays on until "stop adhd mode".