handoff

Delegates implementation tasks to a background agent in a new workmux worktree with a self-contained prompt.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/wesbragagt/nixos-config --skill handoff-wesbragagt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: handoff
Source: https://github.com/wesbragagt/nixos-config/tree/main/home/skills/handoff
Command: npx skills add https://github.com/wesbragagt/nixos-config --skill handoff-wesbragagt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When you want to outsource a task to a separate agent session, that agent starts with zero context from your current conversation. This Skill packages everything diagnosed so far into a standalone brief, spins up an isolated workmux worktree, and launches a ccd agent in it so the work proceeds in the background without losing any findings. ## Core Features & Use Cases - Self-contained prompt synthesis: Writes a structured handoff brief to /tmp covering context, root-cause findings, goals, a step-by-step plan, verification commands, and constraints. - Isolated worktree creation: Uses workmux to create a session worktree off the base branch in the background, leaving your current working tree untouched. - Agent launch and verification: Sends the prompt to a ccd agent via tmux send-keys and confirms it picked up the brief by capturing the pane output. - Use Case: You just diagnosed a webhook 500 error in a docs site. Say "handoff this fix" and a new agent gets a complete brief with the root cause, the files to edit, and the exact test commands, running in its own branch while you continue other work. ## Quick Start Ask the agent to hand off the current task to a background ccd agent, optionally specifying a branch name for the new worktree.

Frequently Asked Questions about handoff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I hand off a coding task to a background Claude agent?

Invoke the handoff skill with an optional branch name. It writes a self-contained brief to /tmp, creates a workmux worktree in the background, and launches a ccd agent in the new tmux pane fed that prompt.

What is workmux and how does it create worktrees?

workmux is a tool that creates git worktrees paired with tmux sessions or windows. The command workmux add <branch> -P <prompt-file> -b copies the prompt into the worktree and keeps the new session in the background without stealing focus.

Why does the handoff agent not launch with workmux -a flag?

The -a flag fails when the repo's .workmux.yaml defines plain zsh panes with no agent placeholder, leaving nowhere to inject the command. The skill instead launches the agent explicitly via tmux send-keys targeting the new pane.

How do I monitor a handed-off agent's progress?

Attach to its tmux session with tmux attach -t '<window_prefix><branch>', run workmux dashboard, or use workmux capture <branch>. If capture reports no agent running, re-send the tmux send-keys launch command.

Does handing off a task modify my current working tree?

No. The handoff only reads conversation context and writes to a new worktree on its own branch off the base. Your current working tree remains untouched while the agent works in isolation.