Hand Off Agent Sessions to AI Badger Without Losing Context

Where this fits

You're debugging a service that only fails in production. You have been going back and forth with your agent for 40 minutes, and the useful decisions are buried under logs and failed attempts. You need to hand off the whole session to AI Badger without re-explaining everything. The handoff skill creates a .badger-handoff file that captures the conversation state so the next agent can continue immediately.

Why agents benefit

• handoff aggressively summarizes the useful conversation, giving later decisions and corrections precedence, so agents do not act on stale instructions.
• It writes an exact BADGER-HANDOFF-V1 frame with mode: handoff, which makes the session file machine-readable and easy to parse.
• It deliberately excludes repository files, diffs, and Git state, so Badger can inspect the worktree itself without loading duplicate context.
• It distinguishes handoff from badger-review, letting teams route broad continuation vs independent review correctly.
• It enforces a 65,536-byte limit, forcing compact state files that stay cheap to load.

Practical scenarios

Moving a debugging session to AI Badger

You have traced a race condition but need a different agent's perspective. The handoff file preserves the current goal, blockers, and verification steps, so AI Badger starts from the real state instead of reading the whole transcript.

Handing off a planning session without touching the repo

When the current worktree is irrelevant, the skill can use mode: design and summarize architecture decisions only. This is useful for whiteboard-style planning before implementation begins.

Recovering after a context window reset

If your agent loses context or you switch machines, the .badger-handoff file becomes a compact recovery point. You can reload the session state and continue with the next steps without reconstructing history.

Add it to your agent workflow

Install the skill with:

npx skills add PVRLabs/aibadger --skill handoff

Then invoke it as part of a session transfer. The skill writes .badger-handoff in the current working directory and prints the absolute directory path. A minimal generated file looks like this:

BADGER-HANDOFF-V1
mode: handoff

Goal: Fix flaky WebSocket reconnect.
Progress: Reproduced on staging; root cause likely heartbeat race.
Next: Add heartbeat jitter and re-run integration test.

Compare before adopting

Before relying on handoff, compare it with badger-review: use handoff when you want the session continued, and badger-review when you want an independent second opinion. Also check how recently the repository is maintained, whether the 65KB format fits your agent runtime, and whether another handoff convention already exists in your team.

Why it is worth tracking

handoff addresses a real problem: agents waste tokens when they inherit bloated context. The summary format is opinionated and practical, and PVRLabs/aibadger is early but active enough to watch. You can track this skill and similar session-transfer tools on OpenAgentSkill at https://www.openagentskill.com/skills/pvrlabs-handoff. Evaluate it once your team starts standardizing how agents pass work to each other.