Session Handoff Skill
ibaifernandez/claude-session-handoff
Preserva contexto e estado entre sessões de agentes IA com handoffs estruturados
Ver no GitHubSkill aprimorado para Claude Code que cria e resume documentos de handoff de sessão, permitindo que agentes de IA continuem trabalhos complexos entre contextos sem perda de informação. Fixa detecção de raiz de projeto, reconhece headings em qualquer nível e adiciona flags CLI para CI/CD.
Instalação
npx convez-ai ibaifernandez/claude-session-handoff1 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
Casos de uso
- Continuar projetos complexos quando o contexto está cheio
- Passar trabalho entre diferentes agentes de IA mantendo estado completo
- Documentar decisões arquiteturais e progresso para retomar depois
- Integrar handoffs em pipelines CI/CD com validação automatizada
Veredito

Solução prática e bem-testada para um problema real em workflows com agentes IA de longa duração. A fork corrige bugs da versão original e adiciona recursos (detecção de raiz, flags CLI) que melhoram usabilidade em projetos reais.
README
A tradução para o português deste README ainda está na fila.
Session Handoff Skill
Enhanced fork. This is a community fix/enhancement of a
session-handoffskill for Claude Code that shipped preinstalled, original author unknown. The fixes, tests, and--project-root/--min-scoreflags are original work released under MIT (seeLICENSE); the base skill is credited inNOTICE.md. If you authored the original, please open an issue.
What's fixed in this fork
- Project-root detection. The validator no longer assumes a handoff lives at
exactly
<root>/.claude/handoffs/<file>.md. It walks up looking for project markers (.git,pyproject.toml,package.json,Cargo.toml,go.mod), so handoffs grouped in subdirectories resolve file references correctly instead of emitting false "file not found" warnings. - Heading matching. Section detection now matches any ATX level (
#–######), fixing required/recommended sections emitted as###being reported missing. - New flags.
--project-root <path>and--min-score <n>(CI-friendly). - Regression tests.
scripts/test_validate_handoff.py(stdlib, runs in <1s).
Overview
The Session Handoff skill creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. It solves the long-running agent context exhaustion problem by preserving complete context, decisions, and state across sessions.
Purpose
When working on complex, multi-session projects with AI agents, context gets lost between sessions. This skill provides a structured approach to:
- Preserve context - Capture all critical information before context window fills
- Enable continuity - Allow new agents to pick up exactly where you left off
- Document decisions - Record architectural choices and their rationale
- Track progress - Maintain clear status of completed and pending work
- Chain sessions - Link related handoffs for long-running projects
When to Use
User-Triggered
- User says "save state", "create handoff", "I need to pause"
- User requests "load handoff", "resume from", "continue where we left off"
- User mentions "context is getting full" or "save this for later"
Agent-Triggered (Proactive)
- Context window approaching capacity (>80% full)
- Major task milestone completed
- Work session ending with significant progress
- After substantial work (5+ file edits, complex debugging, architecture decisions)
- Before switching to a different task
Resumption Scenarios
- Starting a new session on an existing project
- Different agent needs to continue the work
- Need to recall decisions made in previous sessions
- Picking up after a long break
How It Works
The skill operates in two primary modes:
CREATE Mode
Generates a comprehensive handoff document capturing current state:
- Generate Scaffold - Smart script pre-fills metadata (timestamp, git status, modified files)
- Complete Document - Fill in critical sections (state, context, decisions, next steps)
- Validate - Automated checks for completeness, quality, and security
- Confirm - Present location and summary to user
RESUME Mode
Loads and validates existing handoff documents:
- Find Handoffs - List available handoffs in project
- Check Staleness - Assess if context is still current
- Load Document - Read handoff (and chain if linked)
- Verify Context - Validate assumptions and environment
- Begin Work - Start from "Immediate Next Steps"
Key Features
Smart Scaffolding
The create_handoff.py script automatically captures:
- Timestamp and project path
- Current git branch and recent commits
- Modified and unstaged files
- Handoff chain links (if continuing from previous)
Validation & Quality Assurance
The validate_handoff.py script checks:
- No incomplete
[TODO: ...]placeholders - All required sections populated
- No potential secrets (API keys, passwords, tokens)
- Referenced files exist
- Quality score (0-100)
Project-root detection. Referenced files are resolved against the project
root, which is auto-detected by walking up from the handoff looking for a
marker (.git, pyproject.toml, package.json, Cargo.toml, go.mod). This
works regardless of how deeply the handoff is nested (e.g. handoffs grouped in
subdirectories under .claude/handoffs/). If no marker is found, it falls back
to a fixed-depth heuristic and prints a [WARN]. Override detection with
--project-root <path>.
Section matching. Required/recommended sections are matched at any ATX
heading level (#–######), so sections emitted as ### by the template are
detected correctly.
Options:
--project-root <path>— explicit project root for resolving file references.--min-score <n>— minimum score for aREADYverdict (default70); useful in CI.
Staleness Detection
The check_staleness.py script assesses:
- Time elapsed since handoff creation
- Git commits made since handoff
- Files changed since handoff
- Branch divergence
- Missing referenced files
Handoff Chaining
For long-running projects, chain handoffs together:
handoff-1.md (initial work)
↓
handoff-2.md --continues-from handoff-1.md
↓
handoff-3.md --continues-from handoff-2.md
Each handoff links to its predecessor, providing context breadcrumbs for new agents.
Usage Examples
Creating a Handoff
Basic handoff creation:
python scripts/create_handoff.py implementing-user-auth
Continuation handoff (linked to previous):
python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
Validate before finalizing:
python scripts/validate_handoff.py .claude/handoffs/2024-01-15-143022-implementing-auth.md
Resuming from a Handoff
List available handoffs:
python scripts/list_handoffs.py
Check if handoff is current:
python scripts/check_staleness.py .claude/handoffs/2024-01-15-143022-implementing-auth.md
Load and continue work:
- Read the handoff document completely
- Verify context using resume checklist
- Start with first item in "Immediate Next Steps"
Handoff Document Structure
A complete handoff includes:
- Metadata - Timestamp, project path, git branch, commits
- Current State Summary - What's happening right now
- Important Context - Critical information for next agent
- Decisions Made - Architectural choices with rationale
- Immediate Next Steps - Clear, actionable first steps
- Pending Work - Remaining tasks and priorities
- Critical Files - Important locations and their purpose
- Key Patterns Discovered - Conventions and approaches
- Potential Gotchas - Known issues and workarounds
- Handoff Chain - Links to previous/next handoffs
See references/handoff-template.md for the complete template.
Storage Location
Handoffs are stored in: .claude/handoffs/
Naming convention: YYYY-MM-DD-HHMMSS-[slug].md
Example: 2024-01-15-143022-implementing-auth.md
Scripts Reference
| Script | Purpose | Usage |
|---|---|---|
create_handoff.py | Generate new handoff with smart scaffolding | python scripts/create_handoff.py [slug] [--continues-from <file>] |
list_handoffs.py | List available handoffs in a project | python scripts/list_handoffs.py [path] |
validate_handoff.py | Check completeness, quality, and security | python scripts/validate_handoff.py <file> [--project-root <path>] [--min-score <n>] |
check_staleness.py | Assess if handoff context is still current | python scripts/check_staleness.py <file> |
Quality Standards
Do not finalize a handoff if:
- Validation score is below 70
- Secrets are detected
[TODO: ...]placeholders remain- Required sections are empty
Best practices:
- Write clear, specific next steps (not vague goals)
- Document the "why" behind decisions, not just the "what"
- Include code snippets for critical patterns
- Reference specific file paths and line numbers
- Update handoffs as work progresses
References
- handoff-template.md - Complete template structure with guidance
- resume-checklist.md - Verification checklist for resuming agents
- evals/model-expectations.md - Model behavior expectations
- evals/test-scenarios.md - Test cases for handoff creation and resumption
Benefits
- Zero ambiguity - New agents know exactly what to do
- Context preservation - No loss of critical information
- Decision history - Understand why choices were made
- Reduced onboarding - Faster agent startup on existing work
- Quality assurance - Automated validation prevents incomplete handoffs
- Security - Secret detection prevents credential leaks
- Long-term memory - Handoff chains maintain project history