handoff

Un Claude Code Skill qui génère un fichier handoff.md — une passation propre et honnête de l'état réel du travail — pour qu'un agent neuf reprenne exactement là où la session précédente s'est arrêtée, sans retraîner les erreurs et fausses pistes de la session passée.

Inspiré du mini-guide @ia_irl sur le template handoff.md.

Pourquoi un handoff plutôt qu'un /compact

Plus une session Claude Code dure, plus l'agent perd en précision. Le réflexe courant — /compact — ne fait que résumer la conversation : un résumé garde la forme de ce qui s'est passé, y compris les hypothèses bancales et les tentatives de debug ratées. L'agent repart « propre » en apparence, mais avec les mêmes réflexes en tête.

Le handoff fait l'inverse : au lieu de compresser tout l'historique, on écrit un état des lieux net dans handoff.md, puis un agent neuf lit uniquement ce fichier. Il reçoit les faits, pas le bruit.

/compact suffit dans la majorité des cas. Le handoff brille sur les sessions longues, dégradées, ou qui tournent en rond sur une solution qui ne marche pas.

Utilisation

Dans Claude Code, en fin de session :

/handoff

…ou en langage naturel : « prépare une passation », « passe la main », « génère un handoff avant que je coupe ».

Le skill :

1. Ancre l'état dans git (status / diff / log / stash) plutôt que dans sa mémoire de la conversation
2. Archive l'ancien handoff.md dans .handoffs/ (chemin stable, historique conservé)
3. Écrit handoff.md à la racine, en suivant le template en 5 sections
4. Affiche le prompt de reprise prêt à coller dans la nouvelle session

Puis : /clear (ou nouvelle session) → on colle le prompt de reprise → l'agent neuf repart propre.

Le template en 5 sections

# Handoff — [nom du projet / de la tâche]

## 1. Objectif          — le but + le critère de « done »
## 2. État actuel        — ce qui marche (vérifié vs supposé), la dernière action
## 3. Fichiers concernés — issus de git status/diff, avec le rôle de chacun
## 4. Ce qui a échoué    — les impasses déjà tentées + le pourquoi  ← la section critique
## 5. Prochaine étape    — la toute prochaine action concrète, par priorité

La section 4 est la plus précieuse — et celle que tout le monde saute. L'agent neuf n'a aucune mémoire des essais précédents : sans elle, il re-tente logiquement les mêmes impasses. C'est elle qui transforme une simple reprise en vraie passation.

Installation

Copier le dossier dans votre répertoire de skills Claude Code :

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

Le skill /handoff est disponible au prochain démarrage de session.

Structure

handoff/
├── SKILL.md                        # quand/comment utiliser le skill (la logique)
├── references/example-handoff.md   # exemple complet d'un handoff honnête et ancré
└── evals/evals.json                # cas de test (scénarios de passation)

C'est un skill prompt-only : pas de code à exécuter, la « logique » est l'instruction que Claude suit.

Licence

MIT — voir LICENSE. Mini-guide d'origine : @ia_irl.