handoff

name	handoff
description	Generate a session handoff document for successor agents working on this skill-library repo. Use when the user types '/handoff' or asks to create a handoff. Reads the previous handoff (if any) for continuity, generates a new one with today's date, saves it to .agents/handoffs/, and archives the previous one to .agents/handoffs/archive/.

Handoff Skill (repo-maintenance)

Generate effective session handoff documents that enable successor agents to continue work on this skill-library 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

1. Reads previous handoff from .agents/handoffs/handoff-[YYYY-MM-DD].md (most recent if multiple) to understand trajectory and maintain continuity
2. 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
3. Generates new handoff following the structured template
4. Saves as .agents/handoffs/handoff-[TODAY].md
5. Archives previous handoff to .agents/handoffs/archive/handoff-[OLD-DATE].md

All steps happen automatically without confirmation prompts.

Handoff document 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

Watch-Outs for Successor

• Tasks that seem simple but aren't
• Hidden dependencies
• Quality standards

What Worked Well / What To Do Differently

• Collaboration patterns that were productive
• Process improvements needed

Context for Specific Files

• File-by-file notes on status, quirks, dependencies

Session Metadata

• Agent, date, goals
• Continuation priority

Key principles for generation

1. Be specific: "File Y has hidden dependency on Z because of reason R" not "Watch out for X"
2. Capture the invisible: What seemed obvious in context but won't be obvious to successor?
3. Save time: What would you want to know picking this up fresh? What did you learn the hard way?
4. Be honest: Mistakes and dead ends are valuable intelligence
5. Think forward: What enables successor to maintain momentum vs. starting from scratch?
6. Prioritize ruthlessly: Focus on what materially affects successor's effectiveness
7. Maintain narrative continuity: Reference previous handoff observations — did predicted issues materialize? Did recommended approaches work?

Example bad vs. good entries

Bad: "Be careful with the catalog" Good: "If you add or rename a skill directory under skills/, you must also update CATALOG.md. The AGENTS.md constraints section calls this out but it's easy to forget when focused on SKILL.md content."

Bad: "Some skills still need work" Good: "The cyberneutics skills have no version in their frontmatter and haven't declared tested-tools. Before publishing a new release, these need to be brought in line with CONTRIBUTING.md requirements."

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.

No redundancy: Don't repeat what's already in AGENTS.md, CONTRIBUTING.md, or CATALOG.md. 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, execute the skill:

1. Read .agents/handoffs/handoff-*.md (most recent if multiple)
2. Analyze the current session transcript
3. Generate comprehensive handoff document
4. Save as .agents/handoffs/handoff-[TODAY].md
5. Move previous handoff to .agents/handoffs/archive/
6. Confirm completion: "Handoff document created: .agents/handoffs/handoff-[TODAY].md (previous handoff archived)"

No intermediate confirmations or reviews — generate and save directly.