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_prompt.md
View on GitHub# Handoff Prompt — Mandatory Checklist for the Agent
This is the discipline that turns a free-hand summary into a faithful handoff. Walk every item before writing the doc. **No exceptions.**
The goal of the checklist is one thing only: prevent the model from free-handing a rosy summary that drops the actual blockers.
## Step 1 — Walk the conversation explicitly
For **each topic** discussed in the conversation, classify it as exactly one of:
1. **Include in State of play** — work that's done, in flight, or blocked. Reference the artifact (PR, branch, commit, file path).
2. **Log as an Open decision** — a question the next agent must answer before continuing.
3. **Drop with reason** — out of scope for the handoff. Note it inline as a comment if the decision to drop is non-obvious.
If a topic spans multiple classifications, split it. Do not merge.
> **Anti-pattern:** writing the State section by skimming the conversation top to bottom. That misses dropped threads and blocked items that came up mid-conversation.
## Step 2 — Verify each State item against an artifact
For every bullet in **State of play**, name the artifact that proves it:
- "Implemented X" → name the commit hash or PR number.
- "Tested Y" → name the test file or CI run.
- "Documented Z" → name the doc path.
- "Blocked on W" → name the issue, comment, or external party.
If you cannot name an artifact, the item is either not yet done, or it's an Open decision. Reclassify.
> **Anti-pattern:** "Implemented the new endpoint." — vague, unverifiable, and the next agent has no idea where to look.
## Step 3 — Surface every Open decision
A handoff that hides decisions makes the next session repeat work. For each decision:
- State the question in one sentence.
- List the options already considered (even if rejected).
- State which option you lean toward and why — or "no lean yet."
- Name the constraint that forces the decision (deadline, budget, dependency).
> **Anti-pattern:** "TODO: figure out caching." — gives the next agent no starting point.
## Step 4 — Pick 3-5 skills, no more
For **Skills to use**:
- Hard cap at 5.
- Each entry: skill name + one-line *why this session needs it*.
- If you find yourself listing more than 5, you haven't picked. Choose.
- If you find yourself listing fewer than 3, ask: is something obvious missing? (Often a review skill or a verifier.)
> **Anti-pattern:** listing every skill that might be tangentially useful. The reader stops reading after item 8.
## Step 5 — Artifacts as paths and URLs only
For **Artifacts**:
- Branches, PRs, issues, file paths, doc URLs.
- One line each.
- Never paste content. If the next agent needs to see the diff, they open the branch.
> **Anti-pattern:** pasting the PRD because "what if they can't access it?" If they can't access it, the link is the bug — fix that, don't duplicate.
## Step 6 — Run the redaction linter before saving
Before save, the linter scans for secrets and PII. In strict mode it blocks save until findings are resolved. Use the inline marker `<!-- handoff:allow secret -->` to whitelist a specific match if it's a false positive.
Patterns it cannot catch (do these by eye):
- Internal hostnames and IPs that aren't shaped like obvious secrets.
- Names of customers, partners, or unrelated third parties.
- Free-form leakage in narrative ("Last week Ann from FinCo asked us to…").
## Step 7 — Compare against Matt's no-duplication rule
Final pass before save:
- Does any section paste content that exists elsewhere? Replace with a link.
- Does any section narrate the conversation linearly? Compress to State + Decisions.
- Does any bullet say "the user did X"? Rewrite as the artifact (commit, message, decision).
## What "done" looks like
A handoff is done when:
1. Every State bullet has an artifact reference.
2. Every Open decision has a one-sentence question + at least one option.
3. Skills to use has between 3 and 5 entries.
4. Artifacts has only paths/URLs.
5. Redaction linter exits clean (or all findings are whitelisted with reason).
6. A fresh agent could pick up the work without reading the original conversation.
Test the last item by asking yourself: *if I close the conversation right now and a stranger opens this doc, do they know the next 30 minutes of work?* If no, go back to Step 1.
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 |