# Compress Session

Distill the current conversation into a structured note (decisions made, open...

- Repository: https://github.com/pedrohcgs/claude-code-my-workflow (1676 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-09-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add pedrohcgs/claude-code-my-workflow --skill compress-session -g -a claude-code -y`
Codex: `npx skills add pedrohcgs/claude-code-my-workflow --skill compress-session -g -a codex -y`
Cursor: `npx skills add pedrohcgs/claude-code-my-workflow --skill compress-session -g -a cursor -y`
Gemini CLI: `npx skills add pedrohcgs/claude-code-my-workflow --skill compress-session -g -a gemini-cli -y`

## Description

Distill the current conversation into a structured note (decisions made, open questions, file pointers with line numbers, next 1, 3 actions) and save to `quality_reports/session_logs/` before auto-compression. Differs from `/checkpoint` (explicit stop-point snapshot) and from auto-compaction (which truncates rather than distills). Use when context is approaching auto-compact threshold, when a long pipeline has accumulated many decisions, or when the user says "compress", "distil this session", "before we hit auto-compact", "structured handoff before context resets".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# `/compress-session`, distil, don't truncate

Auto-compaction is **lossy**: it keeps recent turns and drops earlier ones, with no preservation of *what was decided* mid-session. `/compress-session` is the **distil-not-truncate** alternative, produce a structured note that the next session can resume from in under a minute.

## Why this skill exists

Drew Breunig's ["How Long Contexts Fail"](https://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html) identifies four failure modes for long-context sessions:

1. **Poisoning**, early hallucinated content gets quoted by later turns, compounding the error.
2. **Distraction**, irrelevant earlier context dilutes the model's attention to current task.
3. **Confusion**, contradicted facts pile up; the model doesn't know which to trust.
4. **Clash**, multiple plans, decisions, or specs accumulate without explicit reconciliation.

The template's 200-line `MEMORY.md` cap defends against *distraction*. The plan-on-disk convention defends against *clash*. Nothing currently defends against *poisoning* or directly against *confusion*, that's what this skill is for.

## Distinction from `/checkpoint`

The rest: https://github.com/pedrohcgs/claude-code-my-workflow/blob/HEAD/.claude/skills/compress-session/SKILL.md