Handoff Write

Handoff Write

Produce a self-instructing handoff document that any LLM agent can pick up — Claude Code, Codex, Cursor, Gemini, GPT — even ones that have never heard of this plugin. The doc carries its own pickup protocol at the top (bootstrap block).

Always do this first

Before any action, read in this order:

1. references/instructions.md — heuristics for depth, pre-flight gates, file/git resolution, redaction rules, INDEX writing, output report shape.
2. references/template.md — canonical doc structure (sections, per-depth inclusion, slug rules).
3. references/bootstrap.md — the literal block to inject at the very top of every doc.

Do not skip the read step. The dispatcher below is intentionally minimal — every operational detail lives in references/.

Universal rules

1. Paths use absolute form in INDEX and user-facing output. Relative paths only inside the workspace .handoffs/ directory.
2. Timestamps are local time in YYYY-MM-DD HH:MM format, no timezone suffix. ALWAYS obtain the current time by running date '+%Y-%m-%d %H:%M' — never estimate it from conversation context.
3. Redact secrets aggressively — API keys, tokens, passwords, bearer headers, .env values, internal IPs, third-party emails/PII. Replace with >. Never let a secret reach the doc, even if the user pasted it earlier in the conversation.
4. Don't duplicate content already in a Plan, PRD, ADR, Issue, commit, or diff. Reference by path/URL/SHA. The one exception is verbatim user-quote constraints in Section 4 — those are duplicated on purpose because the receiver needs them inline.
5. No emojis in file content beyond the template's ✅/🔄/⏸️ status markers.
6. Output language follows the user's conversation language for the doc body and user-facing skill output. The bootstrap block stays English — it's the agent-to-agent protocol; keeping it monolingual maximizes pickup reliability across diverse LLMs.
7. Two storage locations are touched: workspace /.handoffs/.md (the doc) and a central index file ($HANDOFF_INDEX_PATH or ~/.claude/handoffs/INDEX.md). Both must stay in sync; if one write fails, surface the inconsistency to the user.
8. Mention the related sub-skills in the report: /handoff-resume for pickup, /handoff-list to browse, /handoff-archive to clean up.

Pre-flight confirmation gates

Confirm with the user BEFORE writing only in these cases:

• Depth was bumped to exhaustive (potentially large doc — user should know first).
• .handoffs/ doesn't exist yet in this repo (first-time setup deserves a heads-up).

In all other cases, write immediately and report. Friction-free for the common case.

Versioning

Bootstrap block carries `` marker. Future schema changes bump to v2; resume reads the version and dispatches accordingly. Current version: v1.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aploe
• Source: aploe/claude-handoff-skill
• License: MIT

Install and usage instructions live in the source repository linked above.