Guide · Agent skill
How to use the Claude Compaction Restore agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
claude-compaction-restore is an agent skill for Claude Code. It makes a long-running agent write a restore map before its context is compacted, so the connections between files, decisions and next steps survive, and then read that map after compaction to rebuild its working picture. It is written for orchestrator-style agents in the OpenRig multi-agent system. After this guide you will know what the skill does, how to install it, how to trigger it, and what it needs to run.
Claude Compaction Restoremvschwarz/openrig · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it on your machine.
- 2Place the folder. Put the skill folder in ~/.claude/skills/ for personal use or in the project's .claude/skills/ folder for one project. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Confirm OpenRig is ready. Make sure OpenRig is installed and the rig command works. Run rig whoami --json to check your seat.
- 4Trigger it before compaction. Ask the agent to write its restore map before the session compacts. It will write the map at the path named in the preparation request and publish a seat recap.
- 5Restore after compaction. After compaction, ask the agent to restore from its map. It reads the ranked list and the saved transcript before acting.
What the skill makes the agent do
Compaction summarizes a session to free space. The summary keeps facts such as file names, row ids and decisions, but it tends to lose the links between them: why a file matters, what depends on what, and what the agent planned to do next.
The skill has the agent write a restore map first. The map opens with a short summary of 10 to 20 lines and then lists the connections: state, the important files and rows, the edges between them, judgment calls, the timeline, and lookups for where to re-read the session transcript. After compaction, the agent reads that map and its saved transcript before acting.
- Before compaction: write the restore map and publish a seat recap.
- After compaction: read the ranked reading list in the map and rebuild context before taking action.
- Maps from several compactions chain together into one continuous record.
Install the skill from the download
Download the skill ZIP from this page and unzip it. You can install it for yourself or for a single project, or upload it through the Claude apps.
For a personal install, place the skill folder in ~/.claude/skills/. For a project install, place it in the project's .claude/skills/ folder. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you rely on it
The skill depends on OpenRig. It calls the rig command with several subcommands, and it expects OpenRig's file layout. Node.js is needed because the skill runs .mjs scripts. You can confirm your seat's identity and see the commands the skill uses with the lines below.
- Claude Code
- OpenRig installed, with the rig command available
- Node.js to run the .mjs scripts
rig whoami --json
rig compact-plan --jsonTrigger the skill with natural requests
You do not need a special command to use the skill. The skill is meant to be picked up when the session is about to compact, has just compacted, has reached its context limit, has resumed after /compact, or needs to rebuild its picture of a long-running seat. You can ask for it directly in plain language.
Examples of requests that match the skill's description: 'We are about to compact, so write your restore map.' 'You just compacted. Rebuild your picture of this seat from your restore map and transcript before doing anything else.' 'Check your context usage against the restore budget.'
- 'Write your restore map before we compact.'
- 'You just compacted. Restore your context from your map.'
- 'Check how much context you are using at this checkpoint.'
How the restore budgets work
The skill sorts restored seats into two classes. Default seats, such as drivers, builders, reviewers and QA, read the top of the ranked list up to about 100k of real context. High-context seats, such as orchestrators, planners, advisors and leads, read the top tier and the second tier up to about 200k. Assuming a context window of about 1M tokens, these budgets scale to about 10% and 20% on a smaller window.
File size underestimates real context cost, so the skill ranks by bytes divided by 4 at about 50k for Tier 1 and about 100k for Tier 2, then checks actual usage with rig compact-plan --json and the estimatedUsedTokens field.
- Default class: Tier 1 only, to about 100k real context.
- High-context class: Tiers 1 and 2, to about 200k real context.
- Transcripts appear only as targeted line ranges, never as whole files.
Safety notes on scripts and privacy
The skill runs scripts, including precompact-hook.mjs and restore-from-jsonl.mjs. It does not use the network. Restore maps contain private working context, so the preparation folder is set to ignore itself in Git.
Do not use this skill on a shared machine where restore packets in /tmp or private restore maps could expose working context to other users. Read the scripts before you run them in a sensitive project.
- Runs scripts: yes. Uses network: no.
- Restore maps and the preparation folder can hold private working context.
- Avoid shared machines for this skill.
What people use it for
- An orchestrator that coordinates many seats keeps its wide project picture across several compactions.
- A planner or reviewer holds a standard or a long mission and needs to resume with its decisions and reasons intact.
- A developer running a long-lived Claude Code agent inside OpenRig checks context usage at each checkpoint with rig compact-plan --json.
Frequently asked questions
Is the claude-compaction-restore skill free?
The skill is published under the Apache-2.0 licence, as listed on this page. Check the licence file in the download for the full terms. It still requires Claude Code and OpenRig to be installed.
What do I need to install claude-compaction-restore?
You need Claude Code, OpenRig with the rig command available, and Node.js to run the .mjs scripts. Download the ZIP from this page, then place the folder in ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
Where do I put the skill folder?
Use ~/.claude/skills/ for a personal install or .claude/skills/ inside a project for a project-only install. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
Can I use this skill without OpenRig?
No, not as described. The skill depends on OpenRig commands such as rig whoami, rig context recap-write and rig compact-plan, and on OpenRig's file layout. Users outside OpenRig are not the intended audience.
Does the skill send my data over the network?
The skill does not use the network, according to its metadata. It does run scripts, and restore maps can hold private working context, so avoid using it on shared machines where other users could read /tmp or restore files.
How is this different from a normal Claude summary at compaction?
A normal summary keeps facts but loses how they connect. This skill adds a restore map that records relationships, decisions, rejected options and next steps, and the agent rebuilds from that map and its transcript after compaction.
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 this skill if you run long-lived Claude Code agents inside OpenRig, especially orchestrators, planners or reviewers that must keep a wide project picture across many compactions. Skip it for short, one-off chats, for work outside OpenRig, or on shared machines where restore files could be exposed; a plain Claude Code session will be simpler.
Download the skill