convez.ai
MCP ServerProdutividadeIntermediário
Phat-Po

Handoff — Transferência Inteligente de Contexto

Phat-Po/claude-skill-handoff

Transferência de contexto entre sessões com zero perda de informação

Ver no GitHub
InicialPluginScore · de 0 a 100

Um skill para Claude Code que automatiza a transferência de contexto entre sessões, gerando documentos de handoff mínimos e mantendo um log STATUS.md no projeto. Permite que um novo agente se oriente em segundos, sem perder histórico ou precisar de prompts manuais.

Instalação

$npx convez-ai Phat-Po/claude-skill-handoff

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v1.3.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Retomar projetos após horas ou dias sem perder contexto
  • Passar tarefas entre diferentes agentes IA com documentação automática
  • Manter histórico de progresso de um projeto em um único arquivo STATUS.md
  • Criar snapshots de estado do repositório para pontos de restauração

Veredito

Solução prática e bem pensada para um problema real em fluxos de desenvolvimento IA: perda de contexto entre sessões. O STATUS.md com compressão em três camadas é inteligente, e a geração automática de handoffs reduz overhead significativamente — recomendado para quem trabalha com sessões longas ou múltiplos agentes.

README

A tradução para o português deste README ainda está na fila.

handoff — Intelligent Context Handoff for Claude Code

A Claude Code skill that lets you switch sessions without losing context. Generates a minimum-token handoff doc for the next agent and maintains a project-root STATUS.md log so a fresh session can orient itself in seconds.

Handoff — a context handoff tool for Claude Code


The pain

If you've vibecoded for more than a few weeks, you've hit this wall. Three quotes from the 2026-05-16 Hackathon Bottleneck Wall, where attendees wrote their biggest AI-coding pain on sticky notes:

Three quotes from the Hackathon Bottleneck Wall

This skill is the answer. It treats session boundaries as a first-class engineering problem — not a hope-it-works moment.


What you get

When a session wraps up, the skill produces four artifacts:

  1. A handoff document — minimum-token context transfer for the next agent.
  2. A STATUS.md log entry — appended to the project root, never overwritten.
  3. A snapshot commit — repo state matches the handoff exactly (clean starting point + restore point).
  4. A copy-paste prompt — drop into the next conversation, that's it.

It's not a template. The skill investigates what actually happened, figures out the minimum reading list, and writes a doc adapted to the specific situation.


The killer feature: STATUS.md

STATUS.md — a single auto-maintained file at the project root

Every handoff appends one entry to a STATUS.md at the project root — append-only, never overwritten, so the file becomes a scrollable history of the project. The trick: the next time you open a chat and ask "where are we?" or "what's the status of this project?", the skill auto-reads the last entry plus git log --oneline -5 and orients itself in seconds. No handoff prompt required. Finding STATUS.md becomes the default first move.

Three-layer compression (v2)

As the project grows, STATUS.md stays fast. The file uses three layers:

LayerWhat's in itAI reads this?
▲ CurrentFull detail for the latest 1-2 sessionsAlways
■ MilestonesOne-line per completed milestoneAlways (quick scan)
▼ ArchiveOldest compressed entriesOnly on demand

When the file exceeds 100 lines or 15 milestones, the /handoff skill automatically compresses older entries into one-line milestones — no manual cleanup needed. Git history preserves the detail if you ever need it.


Install

Clone into your Claude Code skills directory:

git clone https://github.com/phat-po/claude-skill-handoff ~/.claude/skills/handoff

That's it. To verify, in any Claude Code session type /handoff or just say "wrap up for next agent" — it should trigger.


Usage

The skill triggers on any of these:

  • The slash command /handoff
  • Phrases like handoff, hand off, pass to next agent, context handoff, next agent, session done, stage done, wrap up for next agent
  • Fresh-session questions like "where are we?" / "what's next?" automatically read STATUS.md

A typical handoff plays out like a four-line transcript:

Typical flow — a transcript of how a handoff actually plays out


How it gets there

Five-phase process — how it gets there

The skill is deterministic about process, not output — every handoff runs through the same five investigation phases. Phase 5.5 (STATUS.md update) handles auto-compression inline. For the complete spec, see SKILL.md.


Example

See examples/handoff-example.md for a real (sanitized) handoff document, and examples/STATUS-example.md for a sample STATUS.md log.


Anti-patterns it avoids

  • Conversation transcripts (the next agent doesn't need to know what you discussed)
  • Padding with boilerplate sections (empty "Constraints", "Database", etc.)
  • Over-including the reading list (every extra file costs tokens)
  • Assuming the next agent reads prior handoffs (each handoff is self-contained)

Changelog

v1.1.1 — Repo cleanup

  • Removed unrelated dev artifacts (internal handoff notes, TTS experiments) from the published repo
  • Renamed marketing/ → assets/ and updated README image links

v1.1.0 — STATUS.md compression + visual output

New features:

  • Three-layer STATUS.md compression — ▲ Current / ■ Milestones / ▼ Archive. Auto-compresses when file exceeds 100 lines or 15 milestones. AI reads only Current + Milestones (~30 lines) by default.
  • Clack-style visual output — banner, guide bar (┌│└), diamond indicators (◇◆), summary box. Handoff process is now scannable and satisfying to watch.
  • Passive compression check in Fresh Session Orientation — agent offers to compress if STATUS.md is oversized, without auto-doing it.

Changed:

  • Phase 5.5 now checks compression before appending (was append-only)
  • Fresh Session Orientation reads only ▲ Current + top of ■ Milestones (was full file)

v1.0.0 — Initial release

  • 5-phase handoff investigation
  • STATUS.md append-only log
  • Snapshot commit
  • Copy-paste prompt generation
  • Fresh session orientation via STATUS.md

Compatibility

  • Claude Code — primary target
  • Codex CLI — works (it reads skills from the same ~/.claude/skills/ path if symlinked, or you can adapt the SKILL.md frontmatter)
  • Other Claude-compatible agents — the SKILL.md uses standard skill frontmatter; should work anywhere the skill format is supported

Background

Built and battle-tested across many vibecoding projects by Pohan. Open-sourced after the 2026-05-16 Hackathon Bottleneck Wall, where multiple attendees wrote down the same pain on sticky notes — the three quotes above.


License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados