Handoff to Claude Code

This skill sends work to a local Claude Code session and returns its output.

SKILL_DIR below is the directory that contains this SKILL.md. On a new machine, run this once to confirm that Claude Code is installed and logged in:

python3 "$SKILL_DIR/scripts/handoff.py" doctor

Choose a mode

python3 "$SKILL_DIR/scripts/handoff.py" chat  "Why does this crash on startup?"
python3 "$SKILL_DIR/scripts/handoff.py" agent "Port the auth module to the new API and run the tests"

For a long or multi-line prompt, pass - and send the prompt on stdin:

python3 "$SKILL_DIR/scripts/handoff.py" agent - <<'EOF'
Refactor the parser so that ...
EOF

Read the output

Each run prints Claude Code's output, followed by a metadata footer:

--- handoff metadata ---
session: 6b1c…
model: claude-opus-5
cost_usd: 0.12
duration_s: 41
dir: /path

The footer is for you. Do not show it to the user. Use session: for follow-up turns and model: for the attribution line.

Relay chat output verbatim

Everything above the --- handoff metadata --- line is Claude Code's answer. Put it in your final message exactly as printed, with the same words, markdown, and order. Precede it with one attribution line:

— via Claude Code (claude-opus-5) —

Do not summarize, reformat, or comment on the answer, and do not mix it into your own text.

Summarize agent output

The result of an agent run is the work on disk. Read the output and tell the user, in your own words, what changed, what was verified, and what is still open.

Continue a thread

To ask a follow-up question in the same thread, pass the session id from the footer:

python3 "$SKILL_DIR/scripts/handoff.py" chat --session 6b1c… "And what about the timeout path?"

Run every turn of a thread from the same directory, or with the same --dir.

Long runs

An agent run can take many minutes, which may exceed your shell tool's timeout.

• If your harness can run shell commands in the background, use that. Make the handoff command the entire command line, and use --dir <path> instead of cd <path> &&.
• Otherwise, add --background. The command prints a job id and returns immediately. Use the job id with these commands:

python3 "$SKILL_DIR/scripts/handoff.py" agent --background "Migrate all call sites"
python3 "$SKILL_DIR/scripts/handoff.py" status <job-id>
python3 "$SKILL_DIR/scripts/handoff.py" tail   <job-id> -n 40
python3 "$SKILL_DIR/scripts/handoff.py" wait   <job-id> --timeout 600
python3 "$SKILL_DIR/scripts/handoff.py" kill   <job-id>

A running job keeps using the user's subscription. Run kill when the user changes their mind or a job is stuck.

Other options

• --model <name>: use a specific model. Without it, Claude Code uses the user's default model, which is usually what they want.
• --yolo: skip all permission checks. Use it only when the user asks for it, or when a normal run was blocked by permissions and the user agrees.
• --dir <path>: run in a directory other than the current one.
• --no-auth-check: bill the user's API key instead of their subscription. Use it only when the user asks for API-key or gateway billing.

When a run fails

If the output contains [handoff] ERROR: …, the failure needs a person to fix it, for example an expired login or a used-up usage limit. Report the error to the user and do not retry.

For other commands, options, and troubleshooting, see reference.md in this directory.