| name | handoff |
| description | Generate a session handoff document for successor agents. Use when the user types '/handoff' or asks to create a handoff. Reads the previous handoff (if any) for continuity, generates a new handoff with today's date, saves it to .agents/handoffs/, and archives the previous one to .agents/handoffs/archive/.
|
| license | MIT |
| compatibility | ["codex","claude-code","opencode"] |
| metadata | {"author":"cyberneutics","version":"0.1.0","tags":["automation"],"tested-tools":["claude-code"]} |
Handoff Skill
Generate effective session handoff documents that enable successor agents to
continue work on this repository, avoiding pitfalls encountered and building
on lessons learned that aren't captured in formal documentation.
When to use
- User types
/handoff
- User asks to "create a handoff" or "write a handoff document"
- End of a significant work session when continuity matters
- After completing major milestones or before known breaks
What the skill does
- Reads previous handoff from
.agents/handoffs/handoff-[YYYY-MM-DD].md (if exists) to understand trajectory and maintain continuity
- Analyzes current session to extract:
- What was accomplished
- What mistakes were made and lessons learned
- What dead ends were explored
- Current state of work (completed, in-progress, blocked)
- Immediate next steps for successor
- Generates new handoff following the structured template
- Saves as
.agents/handoffs/handoff-[TODAY].md
- Archives previous handoff to
.agents/handoffs/archive/handoff-[OLD-DATE].md
All steps happen automatically without confirmation prompts.
Handoff document structure
The generated handoff follows this structure:
Session Summary
- Duration and main accomplishments
- Original intent vs. actual outcome
- Key deliverables
Mistakes and Lessons
- Specific mistakes made during session
- Root causes and how to avoid them
- Concrete examples
Dead Ends Explored
- Approaches that didn't work and why
- What was learned from failures
- Conditions under which they might be worth revisiting
Current State
- Completed this session
- In progress (with blockers)
- Not yet started but planned
Immediate Next Steps
- Prioritized, actionable tasks
- Context for why each is ready
- Dependencies and blockers
Open Questions and Decisions Needed
- Questions requiring human input
- Topics needing research/exploration
Technical Notes
- Repository structure quirks
- Tools and workflow notes
- File management approach
Watch-Outs for Successor
- Tasks that seem simple but aren't
- Hidden dependencies
- Quality standards
Theoretical/Conceptual Notes
- Key insights from session
- Unresolved tensions
- How understanding evolved
What Worked Well / What To Do Differently
- Collaboration patterns that were productive
- Process improvements needed
- Communication adjustments
Context for Specific Files
- File-by-file notes on status, quirks, dependencies
Session Metadata
- Agent, date, goals
- Continuation priority
Key principles for generation
-
Be specific: "File Y has hidden dependency on Z because of reason R" not "Watch out for X"
-
Capture the invisible: What seemed obvious in context but won't be obvious to successor?
-
Save time: What would you want to know picking this up fresh? What did you learn the hard way?
-
Be honest: Mistakes and dead ends are valuable intelligence
-
Think forward: What enables successor to maintain momentum vs. starting from scratch?
-
Prioritize ruthlessly: Focus on what materially affects successor's effectiveness
-
Maintain narrative continuity: Reference previous handoff observations—did predicted issues materialize? Did recommended approaches work? What trajectory is the work following?
Example bad vs. good entries
Bad: "Be careful with the evaluation rubrics"
- Not specific, not actionable
Good: "The evaluation-rubrics-reference.md has examples that reference other artifacts. If you change artifact names/structure, those examples need updating too. Caught this when we moved files and examples broke."
- Specific, explains why it matters, gives concrete scenario
Bad: "The user prefers good documentation"
- Everyone prefers good documentation, this says nothing
Good: "The user prefers examples over abstract explanation. When explaining theoretical concepts, noticed engagement increased significantly when we included concrete transcripts/examples rather than just describing patterns."
- Specific observation, actionable pattern
Bad: "Some tasks still need to be done"
- Obvious from the task list already
Good: "The config migration task is listed as 'pending' but the scope hasn't been defined beyond the title. Before starting, confirm: does this cover only the YAML schema change, or also updating all downstream consumers? Those are different tasks with very different scope."
- Identifies real ambiguity, suggests clarifying question, prevents wasted effort
Implementation notes
File naming: handoff-YYYY-MM-DD.md using today's date
Archive location: .agents/handoffs/archive/ — ensure directory exists before moving files
Reading previous handoff: If multiple handoffs exist in .agents/handoffs/, read the most recent (by date in filename). Don't read from archive/ — those are historical.
Continuity narrative: The handoff should note:
- What the previous handoff predicted/recommended
- Whether those predictions were accurate
- What trajectory the work is following
- Evolution of understanding about user preferences
- Patterns that are becoming clearer over multiple sessions
No redundancy: Don't repeat what's already in repository documentation. The handoff is for meta-context, session-specific intelligence, and invisible knowledge.
Tone: Direct, practical, specific. Written for another AI agent picking up the work. Be frank about mistakes and unknowns.
Usage
When user types /handoff, simply execute the skill:
- Read
.agents/handoffs/handoff-*.md (most recent if multiple)
- Analyze the current session transcript
- Generate comprehensive handoff document
- Save as
.agents/handoffs/handoff-[TODAY].md
- Move previous handoff to
.agents/handoffs/archive/
- Confirm completion: "Handoff document created: .agents/handoffs/handoff-[TODAY].md (previous handoff archived)"
No intermediate confirmations or reviews—generate and save directly.
