Session Summary

session-summary

When this skill is the preferred path

Context fill is high (90%+ of the window) and /compact is failing or about to fail. The agent needs to clear and resume without losing the work it has done so far. gc_session_summary produces a portable summary the agent can re-inject after /clear.

This skill is the natural pair to gc_pre_flight. When pre_flight returns the clear_first verdict, the workflow is:

1. Call gc_session_summary with the conversation history.
2. Use /clear (Claude Code's built-in).
3. Send the returned restoration_instructions as your first user message in the cleared session.
4. Call gc_pre_flight again with the next prompt — context fill is now low, you'll get send_compressed or send_as_is.

How to use it

Call gc_session_summary with one of:

• messages — structured conversation history as a list of {role, content} dicts. Roles: user, assistant, system, tool. Preferred when available.
• text — concatenated conversation as a plain string. Use when structured messages aren't available.

If both are passed, messages wins.

Optional:

• keep_facts — facts the summary MUST preserve verbatim (file paths, decisions, blockers, identifiers). Each item is prepended to the summary as a bullet point and not compressed.
• target_tokens — max size for the summary. Default 4000.

What you get back

{
  "summary": "<compressed-summary-string>",
  "key_facts": ["...", "..."],
  "tokens_in_original": 184000,
  "tokens_in_summary": 4200,
  "compression_ratio": 0.023,
  "restoration_instructions": "After /clear, send this as your first user message...",
  "recommendation": "Summary 97.7% smaller than original. Run /clear, then send..."
}

The restoration_instructions field is canonical — copy it into your next user message verbatim and the agent resumes with the compressed context attached.

Why this skill exists

• Anthropic GH#42647 (open): "severe token inefficiency (50K-300K+ tokens per event) due to repeated full-context resubmissions ... Autocompact triggers at ~187K tokens and submits the entire bloated context for summarization." Our summarization runs OUTSIDE the exhausted Claude context — it works when Claude Code's own auto-compact would fail.
• Anthropic GH#7910 (closed, not_planned): "Claude Code frequently becomes unable to compact because it uses almost all of the 200k token context window, and there isn't enough context left for compaction." This skill is the recovery path that issue asked for.
• LocalLLaMA pattern: "Treat the context window like RAM and the scratchpad like disk." This skill IS the scratchpad.

Failure-mode contract

Never raises to the agent. If the compression service is degraded, the response returns the truncated head of the conversation as a fallback summary plus a recommendation field flagging the degradation. The agent always gets a structured response it can re-inject.

Plan availability

Available on every plan including Free. Volume is governed by your existing per-month compression quota — same posture as gc_pre_flight.