Guide · Agent skill

How to use the Strategic Compact agent skill: setup and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The strategic-compact skill is a small add-on for Claude Code that suggests running /compact at natural breakpoints in a long session, instead of letting the tool compact automatically in the middle of a task. This guide explains what it does, how to install it from the ZIP or the Claude apps, how to trigger it, and what to watch out for. By the end you will be able to set up the hook, decide when a suggestion is worth acting on, and protect your plan before compacting.

Strategic Compactaffaan-m/ECC · MIT Download the skill

Quick start

1Get the ZIP. Download the strategic-compact ZIP from the directory page.
2Install the skill. Unzip into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
3Confirm Node.js. Make sure Node.js is installed so the suggest-compact.js script can run.
4Add the hook. Add the PreToolUse Edit and Write hook entries to ~/.claude/settings.json as shown in the setup section.
5Work through a long task. Ask for research, planning and implementation in phases, and write the plan to a file.
6Act on suggestions. When the hook suggests /compact at a phase boundary, save state and compact with a short focus message.

What the strategic-compact skill makes the agent do

Long AI coding sessions eventually fill the assistant's context window, the working memory it has for the conversation. When that happens, the tool summarizes or drops older content automatically, often partway through a task. This skill changes that by suggesting a manual /compact at logical points, such as after research and planning, or after debugging is finished.

The skill combines two signals. The main one is context size: a script called suggest-compact.js reads the session transcript and estimates how many tokens are in context. The secondary one is the number of tool calls made so far. The guidance also advises against compacting mid-implementation, and tells the assistant to write the plan to a file first.

Suggests /compact after planning, after debugging, and after a failed approach
Advises against compacting in the middle of implementation
Re-reminds you as context keeps growing

Install the strategic-compact skill from the ZIP or the Claude apps

Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to one project. The skill's files are SKILL.md and agents/openai.yaml, and the hook script lives in the strategic-compact folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/strategic-compact/
Project install: .claude/skills/strategic-compact/ inside your project
Claude apps: Settings → Capabilities → Skills

Add the hook to Claude Code settings

The suggestions depend on Claude Code's PreToolUse hooks, so the skill alone is not enough. Add the following to your ~/.claude/settings.json. It runs the script before every Edit and Write call.

Make sure Node.js is installed, because the script runs with node.

{
  "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" }]
      }
    ]
  }
}

Trigger the skill with natural requests

You do not need a special command to activate the skill. Ask for the kind of work it covers and the assistant will use it when a session is long or a phase is ending. You can also state the boundary yourself, which makes the assistant more likely to act on it.

When the hook suggests /compact, you decide whether to act. The suggestion tells you when, and you choose if.

"We've finished the research. Write the plan to PLAN.md, then suggest a good point to compact."
"Debugging is done and the fix is committed. Should we compact before the next feature?"
"Before compacting, save the decisions we made to a file."

Choose when to compact and what to keep

Compact at phase boundaries where the bulky material is no longer needed. Avoid compacting while you are still changing code, because variable names, file paths and partial state are costly to lose. When you compact, you can add a short instruction so the summary focuses on what comes next.

Before compacting, check what survives. CLAUDE.md instructions, files on disk, memory files and git state persist. Intermediate reasoning, file contents you read earlier and nuanced preferences you stated verbally do not. The task list only survives if you have the todo tools, so do not rely on it.

Research → planning: compact, since the plan is the distilled output
Planning → implementation: compact after the plan is in a file
Implementation → testing: keep if tests reference recent code, compact if you are switching focus
Debugging → next feature: compact
Mid-implementation: do not compact
After a failed approach: compact before trying a new one

/compact Focus on implementing auth middleware next

Configure thresholds for your model's context window

The defaults are a context threshold of 160k tokens on a 200k window and 250k on a 1M window, with a repeat reminder every 60k tokens of growth. You can change them with environment variables. If you use a large-window model that does not show a [1m] marker in its model id, set ECC_CONTEXT_WINDOW_TOKENS so the threshold matches the real window. Set COMPACT_CONTEXT_THRESHOLD to 0 to turn off the context signal.

The tool-call signal fires after 50 calls by default and then every 25 calls. Change it with COMPACT_THRESHOLD.

COMPACT_THRESHOLD: tool calls before the first suggestion (default 50)
COMPACT_CONTEXT_THRESHOLD: context tokens before the context suggestion (0 disables it)
COMPACT_CONTEXT_INTERVAL: extra tokens before the suggestion repeats (default 60000)
ECC_CONTEXT_WINDOW_TOKENS: explicit window size in tokens
CLAUDE_CODE_AUTO_COMPACT_WINDOW: native window override, used when ECC_CONTEXT_WINDOW_TOKENS is unset

Safety notes and limits

The skill runs a script, so review it before installing. According to the listing, it runs scripts and does not use the network. The hook is only as good as Claude Code's hook support, so the skill will not help in tools without PreToolUse hooks.

Compaction does not save unfinished work. Write plans, decisions and state to files, or to CLAUDE.md or memory files, before you compact.

Runs scripts: yes, via node suggest-compact.js
Uses network: no, per the listing
Without hooks, you only get the manual checklist in the guidance

What people use it for

Running a multi-phase feature that goes research → plan → implement → test in one Claude Code session
Clearing debugging traces before starting an unrelated feature in the same session
Keeping responses coherent in a very long session where they have started to slow or drift
Recovering a clean context after a dead-end approach

Frequently asked questions

How do I install the strategic-compact skill?

Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to run it?

You need Claude Code, since the hooks are configured through ~/.claude/settings.json, and Node.js to run suggest-compact.js. The skill must be installed at ~/.claude/skills/strategic-compact/ where the script lives.

Is strategic-compact free to use?

The skill is listed under the MIT licence. Check the licence text in the source for the full terms.

Does the skill compact my session automatically?

No. It suggests running /compact at strategic points, and you decide whether to act. The hook tells you when, you decide if.

Will I lose my todo list when I compact?

It may not survive. Recent Claude Code versions removed the todo tools by default on some newer models, so write the plan to a file before compacting instead of relying on the task list.

What are the alternatives if I do not use Claude Code hooks?

Without hooks, the skill's guidance works only as a manual checklist: compact after planning or debugging, avoid compacting mid-implementation, and save state to files first. You can also use /compact yourself at the same breakpoints.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use strategic-compact if you run long Claude Code sessions that span research, planning, implementation and testing, or if you switch between unrelated tasks in one session. Skip it for short sessions, for tools without hook support, or if you expect compaction to keep unsaved work, because it will not.

Download the skill