# Write Agent Handoff > Creates an immutable continuation snapshot of active agent work, saved relative to the invocation directory. Use when a user asks to create an agent handoff, transfer work between agents or sessions, preserve context before stopping, or prepare resumption notes. - Skill: `abchoudh-amd/write-agent-handoff` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add abchoudh-amd/write-agent-handoff` - Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/write-agent-handoff/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/abchoudh-amd/write-agent-handoff --- # Write Agent Handoff Create one concise, resumption-ready snapshot from the current task state, save it, report the continuation essentials, and stop. Do not turn the handoff into new task execution. ## Routing Not for ordinary status reports, implementation plans, or PR descriptions. The feature planner's canonical blind implementation handoff is its own artifact and is never produced here. ## Required resources 1. Read [REFERENCE.md](REFERENCE.md) completely before inspecting task state. It defines evidence, freshness, redaction, Git and non-Git capture, and conflict handling. 2. Render the artifact from [templates/agent-handoff.md](templates/agent-handoff.md). Preserve its nine section headings and their order exactly once; replace every prompt. 3. Consult [EXAMPLES.md](EXAMPLES.md) for the closest matching coding, debugging, non-code, or nested-directory case. ## Workflow ### 1. Freeze the invocation location and target - Record the absolute invocation working directory before any inspection, repository discovery, or directory change. Keep that value fixed for the whole invocation. Never search for or substitute a repository root when choosing the output base; a Git root discovered later is context only. - Record a capture-start UTC timestamp now. Record the distinct capture-complete UTC timestamp after the last pre-save observation; use the latter for `Captured at`, the freshness boundary, and the default filename. - Default to `/handoffs/-handoff-.md`, where the timestamp is `YYYYMMDDTHHMMSSZ` and the slug is short kebab-case. `REFERENCE.md` holds slug construction and how a user-supplied override resolves. - Default the recipient to `next agent` when the user does not name one. ### 2. Establish a safe inspection boundary - Classify likely sensitivity from source identity, filenames, and metadata before reading content. Treat logs, environment/configuration files, authentication material, crash dumps, transcripts, and unknown user artifacts as potentially sensitive. - Keep secrets out of the capture channel, not just the finished Markdown: filter source-side before any output is emitted. Never print raw content and redact afterward. - If safe filtering is unavailable or uncertain, do not read the content. Record an unknown with its impact and a path to a sanitized export instead. - Choose the narrowest defensible sensitivity level and keep inspection and references appropriate to it. `REFERENCE.md` lists what may never appear, the redaction markers, and the access controls each level requires. ### 3. Capture the pre-save state - Use conversation context, user-supplied artifacts, and only targeted read-only live checks needed for safe continuation. - For Git work, discover repository root, branch or detached state, HEAD, concise status, staged and unstaged summaries, and only the diff details relevant to resumption. - For a graph feature workflow, read only the exact supplied workflow state. Record its revision, physical common-Git identity, frozen target, package/worktree/checkpoint map, terminal-review record, and every pushed branch/PR state. Query each recorded PR by exact number or head before calling mutable GitHub state observed; never scan for a newest state or infer missing stack members. - Capture workspace state before creating the output directory or file so the handoff does not invalidate its own snapshot. Preserve all existing files and state. - Timestamp mutable workspace, external-system, process/job, and verification claims. - Mark material claims as `[observed]`, `[reported]`, or `[inferred]`. Preserve contradictions instead of selecting a convenient version. - Record inaccessible or uncertain information as an unknown with its impact and a concrete resolution path. Do not block creation merely because a source is unavailable. ### 4. Compose the continuation contract - Use exactly one status from: `in-progress`, `blocked`, `awaiting-input`, `awaiting-external`, `ready-for-review`, or `ready-for-verification`. - State one immediate next safe action, not a menu of alternatives. - Describe commits and staged, unstaged, and untracked changes separately when present, including their intent without claiming ownership that the evidence does not support. - Populate the Feature delivery stack table from the exact state revision. Preserve total stack order, stable `WP*` identities, physical worktree paths, original and restacked commit IDs, explicit PR bases, draft/ready state, and pending operations. Use one N/A row for work that is not a graph feature workflow. - Record verification as `passed`, `failed`, `not run`, or `not applicable`; never imply success from an absent result. - Start resume steps with state revalidation. Give every step dependencies, prerequisites, and an observable done condition. - Give every blocker, risk, and unknown an owner and unblock condition, or a concrete resolution path when an owner is unknown. - State whether the output and referenced artifacts are durable or temporary. Treat any temporary path or expiring store as a risk with a safe preservation/regeneration path. - Omit checksums unless they are supplied evidence or materially disambiguate artifacts. When one is necessary, preserve the exact observed value without manual retyping and verify it before publication. ### 5. Save immutably - Never overwrite or edit an existing handoff. Treat an existing regular handoff as a collision: append `-v2`, then `-v3`, and so on before `.md`, rechecking each candidate. - If a same-task snapshot already exists in the target directory, link the newest prior snapshot from the new handoff's `References` section. Never modify the prior snapshot. - Reject a target, target directory, or newly traversed output component that is a symlink or unexpected special file. That is an unsafe-path blocker, not an ordinary collision; never follow it or relocate silently. - Publish the complete artifact with an exclusive, no-follow, no-clobber operation and verify the published content before returning. If a concurrent writer wins, retry the next version suffix; never use a check-then-overwrite sequence. `REFERENCE.md` holds the publication and access-control procedure, including when inability to enforce controls is itself a write blocker. - When `/handoffs/` is inside a Git worktree and is not ignored, record that risk in the handoff and warn the user after saving. Do not edit the target repository's ignore rules. - Run the template self-check in `REFERENCE.md`, then write exactly one new artifact. - If output creation fails, report the resolved target and blocker without modifying an older handoff or any task state. ### 6. Return and stop Return: 1. the saved path; 2. critical blockers, risks, or evidence gaps, or `none`; and 3. the single immediate next action. That return is the only post-write response. After writing, do not continue implementation, run new tests, commit, push, update issues or tickets, post or send external messages, or start, stop, or manage jobs.