Session Handoff: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas.

Prompt

Installs to .agents/skills/session-handoff-agent-skill-skill-md-for-claude-code-codex-and-c/

mkdir -p .agents/skills/session-handoff-agent-skill-skill-md-for-claude-code-codex-and-c && curl -sL "https://prompts-gpt.com/prompts/session-handoff-agent-skill-skill-md-for-claude-code-codex-and-cursor/raw" -o .agents/skills/session-handoff-agent-skill-skill-md-for-claude-code-codex-and-c/SKILL.md
SKILL.md
Preview
---
name: session-handoff-agent-skill-skill-md-for-claude-code-codex-and-c
description: "Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas."
---

# Session Handoff: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas.

## Prompt

```
---
name: session-handoff
description: "Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas. Use when asked for a handoff, a summary to continue later, 'write this up for the next session', before clearing context, or when passing work to someone else."
---

# Session handoff

Write a document that lets someone with zero context pick up the work where you left it.

## Steps

1. Review the session and the current state of the work. In a repo, run `git status`, `git log --oneline -5` and `git diff --stat` to get the branch, uncommitted changes and recent commits. Note the last command results and anything left half-done.
2. Write the handoff with these sections, in order:
   - Goal: what the work is for and what done looks like, in two lines.
   - Current state: what works, what doesn't, what's half-done. Branch name and last commit if relevant.
   - Decisions: each decision made and the reason, one line each.
   - Files touched: paths, with one line on what changed in each.
   - Commands that work: exact commands to build, test, run or reproduce, copied verbatim.
   - Tried and ruled out: approaches that failed and why, so nobody repeats them.
   - Open questions: what's unknown and who or what can answer it.
   - Next 3 steps: concrete, ordered, each small enough to start right away.
   - Gotchas: env vars, flaky tests, slow steps, things that look wrong but aren't.
3. Read it as a stranger would. Replace every "it", "the fix" and "that issue" with the actual name, path or error message.
4. Save it where the user asked, or show it inline. If they want a file, suggest HANDOFF.md at the repo root and don't commit it unless they ask.

## Rules

- Under one page, about 400 words. Cut anything the reader doesn't need to act.
- No story of the conversation ("first we tried, then"). State facts.
- Paths, commands, error messages and IDs go in verbatim, in code formatting.
- Separate what you verified from what you believe; mark the latter "unverified".
- No secrets or tokens. Name the env var instead of its value.

## Example output

```
Goal: checkout rejects expired coupons; done when the #412 acceptance tests pass.
State: API check done and tested; UI message not started. Branch fix/coupon-expiry, last commit a1b2c3d.
Ruled out: checking expiry in the DB query (breaks the admin coupon list).
Next: 1) add the message to src/checkout/CouponField.tsx 2) e2e test in e2e/coupon.spec.ts 3) open the PR
Gotcha: tests need TZ=UTC or the boundary test fails.
```
```

## Usage Notes

Save as .claude/skills/session-handoff/SKILL.md in one project (or ~/.claude/skills/session-handoff/ for all of them); Codex reads .agents/skills/session-handoff/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill session-handoff.

Example output

At a glanceNext 3 steps in the webhook retry handoffWhere the next agent picks up on branch feat/webhook-retry
  1. Wire up dead-letter handlingStep 1Call move_to_dead_letter() when attempt_count >= 5, add a test
  2. Commit model and migrationStep 2Commit the model change and migration 0047
  3. Extend admin webhook logStep 3Add attempts and status column to admin/webhooks.html

Example for: a Python service adding retry logic to a webhook sender, handed off before clearing context.

HANDOFF: Webhook retry with backoff

Goal: Failed outbound webhooks retry with exponential backoff (max 5 attempts) instead of being dropped. Done when ticket WH-238 acceptance tests pass and retries show in the /admin/webhooks log.

Current state:

  • Retry scheduler works and is tested (tests/test_retry.py, 14 passing).
  • Admin log view is not started.
  • Dead-letter handling is half-done. move_to_dead_letter() exists but nothing calls it yet.
  • Branch feat/webhook-retry, last commit 7e91c4f ("add backoff scheduler"). There are 2 uncommitted files, listed under Files touched.

Decisions:

  • Backoff is 2^attempt * 30s with ±10% jitter. Jitter keeps retries from all landing at once on a recovering endpoint.
  • Retries run as Celery tasks with countdown, not a cron sweep. That way there is no new infrastructure to add.
  • Only HTTP 5xx and timeouts retry. A 4xx means the payload is bad, so retrying won't help.

Files touched:

  • app/webhooks/sender.py: wraps send() in schedule_retry() on failure.
  • app/webhooks/retry.py (new): backoff math and move_to_dead_letter().
  • app/models/webhook_event.py: adds attempt_count and next_retry_at. Uncommitted.
  • migrations/0047_webhook_retry_fields.py: migration for the two fields above. Uncommitted.

Commands that work:

docker compose up -d redis postgres
alembic upgrade head
pytest tests/test_retry.py -q
celery -A app.worker worker --loglevel=info

Tried and ruled out:

  • tenacity inside the request thread. It blocks the worker for up to 8 minutes and fails test_send_nonblocking.
  • Storing retry state in Redis only. State is lost on restart, which violates WH-238 criterion 3.

Open questions:

  • Should dead-lettered events alert anyone? Ask Priya Okafor (product owner for WH-238).
  • Does staging Celery have task_acks_late=True? This is unverified. Check deploy/staging/celery.env.

Next 3 steps:

  1. Call move_to_dead_letter() in retry.py when attempt_count >= 5, and add a test.
  2. Commit the model change and migration 0047.
  3. Add an attempts and status column to templates/admin/webhooks.html.

Gotchas:

  • Tests need CELERY_TASK_ALWAYS_EAGER=1 set, or the retry tests hang.
  • test_jitter_bounds is seeded via RETRY_RANDOM_SEED. Without the seed it fails about 1 run in 50.
  • Migration 0046 shows a "multiple heads" warning. That is expected because it merged two branches. Ignore it.
  • WEBHOOK_SIGNING_KEY must be set locally. Get it from the team vault and do not commit it.
Written by AI from this prompt. Your results will vary.

Save as .claude/skills/session-handoff/SKILL.md in one project (or ~/.claude/skills/session-handoff/ for all of them); Codex reads .agents/skills/session-handoff/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill session-handoff.

Make it repeatable

Keep using this prompt without pasting it in every time.

Prompt details

By
Prompts-GPT editors
Published
How prompts are written and checked

Did this prompt work?

Keep exploring

More in Writing