Pi Agent Compression & Handoff Skill: Cross-Session Context Management

Problem: Context Loss in Long-Running Agent Tasks

When using agents for long tasks, two common issues arise: (1) the context window fills up mid-task, causing goal drift; (2) switching sessions or agents loses the entire execution context, forcing a restart.

Pi Official Compression Algorithm

Pi's native compression manages the context window within a single session. Its core design points:

Trigger Design : Auto-compress when context hits the limit, or manually via /compact. Auto-compression completes within the same turn without interruption.

Cutoff Design : Counting back from the latest message, preserve keepRecentTokens worth of tokens verbatim; earlier messages are summarized.

Structured Summary (Not Free Text) : Fixed fields defined by Pi:

Goal

Constraints

Progress

(Done / In Progress / Blocked)

Decisions

Next Steps

Critical Context

Plus a cumulative list of files read and modified.

Summary Relay : The previous summary becomes input for the next compression round; re-compression continues from the last retained boundary, avoiding re-summarizing already-kept messages. The file list also accumulates across compressions.

Branch Switching Support : Using /tree to switch branches carries the departing branch's summary forward (called branch summarization ).

Single-Turn Long Handling : If a single conversation turn is too long to fit, the cutoff falls inside that turn, splitting it into two summaries (Turn Context + recent verbatim) that are merged for the next request.

Pi Agent controls what to compress/keep and the summary format, delegating the actual summarization to the LLM.

In-session rely on Agent native compression; cross-session rely on Handoff to carry context.

Handoff Skill

Adopting Pi's six-field summary structure, the author created a Handoff skill that generates a persistent handoff.md checkpoint for cross-session and cross-agent handoff. The complete SKILL.md and a fixed HANDOFF-TEMPLATE.md are provided (also available at flyeric0212/agent-skills on GitHub).

Skill Definition (SKILL.md)

---
name: handoff
description: 生成或更新工程 handoff.md，记录可验证的目标、进展、决策、下一步和接手上下文。用于暂停开发、切换会话或交接未完成工作。
---

# Handoff

使用 [HANDOFF-TEMPLATE.md](templates/HANDOFF-TEMPLATE.md) 生成或更新工程 checkpoint。优先使用用户指定路径和项目约定；都没有时，写入 `docs/handoff/{yyyyMMdd-slug}-handoff/handoff.md`。

## Workflow

1. 确定交接范围，读取用户消息、项目代码上下文、项目规则和关联文档。
2. 若已有 handoff，将其作为 previous checkpoint：保留有效信息，加入新进展，移动完成事项，删除过期现场和已解决阻塞。
3. 严格按模板生成完整 checkpoint；没有证据的事项不得写入 Done，推测必须明确标记。
4. 确保内容简洁、自包含，并能让下一 Agent 直接执行第一项 Next Steps.

Fixed Template (HANDOFF-TEMPLATE.md)

# Handoff Template

使用以下固定结构生成 `handoff.md`。删除全部占位内容；除 Progress 下的 Done、In Progress、Blocked 外，不增加其它固定标题。

```md
# {Handoff Title}

> 本文件是当前工程 checkpoint。详细需求、设计和任务状态以引用的项目文档为准。

## Goal

{简要说明当前工作的目标、范围和交付边界。}

## Constraints

- {仍然生效且后续必须遵守的要求、偏好或禁止事项。}

## Progress

### Done

- [x] {已有证据的完成结果。}

### In Progress

- [ ] {尚未收口的当前工作；没有时写 None。}

### Blocked

- {阻塞、待决策或未验证事项；没有时写 None。}

## Decisions

- **{Decision}**: {Rationale}

## Next Steps

1. {下一 Agent 可以直接执行的第一项工作。}
2. {完成当前阶段所需的后续工作。}
3. {未来阶段任务及其开始条件。}

## Context

- {接手必需的文档和代码路径。}
- {接手必需的 Git 现场和未提交文件。}
- {已执行或未执行的验证及结果。}
- {必须精确保留的错误、接口或环境信息。}
```

Three Key Differences from Pi Compression

What to Keep : Next Steps first item must be directly executable; unfinished context stays in In Progress.

What to Collect : Goals, constraints, evidenced progress, and decisions go into the checkpoint; process logs are excluded to avoid polluting agent attention.

How to Continue : Completed items move to Done, expired items are deleted—no full rewrite each time. When a new phase begins, a fresh handoff file is started.

Detailed requirements, designs, and tasks remain in original project documents; handoff only handles phase-level context transfer and tracking.

Effect Demonstrations

1) Pi Agent In-Session Compression

2) Cross-Session Handoff Skill

Conclusion

The Handoff skill does one thing: decide whether the current session needs to continue or summarize a phase's tasks into a checkpoint that supplements context and tracks progress.

Context management is critical; use compression within a session, and leave a good Handoff for cross-session continuity.

GitHub repository: flyeric0212/agent-skills (contains the skill and template).