handoff-create
Generate a structured handoff document from the current session. Captures scope, relevant files with line numbers, key discoveries, work completed, current status, next steps, and code snippets. Use before ending a session or handing work to another agent.
93%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Generate a structured handoff document from our current conversation and save it to claudedocs/handoffs/handoff_YYYYMMDD_HHMMSS.md (or use the filename provided as $ARGUMENTS[0] if given).
Create the claudedocs/handoffs/ directory if it does not exist.
Document structure
Include exactly these sections:
# Handoff: [Task Name] - [YYYY-MM-DD HH:MM]
## Task
[One sentence: what is being accomplished]
## Scope
[In-scope behavior and exclusions. Include the contract revision, base commit and relevant working-tree state, acceptance criteria, applicable ADRs, blockers, permitted actions, and next owner. Mark unknowns explicitly.]
## Files
[All relevant files touched or needed. Format: `path/to/file:line` when a specific line matters]
- `src/auth/middleware.ts:45` - token validation logic
- `tests/auth.spec.ts` - test suite for this change
- `docs/api.md` - needs update after implementation
## Discoveries
[Key findings and insights from the work so far. Things the next agent needs to know that are not obvious from the code]
- [Discovery 1]
- [Discovery 2]
## Work Done
[Historical completion claims. Append-only: never remove prior entries. Include revisions, checks actually run, and evidence links when available.]
- [x] Task A completed (commit: abc1234)
- [x] Task B completed
## Status
[Last observed state and observation time: what is done, what remains, checks and their scope, blockers. Distinguish ticket state, run state, and acceptance.]
## Next Steps
[Actionable checklist of remaining tasks, in order]
1. [ ] Step 1
2. [ ] Step 2
3. [ ] Step 3
## Code
[Relevant code snippets with context. Focus on the parts a resuming agent needs to understand immediately]
\`\`\`typescript
// Key implementation detail
\`\`\`Rules
- Keep it under 600 words total. A resuming agent should be able to load this and proceed within 30 seconds of reading.
- Use real paths and symbols; add
:lineonly when verified at the recorded revision. - Make the handoff self-contained without copying the exploratory transcript. Preserve source links and distinguish observation from interpretation.
- A handoff records authorization; it does not grant new permissions.
- "Work Done" is append-only. Never remove previous entries.
- Do not include the full git diff or full file contents. Include only the code snippets that are non-obvious.
After saving, confirm the file path.
- Revision
e0d8cbb
- Last updated
- First committed
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.