| name | pm-handoff |
| description | Use this skill when the user wants to hand off work to another person or to the next stage of the lifecycle. Trigger phrases "hand this off to", "give this to", "I'm OOO", "passing this to", "covering for", "ready for release", "ready for QA", "ready for review", "release notes", "deploy handoff", "write a handoff", "/pm-handoff". Produces recipient-facing briefs with four required blocks (summary, what's done + how to use it, what's NOT done + next steps, open questions). Routes through configured channels (Linear, GitHub, markdown, chat/email). |
| version | 0.44.4 |
PM Handoff
Cross-team handoff context (v0.21.0+)
When --scope team:<KEY>[+subteams] is passed (or the handoff naturally spans more than one team), pull the in-scope issues with scope-briefing before drafting the brief. Use the result to populate "Recent work" and "What's not done" with concrete issue IDs rather than vague references.
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-cache.js" scope-briefing --scope "team:ENG+subteams"
The four-block invariant (summary, done + how to use, NOT done + next steps, open questions) still applies — scope just gives you more accurate raw material to fill the blocks.
Produce a recipient-facing brief that moves work forward — either to another teammate (cross-person handoff) or to the next phase of the lifecycle (cross-stage handoff). The brief packages what's done, how to use it, what's NOT done, and what's open, then routes through configured channels.
This skill is downstream of every other pm-* skill that creates state. It's how work leaves your hands cleanly.
The load-bearing claim
A handoff is not a status update. The CLI refuses to ship a brief whose "What's not done — next steps" block is empty. If there's nothing outstanding, you're not handing off — you're celebrating. Use pm-report for that. There is no --force to override this; either fill the block or ship through a different skill.
Two modes
| Mode | When to use | Default detection |
|---|
person | "Hand this off to Alex", "I'm OOO Friday", "passing this to " | Trigger phrase names a teammate |
stage | "Ready for release", "ready for QA", "deploy handoff" | Trigger phrase names a lifecycle stage |
Auto-detected from the prompt. Override with --mode person|stage. For stage mode, the first-class transition is --from pr --to release. Other transitions use the generic template (stage-generic.md).
Project configuration
The skill reads two fields from <repo>/.claude/pm/project.json:
handoff_channels — array of destinations. Each entry has type (linear / github / markdown / chat) plus per-type config. At least one channel required.handoff_templates — optional map of <mode> or <mode>:<from>-><to> keys to template names. Falls back to bundled defaults.
Get the resolved config:
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" config --slug "<slug>"
Missing config → guided error pointing at /pm-setup. No silent defaults.
Workflow
Step 1: Capture state (scaffolding only)
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" capture \
--slug <slug> --mode person --to alex
Or for stage mode:
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" capture \
--slug <slug> --mode stage --from pr --to release --prs 247,251
What gets captured: issue metadata from pm-cache, current branch, commits since main divergence, files touched, PR list, heuristic checklist from the issue body. Not captured: "what I tried", "why I decided X", "what's tricky about this." That's your job in Step 2.
The CLI writes a draft JSON state object to a temp file and returns its path.
Step 2: Draft the brief
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" draft \
--slug <slug> --state-file <path-from-step-1>
The CLI resolves the template (three-scope: per-project → user → bundled), substitutes {{var}} placeholders against the state, and writes a brief to a temp file.
This is where you do the heavy lifting. Open the brief in an editor. Fill the four required blocks with prose that's actually useful to the recipient. The bundled templates have inline > **Operator action:** ... prompts marking each block — replace them.
For the narrative parts ("how to use it", "what's not done", decisions), re-read the session transcript and the relevant issue/PR comments. The CLI cannot extract those for you.
When you save, the brief is ready for send. If "What's not done" is empty, the next step will reject it with EMPTY_NOT_DONE.
Stuck-lens integration
When building "What's NOT done" entries, pm-handoff invokes report-lenses.stuck (hooks/lib/report-lenses.js) and annotates each issue with its stuck reasons (stale, no_update, blocked_label, unassigned_p1_p0, needs_info_self). The recipient sees not just what's open but why it's drifting.
Step 3: Send
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" send \
--slug <slug> --brief <path-from-step-2>
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" send \
--slug <slug> --brief <path-from-step-2> --yes
The send verb fans out to every configured channel. Each reports independently — if Linear succeeds and the GitHub reviewer-request fails, the result shows per-channel status (sent, partial, failed, already_sent).
Use --only <channel-type> to scope to one channel (e.g., --only markdown to write the file without posting to Linear).
Idempotency: every brief has a content hash. Re-running send on the same brief is a no-op (markdown file already exists with matching hash, Linear comment already posted, etc.). Use --force to override.
Step 4 (chat channel only): Hand off to resend-cli
The chat channel doesn't deliver email itself — it returns a payload (subject, to, body) and points at the resend-cli skill via next_skill. The operator picks that up and invokes resend-cli to actually send.
Step 5: Audit later
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" list --slug <slug>
Lists past handoffs in docs/pm/handoffs/ sorted newest-first with date, recipient, and content hash. Useful when reviewing what's been sent over the last week.
Channels
Markdown
Writes the brief to <channel.path>/<YYYY-MM-DD>-<slug>-to-<recipient>.md. The file is git add-ed; the operator commits it. The brief is version-controlled in the repo for the audit trail.
Linear
Posts the brief as a comment on the linked Linear issue (or appends to the issue body if linear comment create is unsupported in the installed CLI version — the probe runs lazily at send-time). Updates assignee + state per channel config (assignee_from: "recipient" + default_status: "In Review").
GitHub
Posts the brief as an issue/PR comment via gh issue comment. Optionally gh pr edit --add-reviewer <recipient> (when request_review: true) and gh pr ready (when ready_for_review: true).
Chat (resend-cli handoff)
Returns a payload. The operator invokes resend-cli separately to deliver. Project must have .resend.md configured.
Proactive invocation
Use this skill proactively when:
- pm-status reports stale issues (
stale_issues non-empty) — offer to write a handoff for one of them
- A PR merges and
handoff_channels includes a release-style destination — offer to write the release handoff
- A branch has been inactive 3+ days with no PR — offer to write a handoff for whoever's covering
Failure codes
| Code | Meaning | Operator action |
|---|
NO_HANDOFF_CONFIG | Project has no handoff_channels | /pm-setup to add |
NO_CONTEXT | Auto-capture found no branch/issue/PRs | Pass --issue or --prs explicitly |
MISSING_BLOCK | Brief is missing one of the four required blocks | Edit the brief, restore the block |
EMPTY_NOT_DONE | "What's not done" block is empty | Fill it, or use pm-report instead |
TEMPLATE_NOT_FOUND | Named template missing in all three scopes | Check handoff_templates or use a bundled name |
Per-channel failed / partial | A channel failed during send | Inspect error field; retry with --only <channel> and --force |
References
