Guide · Agent skill
How to use the Session Compaction and Restore agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Session Compaction and Restore skill is an instruction file for an AI coding agent. It teaches the agent how to keep active work intact when its conversation memory is trimmed by compaction, when it crashes, or when its seat is refreshed. It is written for people running long-lived agent seats inside OpenRig, a multi-agent system with a rig CLI. After this guide you will know how to install the skill, how to ask an agent to use it, and how to tell resume, fork and rebuild apart.
Session Compaction and Restoremvschwarz/openrig · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm OpenRig is installed. The skill assumes OpenRig is installed with its rig CLI available, and that your seats run Claude Code or Codex runtimes managed by OpenRig.
- 3Check readiness. Run rig restore-check to see whether running rigs are ready for restore. It is read-only.
- 4Plan before compacting. Run rig compact-plan to triage seats. It reports which seats need attention and does not compact anything.
- 5Ask the agent for a restore packet. Describe the active workflow in a natural request so the agent designs a packet that keeps current state and product intent.
- 6Compact or restore one seat. Use rig compact <session> for a single Claude seat, or rig restore-packet to write, read or validate the packet.
- 7Verify recovery. After the seat restarts, check that it knows its identity, current workflow, next owner, files and constraints without a re-briefing.
What the skill makes the agent do
Compaction shortens an agent's conversation history so it fits in the context window. Without care, the agent can lose track of the work it was doing. This skill tells the agent how to check what survives compaction, context loss, restart or seat refresh, and how to rebuild its understanding when needed.
The skill names four failure modes that prevent an honest restore: a compacted seat drops the active work (the "hot potato"), a restore packet keeps details but loses the product intent, a runtime resume is mistaken for a handover or fork, and a rebuilt seat starts with stale instructions.
- Separates native resume, fork, rebuild, artifact-backed mental-model rebuild and fresh launch
- Explains how to design a restore packet that keeps why the work matters, not only what was happening
- Describes the CLI commands for checking readiness and triggering compaction or restores
Install the skill from the ZIP
Download the ZIP for this skill from this page. The skill is a single file named SKILL.md. Unzip it so the folder is placed in one of two locations: ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to make it available only in that project.
If you use the Claude apps instead of the file system, you can upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: upload under Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. Agents load skills based on their description, so ask in plain language about the situation. The skill's description covers questions about what survives compaction, designing a restore packet, and telling resume, fork and rebuild apart.
Good requests name the situation: the seat is nearly full, it has just been compacted, or it was restarted and needs to pick up active work. Mention the workflow you want preserved so the agent knows what to protect.
- "This seat is close to compaction. What needs to go into its restore packet?"
- "We just compacted the reviewer seat. Check whether it kept the current task and why it matters."
- "Should I resume this session or fork it? Explain the difference for our workflow."
- "Design a restore packet for the release work so a rebuilt seat does not follow stale instructions."
Use the OpenRig CLI commands
The skill references five OpenRig commands. Pick the one that matches your intent. The packet and its artifacts are the source of truth; the CLI is only the trigger.
rig compact-plan is read-only triage and does not compact anything. rig compact runs guided compaction for one Claude seat. rig restore-check is a read-only readiness probe across running rigs. rig restore-packet supports write, read and validate. rig restore takes a snapshot ID and is a rig snapshot restore for infrastructure, which is a different mechanism from session-context restore.
- rig compact-plan: triage only, flags include --rig, --refresh, --threshold-tokens, --threshold-percent
- rig compact <session>: one Claude seat; non-Claude seats are rejected
- rig restore-check: flags include --full, --ready, --rig, --no-queue, --no-hooks
- rig restore-packet {write,read,validate}: the cross-runtime packet
- rig restore <snapshotId> --rig <rigId>: rig snapshot restore, not session-context restore
rig compact-planUnderstand resume, fork and rebuild
These outcomes are kept separate on purpose. Native resume continues the same managed seat with its native runtime token and reports resumed. Fork creates a new managed seat from a prior native conversation with a new post-fork token and reports forked. Rebuild is a fresh launch seeded with operator-declared artifacts in trust-precedence order and reports rebuilt. Fresh launch is a new agent with no prior continuity and reports fresh.
Do not treat a fork as an artifact-backed reentry, and do not treat a rebuild as a fork.
- resumed: same seat, native runtime token
- forked: new seat from prior conversation, new token
- rebuilt: fresh launch seeded with artifacts
- fresh: no prior continuity
Check what is preserved after a restore
A good restore is judged by measured recovery. After a deliberate compaction or restart of a seat with active work, the restored seat should know its identity, current workflow, next owner, relevant files and constraints without a human re-briefing it.
For project context, a restore packet carries the work in flight, not the project's declared intent and context files. Run rig context work-install to list what the project declares, and read the pieces the restored task needs. Use --deliver to print them all. If several projects are declared, use --json to list the ids and select one with --project <id>.
- Confirm identity, current workflow, next owner, relevant files and constraints are present
- Read declared project context with rig context work-install when the task needs it
rig context work-installWhat people use it for
- Keeping a senior reviewer seat productive through repeated compactions on a long project
- Writing a restore packet before restarting an operator seat that runs an ongoing release workflow
- Deciding whether to resume a managed seat or fork it when a conversation has gone stale
- Rebuilding a seat from artifacts after its instructions have changed, so it does not follow outdated guidance
- Auditing a restore to confirm the seat kept why the work matters, not just what was happening
Frequently asked questions
How do I install the session compaction and restore skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to use this skill?
The source lists OpenRig installed with its rig CLI available, plus Claude Code or Codex runtime seats managed by OpenRig. Most of the guidance depends on OpenRig's CLI commands and seat model, so users unfamiliar with OpenRig will find it hard to apply.
Is the skill free and what is its licence?
The item is licensed under Apache-2.0. The source does not state a price, so check the directory page for any listing details.
Does the skill run scripts or use the network?
According to the listing, it runs no scripts and uses no network. It is a single SKILL.md instruction file. It does reference OpenRig CLI commands, which you run yourself.
Does the skill edit my Claude or Codex session files?
No supported OpenRig path edits provider-owned native session, auth or transcript files to inject context. Context enters through hook additionalContext, a normal message via rig send, or Codex resume tokens. OpenRig does write ~/.codex/config.toml, but only to install activity hooks and [features].
What is the difference between this skill and session-source-fork?
This skill is for restoring and re-entering active work after compaction, restarts or seat refreshes. session-source-fork is for creating a new seat from a primed source. The source says to use session-source-fork or agent-starters when the goal is a new seat.
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 or Codex seats inside OpenRig and need them to survive compaction or restarts without losing active work. Pick something else if you are starting fresh sessions with no working state, do not use OpenRig, or only need to create a new agent from a primed source, where a sibling skill like session-source-fork fits better.
Download the skill