alirezarezvani/claude-skills / productivity/handoff/skills/session-handoff
session-handoff
VerifiedWrite a handoff document so a fresh session or another agent can pick up exactly where this one left off: goal, current state, decisions, next steps and the skills to load, referencing existing files instead of copying them, with secrets redacted before saving. Use whenever the user is ending a session, switching machines, running low on context, or asks for a handoff, a handoff doc, a 'pick up where we left off' summary, or to compact the conversation for next time. Saves to a location the user picks on first run (OS temp, home folder or per-project .handoff/) and can auto-load the latest handoff at the next session start.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.2 KB |
| SKILL.md | skill md | 9.6 KB |
| assets/example_handoff.md | markdown | 2.3 KB |
| references/configuration.md | markdown | 5.3 KB |
| references/deduplication_discipline.md | markdown | 4.5 KB |
| references/handoff_prompt.md | markdown | 4.3 KB |
| references/handoff_structure.md | markdown | 4.5 KB |
| references/redaction_checklist.md | markdown | 4.6 KB |
| scripts/cleanup.py | script | 5.1 KB |
| scripts/config_loader.py | script | 4.9 KB |
| scripts/handoff_self_check.py | script | 13.1 KB |
| scripts/handoff_template_generator.py | script | 7.9 KB |
| scripts/redaction_linter.py | script | 9.2 KB |
| scripts/setup.py | script | 9.6 KB |
| scripts/skill_recommender.py | script | 8.0 KB |
references/handoff_structure.md
View on GitHub# Handoff Structure — Five Sections, One Template
The handoff doc has exactly five sections. Use these headers verbatim — the SessionStart hook and downstream tooling expect them.
## 1. Goal of next session
One or two sentences. Either taken from the user's `argument-hint` value, or inferred from the most recent unresolved thread in the conversation.
**Good:**
> Finish wiring the redaction linter into `/cs-handoff` and ship a draft PR before EOD.
**Bad:**
> Continue working on the handoff skill.
The bad version gives the next agent no end-state. The good version tells them when to stop.
## 2. State of play
Three labelled lists. Every bullet references an artifact (commit hash, PR, branch, file path, issue).
```
- Done:
- <thing> — <artifact: commit hash, PR, file path>
- In flight:
- <thing> — <where it lives now>
- Blocked:
- <thing> — <what's blocking + who/what unblocks>
```
If `include_git_context: true` in config, the template generator pre-fills a quick git block (current branch, last commit, dirty file count). That block is informational; you still write the prose bullets above it.
## 3. Open decisions
Each decision is a question. Format:
```
- Q: <one-sentence question>
- Options considered: <a>, <b>, <c>
- Lean: <option or "no lean yet"> — <one-line reason>
- Forcing constraint: <deadline / dependency / budget>
```
If there are no open decisions, write `- None.` Do not invent decisions to fill space.
## 4. Skills to use
Hard cap at 5. Each entry: skill name + one-line *why this session needs it*.
```
- <skill-name> — <why>
- <skill-name> — <why>
```
The `skill_recommender.py` script generates a starter list scored against the goal text. Edit it. The recommender is a starting point, not the answer.
## 5. Artifacts
Paths and URLs. No bodies.
```
- PR: https://github.com/org/repo/pull/123
- Branch: feature/handoff-skill
- PRD: documentation/implementation/handoff.md
- Issue: https://github.com/org/repo/issues/456
- ADR: documentation/adr/0023-handoff-storage.md
```
## Worked example
```markdown
---
generated_at: 2026-05-21T17:42:00Z
goal: "Finish wiring the redaction linter into /cs-handoff and ship a draft PR before EOD."
---
# Handoff — 2026-05-21
## Goal of next session
Finish wiring the redaction linter into `/cs-handoff` and ship a draft PR before EOD.
## State of play
- Done:
- Redaction linter implemented and unit-tested — commit `a1b2c3d`
- First-run setup walks 5 questions and writes config — commit `d4e5f6g`
- In flight:
- Wiring `cs-handoff.md` command to call linter after template generator — uncommitted in `~/work/handoff/`
- Blocked:
- SessionStart hook smoke test on macOS — need access to mac, waiting on @teammate
## Open decisions
- Q: Should the SessionStart hook surface the *latest* handoff or *all* handoffs from today?
- Options considered: latest only, all-from-today, user-configurable
- Lean: latest only — keeps context window small
- Forcing constraint: ships in v1.0, can change in v1.1
- Q: Strict redaction mode by default, or warn?
- Options considered: strict, warn
- Lean: strict — Matt's redaction sentence implies hard enforcement
- Forcing constraint: none; reversible in config
## Skills to use
- handoff — to update this doc when work continues
- code-review — to review the PR before opening it
- security-scan — to confirm no secrets are committed alongside the linter
- update-docs — to update README with the SessionStart hook installation step
## Artifacts
- Branch: claude/handoff-skill-review-LnSxe
- Draft PR (not yet opened): will target same branch
- SKILL.md: productivity/handoff/skills/session-handoff/SKILL.md
- Linter: productivity/handoff/skills/session-handoff/scripts/redaction_linter.py
- Inspired by: https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff
```
That example is what a clean handoff looks like. Anything significantly longer is probably duplicating an artifact and should be trimmed.
## Sources
- Matt Pocock, *Handoff skill* (MIT) — the no-duplication discipline and the original four content rules.
- Karpathy, *Software 3.0 talk* (2025) — context engineering: optimize for what the next agent *cannot* recover.
- Anthropic, *Claude Code SessionStart hooks documentation* — surfacing prior context as data, not instructions.
- Google SRE Workbook, *Postmortem culture* — naming open decisions and their forcing constraints.
- DORA / Forsgren et al., *Accelerate* — referencing artifacts rather than narrating work.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |