preserving-context
npx machina-cli add skill oryanmoshe/agent-skills/preserving-context --openclawPreserving Context
Overview
Capture state proactively, not reactively. Before compaction or task switches, write down everything needed to resume seamlessly. If you wait until after compaction, the context is already gone.
What to Capture
| Category | Capture |
|---|---|
| Current work | Exact task, file path, progress (X of Y) |
| Completed items | Which files changed and what was done |
| Remaining items | What still needs doing, in order |
| Pattern | The transformation being applied (so it continues consistently) |
| Decisions | Key choices made and why (not just what) |
| Blockers | Issues discovered, dependencies, failing tests |
| Test state | Are tests passing? Which are failing and why? |
Checkpoint Template
Write this as a task description (via TaskUpdate) so it persists across compaction, and also communicate it to the user so they have it too:
## Checkpoint — [Task Name]
**Working on:** [specific task]
**Current file:** [path]
**Progress:** [X of Y complete]
### Completed
- [file1] — [what was done]
- [file2] — [what was done]
### Remaining
- [file3] — [what needs doing]
- [file4] — [what needs doing]
### Pattern Being Applied
[Describe the transformation so it can be continued consistently]
### Key Decisions
- [Decision]: [why this over alternatives]
### Blockers / Notes
- [Any issues or dependencies]
Good vs Bad Checkpoints
Bad: "Working on refactor. Some files done."
Good: "Renaming getUserById to fetchUserById across the codebase. Completed: src/services/user.ts, src/api/routes.ts, src/tests/user.test.ts. Remaining: src/middleware/auth.ts, src/utils/cache.ts. Pattern: find-and-replace function name + update all call sites + update test assertions. Tests currently failing on 2 import mismatches."
Red Flags — STOP and Checkpoint
| Thought | Action |
|---|---|
| "I'll remember where I was" | Write it down NOW |
| "It's obvious what's next" | Obvious now ≠ obvious after compaction |
| "Just one more thing then I'll document" | Checkpoint first, then continue |
| "This is too small to checkpoint" | Small context loss compounds |
Integration with tracking-tasks
These two skills complement each other:
- tracking-tasks: Tracks WHAT tasks exist and their status
- preserving-context: Captures HOW to resume each task
Both should be used together before compaction.
Source
git clone https://github.com/oryanmoshe/agent-skills/blob/main/skills/preserving-context/SKILL.mdView on GitHub Overview
Preserving-context captures the current work state so you can resume without losing progress. Do this proactively before context compaction, when switching between unrelated tasks, or when a session ends. It triggers on long tasks, multi-file changes, context warnings, or continue-later scenarios.
How This Skill Works
Before compaction or task switches, record everything needed to resume: the exact task, current file path, progress (X of Y), completed items, remaining items, the transformation pattern, key decisions, blockers, and test state. Save this as a Checkpoint via TaskUpdate so it persists across compaction and is visible to the user when resuming.
When to Use It
- Before context compaction on a long-running task
- When switching between unrelated tasks
- After completing a logical phase of multi-step work
- When resuming work in a new session
- When blockers arise or a continue-later scenario is needed (including multi-file changes)
Quick Start
- Step 1: Identify the critical state to capture (task, file, progress, blockers, tests)
- Step 2: Create a checkpoint with Working on, Current file, Progress, Completed, Remaining, Pattern Being Applied, Key Decisions, Blockers / Notes
- Step 3: Persist via TaskUpdate so the checkpoint remains across compaction and is shown to the user
Best Practices
- Capture precise state: current task, exact file path, and progress (X of Y)
- Document Completed items and Remaining items in clear, actionable terms
- Record the transformation Pattern being applied and the Key Decisions behind choices
- Note Blockers and the current Test state (which tests pass/fail and why)
- Use the provided Checkpoint template via TaskUpdate and share the checkpoint with the user
Example Use Cases
- Refactoring a feature across multiple files: checkpoint shows Working on, Current file, Progress, Completed, Remaining, Pattern, Decisions, Blockers
- Data migration that will take multiple sessions: checkpoint includes progress, remaining steps, and test status
- Switching from feature A to feature B mid-work: checkpoint captures current task, files touched, and next steps
- Pausing a task due to blockers: checkpoint lists blockers and what must be resolved to continue
- Resuming after a long pause: checkpoint provides a quick resume snapshot including transformation pattern and decisions
