handover-skills
CoachSteff/handover-skills
Handover & Resume — session-continuity skills for Claude Code / Craft Agents
Instalação
npx convez-ai CoachSteff/handover-skills1 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
README
A tradução para o português deste README ainda está na fila.
Handover & Resume — Session Continuity Skills
A pair of skills for Claude Code and Craft Agents that keep long coding sessions from degrading. They treat a session boundary as state transfer, not conversation summary — you write the truth into durable files inside your project, then start a fresh session that reconstructs state from those files instead of from a giant, noisy transcript.
Two skills, one contract:
| Skill | Command | What it does |
|---|---|---|
| Handover | /handover | At a milestone or phase change, captures the session's real state into in-repo artifacts and writes a self-contained startup brief. |
| Resume | /resume | In a fresh session, reads the brief, verifies it against the live files and git, reconciles any drift, then restates the plan before changing anything. |
Why bother
Long sessions fail in two ways: the context window fills with noise, and the model starts trusting its own stale summary over the actual code. Compaction helps you stay in one thread, but when you cross a boundary — finishing a milestone, switching phases, or noticing drift — a clean restart from explicit files is more reliable. These skills make that restart disciplined and repeatable.
The loop
session 1 (build) ──/handover──▶ writes artifacts ──▶ START A NEW SESSION ──/resume──▶ session 2 (build)
The fresh session is the whole point. /handover ends by telling you to open a new session and
run /resume there — it will not resume in the same polluted context.
Artifacts (all live inside your project repo)
{project-root}/
├── PROGRESS.md # living log — appended every milestone, never wiped
├── HANDOVER.md # the latest self-contained brief — overwritten each handover
├── handover/ # visible archive of timestamped snapshots, one per handover
│ └── HANDOVER-YYYY-MM-DD-HHMM.md
└── init.sh # optional deterministic startup (install / build / serve)
Because the artifacts live in the repo, a handover travels with your code — clone the project, get the state.
HANDOVER.md structure
The brief uses XML-tagged sections so the next session can parse fields unambiguously while staying human-readable:
<mission>— what the project is and what "done" means for the current phase<current_state>— what works (verified), what's half-built, what's broken<artifacts>— repo/branch, key files, how the app runs, where tests live<decisions>— settled choices that must not be reopened, with the why<constraints>— hard limits and forbidden moves, read from the project itself<verification>— what was actually run vs assumed<next_steps>— exact next actions, in order<unknowns_and_do_not_assume>— explicit gaps to verify before acting<source_of_truth_rank>— precedence when the brief disagrees with reality<startup_protocol>— what to read and run before answering or editing
Two of these do the heavy lifting against hallucination: the verified-vs-assumed split (unverified
claims go to <unknowns>, never to <current_state>) and <source_of_truth_rank> (a fixed
precedence — running code > tests > docs > PROGRESS.md > this HANDOVER > older handovers — so a
stale brief can never override live code).
Install
Drop both folders into your agent's skills/ directory:
- Claude Code:
~/.claude/skills/(global) or.agents/skills/(per-project) - Craft Agents: your workspace's
skills/folder
skills/
├── handover/
│ ├── SKILL.md
│ └── icon.svg
└── resume/
├── SKILL.md
└── icon.svg
Then invoke /handover and /resume. No external services, sources, or memory systems required —
the only dependencies are git and a shell.
When to use which
- Use
/handoverat a boundary: a milestone is stable, you're switching phases, the conversation has drifted, or you're stopping for the day. Not for trivial mid-thread saves. - Use
/resumeat the start of a fresh session on a project that already has aHANDOVER.md. It verifies before it trusts, and it won't edit until it has restated the plan.
License
© 2026 Steff VanHaverbeke (CoachSteff). Licensed under CC BY-SA 4.0 — a copyleft license. You may share and adapt this material, including commercially, as long as you credit Steff VanHaverbeke (CoachSteff), link to the license, indicate any changes, and license your derivatives under the same terms. See LICENSE.