AI agent skill · by @jh941213

Compact Guide

Context window management and token optimization guide. Triggers on: context, tokens, compact, memory management. NOT for: code writing, debugging.

Archived 2026-10-23 · Source updated 2026-08-03. Check the original repository for the latest version.

SKILL.md instructions

# Context Management Guide

Context is like fresh milk. **The problem is freshness, not volume** — polluted context deserves a reset.

## Core Principles (the 1M-context era)

- Don't count remaining tokens — **auto-compact manages the threshold** — manual /compact **only when a work unit ends**
- Manual intervention is **signal-based**, not number-based:

| Signal | Action |
|--------|--------|
| A work unit (milestone/story) just finished | /compact — start the next unit clean |
| The work topic changes entirely | /handoff → /clear — new session |
| Repeating the same mistakes, forgetting earlier decisions, illogical replies | Pollution signal — /handoff → /clear (compact doesn't wash pollution out) |
| Right after long exploration/log output | /compact if a work unit is ending; otherwise leave it to auto-compact |

- Never shrink or rush work out of worry about remaining context — keep going

## Commands

### /compact
- Summarizes and compresses conversation content
- Retains important information, reduces tokens only
- Does not interrupt workflow

### /clear
- Complete reset
- Risky without HANDOFF.md!
- Use when you want a clean start

## Recommended Pattern

```
Start work
    |
Work unit completed (milestone/story)
    |
/compact (clean up at the boundary)
    |
… repeat …
    |
Topic switch or pollution signal
    |
/handoff (generate HANDOFF.md)
    |
/clear (reset)
    |
Read HANDOFF.md in new session
```

## Context Management from a Cost Perspective

### Why /compact is advantageous
- Work context (progress, decisions) is preserved as a summary, so nothing needs rebuilding
- Retains important information while reducing tokens only, so workflow is not interrupted
- Lower restart cost than /clear

### Hidden cost of /clear
- Conversation-context rebuild cost — progress, decisions, and exploration results must be rebuilt from scratch
- Additional tokens generated when loading HANDOFF.md
- Implicit context not captured in HANDOFF.md is lost

### Decision rule
- **On cost alone**: /compact > /clear
- **When quality wobbles**: /clear is the answer — summarizing polluted context summarizes the pollution too
- For long autonomous runs (TTH/autodev), leave it to auto-compact and don't intervene