Home / All Skills / Workflow & Core Tools / claude-handoff
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · mattpocock/skills

claude-handoff

Hand the current conversation off to a fresh background agent that picks up the work immediately.

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 257659License MIT（GitHub API spdx MIT；仓库根 LICENSE: Copyright (c) 2026 Matt Pocock）Commit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core mechanism launches a background agent directly without writing to disk: compresses the current conversation into a handoff summary, then invokes `claude --bg` using the summary directly as the prompt to start a new agent, rather than writing a handoff document like the stable handoff skill.

skills/in-progress/claude-handoff/SKILL.md
Write a handoff summary of the current conversation so a fresh agent can continue the work. Instead of saving it, launch a background agent seeded with the summary as its prompt: `claude --bg --name "<descriptive name>" "<handoff summary>"`. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.
What is happening here: The phrase 'Instead of saving it' distinguishes this skill from productivity/handoff (which hands off via written documents)—the handoff artifact shifts from a file to an active process.

Summary discipline: Must include a suggested skills section, reference existing artifacts via path/URL instead of duplicating content, and redact sensitive information—because the summary becomes the prompt for the new agent.

skills/in-progress/claude-handoff/SKILL.md
Include a "suggested skills" section in the summary, naming which skills the next agent should call the Skill tool for.
Original redaction instruction: 'Redact any sensitive information, such as API keys, passwords, or personally identifiable information, since the summary becomes the agent's prompt.'—The summary written by the model directly serves as instructions for another agent, making redaction a critical security step.

Explicit user invocation only: Frontmatter specifies disable-model-invocation: true, paired with policy.allow_implicit_invocation: false in the Codex manifest; argument-hint prompts the user for the 'next session purpose' upon triggering.

skills/in-progress/claude-handoff/SKILL.md
argument-hint: "What will the next session be used for?"
argument-hint is Claude Code's user input prompt; the direction provided by the user is incorporated into the summary ('If the user passed arguments, treat them as a description of what the next session will focus on and tailor the summary accordingly.').

Naming convention: Must pass a descriptive name via -n/--name for display across job lists, session pickers, and terminal titles.

skills/in-progress/claude-handoff/SKILL.md
Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`); it sets the display name shown in the job list, session picker, and terminal title.
CLI parameter convention targeted at the Claude Code host; also indicates this skill's strong dependency on Claude Code (`claude` command + `claude agents` management interface).

2Core Capabilities

01Handoff the current session to a fresh background agent with a single command (`claude --bg`, returns immediately)
02Tailor summary focus and orient the next session according to user arguments
03Recommend skills for the next agent to invoke directly within the summary
04Reference existing artifacts (specs/plans/ADRs/issues/commits/diffs) by path/URL to avoid duplicated content
05Summary redaction: Redact API keys, passwords, and PII before handing off to the new agent

3External Dependencies

KindDependency / Endpoint
cliclaude (Claude Code CLI)

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Restrict working directory
For Administrators
Retain operation logs
Evidence & Triggers (File Paths & Excerpts)
  • 本地工作目录: File I/O and artifact output: The skill itself writes no files (explicitly 'Instead of saving it'); the background agent it launches continues working in the cwd according to host permissions, potentially reading and writing files.
Audit Notes: Calls the official local CLI (`claude --bg`) to hand off the conversation to a background agent: the skill itself performs no outbound network requests, reads no credentials, and writes nothing to disk. Points of attention: 1) The summary becomes the complete prompt for the new agent, requiring care around redaction and injection surfaces (untrusted conversation content may propagate across sessions); 2) The background agent continues execution in the cwd under the host's tool permissions, meaning its capabilities match the permissions granted by the host; 3) Strong dependency on Claude Code, providing limited utility across other hosts. All behaviors represent predictable local tool usage without code-level hazards.

5Second-Pass Verification

  • [ok] claude --bg 调用点真实存在 — SKILL.md 正文逐字含 ``claude --bg --name "<descriptive name>" "<handoff summary>"``，且是唯一 CLI 调用指令。
  • [ok] user-invoked 双清单（disable-model-invocation + allow_implicit_invocation: false） — 两 manifest 均存在且取值正确；in-progress README 亦标 User-invoked。
  • [ok] 不落盘 vs productivity/handoff 写文档 — 原文 'Instead of saving it, launch a background agent' 明确；productivity/handoff/SKILL.md 存在且为写文档实现，两 skill 并存无冲突。
  • [ok] suggested skills / 引用不复制 / 脱敏三段纪律 — 三段原文均在 SKILL.md（'suggested skills'、'Reference them by path or URL instead'、'Redact any sensitive information…'）。
  • [ok] argument-hint 存在 — frontmatter 含 argument-hint: "What will the next session be used for?"，且正文有对应的定向裁剪指令。
  • [ok] 无外部网络端点/凭证读取 — token 扫描零网络命中；无 env/keychain/文件凭证读取指令。claude --bg 为本地 CLI。
  • [ok] 命令注入面（安全反例检查） — 确认注入面真实存在（摘要进命令行 + 进新 agent prompt），已在 security.injection_surface 与 verdict.risks 显式记录；skill 自身无转义指令属宿主/模型责任，如实标注而非回避。
  • [ok] 元数据 — GitHub API：MIT、257659 stars、pushed_at 2026-09-04T08:45:43Z；本地 HEAD == 3cca18b。license 归属仓库根 LICENSE。

6Verdict & Scenarios

  • Zero-intermediate-state handoff: No file writes; a single command converts continued work directly into a running background agent, ideal for 'continuing work in a fresh session'.
  • Summary serves as the quality gate: Built-in disciplines for suggested skills, referencing instead of duplicating, and redaction govern cold-start quality and prevent data leakage for the new agent.
  • Preserves user edit trails and single source of truth: Avoids duplicating specs/ADRs/diffs content, preventing conflicting versions of truth.
    • Best for: Ideal for Claude Code users who hit context limits or need to shift focus while continuing the same task, handing off the session to a background agent (managed via `claude agents`), especially when work is already partially committed to specs/commits and can be referenced rather than copied.
    Not for: Not suitable for non-Claude Code hosts like Codex (commands cannot execute); not suitable for team workflows requiring auditable handoff documents (use productivity/handoff instead); not suitable for sessions containing secrets or highly sensitive data in unisolated host environments (redaction relies on model compliance).
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload claude-handoff.tar.gz
    sha256: 09e04d39f394ef5b…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.