Clear Context
Define versioned session-state checkpoint files so continuation agents can resume work after context limits or handoffs without losing decisions and todos.
Overview
Clear-context is a journey-wide agent skill that defines a versioned session-state checkpoint schema—usable whenever a solo builder needs to preserve agent context before committing to the next continuation turn.
Install
npx skills add https://github.com/athola/claude-night-market --skill clear-contextWhat is this skill?
- Version 1 schema with required state_version on the checkpoint header
- Required sections: Execution Mode, Current Task, Progress Summary, Continuation Instructions
- Optional sections for Key Decisions, Active Files, Pending TodoWrite Items, Existing Task IDs, Metadata JSON
- Backward-compatible v0 detection for unversioned legacy checkpoint files
- Supports checkpoints triggered by context threshold, manual save, or task boundary
- Schema version 1 with four required sections
- Six optional sections including Metadata JSON block
Adoption & trust: 1 installs on skills.sh; 304 GitHub stars; 2/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You hit context limits or switch agents mid-task and lose execution mode, progress, and the exact next steps unless you ad-hoc dump chat history.
Who is it for?
Solo builders running multi-hour agent sessions on one repo who already use or want markdown checkpoint files at context thresholds or task boundaries.
Skip if: Teams that never hand off between agent runs and keep full state only in issue trackers without procedural checkpoints.
When should I use this skill?
When creating or migrating session state checkpoint files for continuation agents after context threshold, manual checkpoint, or task boundary.
What do I get? / Deliverables
After the skill runs, continuation agents read a predictable checkpoint with continuation instructions and optional metadata instead of guessing from fragmented notes.
- Versioned session state markdown matching the v1 schema
- Continuation Instructions section for the next agent run
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Checkpoint before refactoring a large module so the next agent sees Active Files and Pending TodoWrite Items.
Save progress mid-API integration with Key Decisions recorded for auth approach.
Hand off halfway through a test-fix loop with Continuation Instructions listing failing cases.
Resume an incident fix after overnight with Execution Mode and Existing Task IDs for deduplication.
How it compares
Use instead of unstructured paste summaries when resuming Claude Code or Cursor after a context clear.
Common Questions / FAQ
Who is clear-context for?
Solo and indie builders using agentic coding workflows who need reliable session handoffs when context is trimmed or a new agent continues the same task.
When should I use clear-context?
Use it during build and ship when context thresholds fire, at task boundaries before pausing, or in operate when long-running fixes span multiple agent sessions—you want versioned checkpoint markdown with continuation instructions.
Is clear-context safe to install?
It is a schema and documentation skill with no runtime commands; review the Security Audits panel on this Prism page before adding the parent repo skill pack to your agent.
SKILL.md
READMESKILL.md - Clear Context
# Session State Schema ## Current Version: 1 All session state files MUST include a `state_version` field on the first content line after the heading. This enables continuation agents to detect the format and apply migration logic when needed. ## Version 1 Schema ### Required Header ```markdown # Session State Checkpoint state_version: 1 Generated: YYYY-MM-DD HH:MM:SS Reason: [Context threshold | Manual checkpoint | Task boundary] ``` ### Required Sections | Section | Purpose | |---------|---------| | `## Execution Mode` | Mode, auto-continue flag, source command | | `## Current Task` | What we are trying to accomplish | | `## Progress Summary` | What has been done so far | | `## Continuation Instructions` | Next steps for the continuation agent | ### Optional Sections | Section | Purpose | |---------|---------| | `## Key Decisions` | Decisions and rationale | | `## Active Files` | Files being modified or referenced | | `## Pending TodoWrite Items` | Outstanding todo items | | `## Existing Task IDs` | Task IDs for deduplication | | `## Metadata` | JSON block with handoff count, priority, etc. | ## Version 0 (Unversioned Legacy) Any session state file that lacks the `state_version` field is v0. These files were written before versioning was introduced. ### Identifying v0 Files A v0 file typically starts with: ```markdown # Session State Checkpoint Generated: YYYY-MM-DD HH:MM:SS ``` No `state_version` line is present. ### V0 Field Mapping V0 files use the same section names as v1. The only difference is the missing version header. All sections are compatible. ## Migration: V0 to V1 When a continuation agent encounters a v0 file, apply this migration: 1. **Treat it as v1.** The content is structurally identical. 2. **Do not rewrite the file** just to add the version header. Only add `state_version: 1` if you are already updating the file for other reasons (e.g., progress checkpoint). 3. **Log the migration.** Note in your handoff summary: "Migrated session state from v0 (unversioned) to v1." No field renaming or restructuring is needed. V0 and v1 are content-compatible. ## Version Check Logic Continuation agents MUST follow this sequence when reading a session state file: ``` 1. Read the file 2. Look for "state_version: N" in the first 5 lines 3. If found: a. version == 1 -> proceed normally b. version > 1 -> warn "Unknown state version N, attempting to read" then proceed (best-effort forward compatibility) 4. If not found: -> treat as v0, proceed normally (v0 is compatible with v1) ``` ### Forward Compatibility Future versions should maintain backward-compatible section names where possible. If a breaking change is needed, the version number increments and this document gets a new migration section. A continuation agent encountering an unknown future version should: - Log a warning: "Session state version N is newer than expected (v1). Reading with best effort." - Attempt to read all recognized sections - Skip unrecognized sections without error - Continue the work rather than failing ## Version History | Version | Date | Changes | |---------|------|---------| | 0 | Pre-1.5.2 | Original unversioned format | | 1 | 1.5.2 | Added `state_version` header field | --- name: session-state description: | Session state persistence format and management for context handoffs. Defines the checkpoint structure that enables smooth continuation. category: conservation --- # Session State Module ## Overview This module defines the session state format used for context handoffs. A well-structured state file enables continuation agents to seamlessly pick up where the previous agent left off. ## State File Location **Default**: `.claude/session-state.md` **Override**: Set `CONSERVE_SESSION_S