Handoff Prompt Generator
Generate the smallest prompt another agent can execute without guessing.
When to Use
- Delegate one bounded task to an agent that shares the current workspace.
- Continue work in a fresh session, after
/clear, or on another platform.
- Transfer work between model families and apply the receiver's preferred
prompt structure.
- Prepare a one-shot worker directive when another orchestrator owns routing,
supervision, lifecycle, and integration.
- Produce separate optimized prompts for multiple target models.
When NOT to Use
- Save a session identifier for later resumption; use
save-session.
- Decompose and execute subtasks from this session; use
orchestrate.
- Supervise live tmux agents continuously; use
tmux-pm. This skill may tune
a worker directive, but does not own routing, panes, merges, or DONE messages.
- Continue in the same conversation when no context boundary exists.
Choose the Handoff Mode
- Shared workspace: receiver can inspect the same repo, files, branches,
worktrees, logs, and artifacts. Prefer paths over pasted content.
- Fresh context: receiver starts cold or after a reset. Include enough
verified state to reconstruct the work without the prior transcript.
Preserve Target Identity and Authority
Resolve the receiver in this order:
- Exact model, account, harness, and effort supplied by the user or caller.
- Exact current model/harness when building a same-session-family restart and
that identity is known.
- Model family supplied by the user or caller.
- Vendor-neutral prompt when neither model nor family is known.
Never silently change a caller-supplied model, account, effort, permission
mode, or security lane. Model references tune prompt shape; they do not reroute
runtime settings. Put unresolved identity in a placeholder instead of guessing.
Read One Vendor Reference
Read only the reference matching the receiving family:
| Family |
Reference |
| Anthropic Claude |
references/anthropic.md |
| OpenAI GPT / Codex |
references/openai.md |
| Google Gemini |
references/google.md |
| xAI Grok / Grok Build |
references/xai.md |
Freshness rule
Verify official vendor documentation before drafting when any condition holds:
- the user asks for the latest, current, newest, best, or recommended model;
- the target version is absent from the matching reference;
- the reference snapshot is more than 30 days old;
- a sibling skill or caller supplies a newer explicit route;
- model availability, IDs, effort levels, or prompting behavior conflict.
Use primary vendor sources. Update the reference snapshot only after verifying
the facts. If live verification is unavailable, preserve the caller's route and
label any model-specific advice as potentially stale.
Gather Execution-Critical Context
Collect only facts that change the receiver's next action:
- objective and why the outcome matters;
- observable success criteria and completion bar;
- current verified state, baseline, blockers, and open questions;
- files, branches, worktrees, commands, URLs, logs, and artifacts;
- ownership boundaries and areas not to touch;
- authorization, side-effect, and stop boundaries;
- verification commands and expected results;
- output location, report schema, and coordination contract.
Do not paste large logs or history when the receiver can read the artifact.
Distinguish verified facts from assumptions and stale handoff claims.
Build the Base Handoff
Start with a minimal execution contract. Apply only the model-specific changes
from the selected reference; do not blend guidance from other families.
Shared-Workspace Handoff
Target: [exact model/account/harness/effort, or known family]
Handoff type: shared workspace
Objective
[One concrete outcome and why it matters]
Success criteria
- [Observable completion condition]
- [Verification condition]
Verified context
- [Current state and relevant facts]
Inputs
- [Paths, branch/worktree, logs, docs, prior outputs]
Ownership and constraints
- Modify: [owned paths]
- Do not touch: [excluded paths]
- Authorization/stop rules: [state-changing or scope boundaries]
Verification
- [Commands or evidence checks]
- [Expected baseline/result]
Output contract
- [Deliverable location or exact response shape]
- [How to report blockers, uncertainty, and incomplete checks]
Coordination
- [Relationship to parallel work and notification contract]
Fresh-Context Handoff
Target: [exact model/harness/effort when known; otherwise family]
Handoff type: fresh context
Project and objective
- Project: [name and one-sentence purpose]
- Outcome: [single concrete outcome and why it matters]
- Start by reading: [entry points]
Verified current state
- Repo/worktree/branch: [paths and refs]
- Completed: [verified work]
- Remaining: [work still required]
- Baseline/blockers: [known failures, risks, assumptions]
Task contract
- Success criteria: [observable completion bar]
- Scope: [owned paths or subsystem]
- Do not change: [explicit exclusions]
- Authorization/stop rules: [side-effect and scope boundaries]
Verification
- Already run: [commands and results]
- Run next: [commands and expected result]
Output contract
- [Deliverable shape and location]
- [How to report mismatches, blockers, TODOs, and uncertainty]
Use [TODO: exact path] rather than inventing repository facts.
Apply Model-Specific Tuning
After the base contract exists:
- preserve the selected model and runtime settings exactly;
- restructure to the vendor reference's Good shape when it differs;
- add only guidance that changes behavior for this task and target model;
- keep API-only controls outside plain chat prompts unless the handoff is for
an API harness configuration;
- preserve the orchestrator's transport envelope. For example, a tmux worker's
worktree setup, commit policy, PM target, and exact DONE line remain intact.
Do not assume every frontier model wants the same ordering. Gemini benefits
from task and critical restrictions at the end; Claude often benefits from XML
separation; GPT‑5.6 favors a lean outcome/evidence/completion contract; Grok
Build benefits from precise paths while loading durable project rules itself.
Hold the Quality Bar
- Keep a worker task atomic unless the chosen model was explicitly routed for
long-horizon orchestration.
- Define what done means and what evidence supports it.
- Name files and commands whenever known.
- Preserve exact values, scope words, account boundaries, and stop rules.
- Ask for findings first on review tasks.
- Define source boundaries, freshness, and citations for research.
- Require the receiver to report failed or skipped verification honestly.
- Do not ask for private chain-of-thought; request conclusions, evidence,
assumptions, checks, and concise reasoning summaries instead.
Return Format
When asked for a handoff prompt:
- Return the ready-to-send prompt in one fenced block.
- List unresolved assumptions or placeholders after the block.
- Return separate prompts when multiple target models need different tuning.
1---
2name: handoff
3description: >-
4 Generate execution-ready, model-specific prompts for handing work to a
5 different LLM agent or fresh session. Use for shared-workspace delegation,
6 cold-start continuation, cross-model transfer, one-shot worker directives,
7 or requests such as "create a handoff prompt", "delegate this", "hand this
8 off", and "prepare context for another agent". Supports current Anthropic
9 Claude, OpenAI GPT/Codex, Google Gemini, and xAI Grok families.
10version: 2.0.0
11metadata:
12 source: https://skillmd.com/skills/blacktop/handoff
13---
14
15# Handoff Prompt Generator
16
17Generate the smallest prompt another agent can execute without guessing.
18
19## When to Use
20
21- Delegate one bounded task to an agent that shares the current workspace.
22- Continue work in a fresh session, after `/clear`, or on another platform.
23- Transfer work between model families and apply the receiver's preferred
24 prompt structure.
25- Prepare a one-shot worker directive when another orchestrator owns routing,
26 supervision, lifecycle, and integration.
27- Produce separate optimized prompts for multiple target models.
28
29## When NOT to Use
30
31- Save a session identifier for later resumption; use `save-session`.
32- Decompose and execute subtasks from this session; use `orchestrate`.
33- Supervise live tmux agents continuously; use `tmux-pm`. This skill may tune
34 a worker directive, but does not own routing, panes, merges, or DONE messages.
35- Continue in the same conversation when no context boundary exists.
36
37## Choose the Handoff Mode
38
39- **Shared workspace:** receiver can inspect the same repo, files, branches,
40 worktrees, logs, and artifacts. Prefer paths over pasted content.
41- **Fresh context:** receiver starts cold or after a reset. Include enough
42 verified state to reconstruct the work without the prior transcript.
43
44## Preserve Target Identity and Authority
45
46Resolve the receiver in this order:
47
481. Exact model, account, harness, and effort supplied by the user or caller.
492. Exact current model/harness when building a same-session-family restart and
50 that identity is known.
513. Model family supplied by the user or caller.
524. Vendor-neutral prompt when neither model nor family is known.
53
54Never silently change a caller-supplied model, account, effort, permission
55mode, or security lane. Model references tune prompt shape; they do not reroute
56runtime settings. Put unresolved identity in a placeholder instead of guessing.
57
58## Read One Vendor Reference
59
60Read only the reference matching the receiving family:
61
62| Family | Reference |
63| --- | --- |
64| Anthropic Claude | [references/anthropic.md](references/anthropic.md) |
65| OpenAI GPT / Codex | [references/openai.md](references/openai.md) |
66| Google Gemini | [references/google.md](references/google.md) |
67| xAI Grok / Grok Build | [references/xai.md](references/xai.md) |
68
69### Freshness rule
70
71Verify official vendor documentation before drafting when any condition holds:
72
73- the user asks for the latest, current, newest, best, or recommended model;
74- the target version is absent from the matching reference;
75- the reference snapshot is more than 30 days old;
76- a sibling skill or caller supplies a newer explicit route;
77- model availability, IDs, effort levels, or prompting behavior conflict.
78
79Use primary vendor sources. Update the reference snapshot only after verifying
80the facts. If live verification is unavailable, preserve the caller's route and
81label any model-specific advice as potentially stale.
82
83## Gather Execution-Critical Context
84
85Collect only facts that change the receiver's next action:
86
87- objective and why the outcome matters;
88- observable success criteria and completion bar;
89- current verified state, baseline, blockers, and open questions;
90- files, branches, worktrees, commands, URLs, logs, and artifacts;
91- ownership boundaries and areas not to touch;
92- authorization, side-effect, and stop boundaries;
93- verification commands and expected results;
94- output location, report schema, and coordination contract.
95
96Do not paste large logs or history when the receiver can read the artifact.
97Distinguish verified facts from assumptions and stale handoff claims.
98
99## Build the Base Handoff
100
101Start with a minimal execution contract. Apply only the model-specific changes
102from the selected reference; do not blend guidance from other families.
103
104### Shared-Workspace Handoff
105
106```text
107Target: [exact model/account/harness/effort, or known family]
108Handoff type: shared workspace
109
110Objective
111[One concrete outcome and why it matters]
112
113Success criteria
114- [Observable completion condition]
115- [Verification condition]
116
117Verified context
118- [Current state and relevant facts]
119
120Inputs
121- [Paths, branch/worktree, logs, docs, prior outputs]
122
123Ownership and constraints
124- Modify: [owned paths]
125- Do not touch: [excluded paths]
126- Authorization/stop rules: [state-changing or scope boundaries]
127
128Verification
129- [Commands or evidence checks]
130- [Expected baseline/result]
131
132Output contract
133- [Deliverable location or exact response shape]
134- [How to report blockers, uncertainty, and incomplete checks]
135
136Coordination
137- [Relationship to parallel work and notification contract]
138```
139
140### Fresh-Context Handoff
141
142```text
143Target: [exact model/harness/effort when known; otherwise family]
144Handoff type: fresh context
145
146Project and objective
147- Project: [name and one-sentence purpose]
148- Outcome: [single concrete outcome and why it matters]
149- Start by reading: [entry points]
150
151Verified current state
152- Repo/worktree/branch: [paths and refs]
153- Completed: [verified work]
154- Remaining: [work still required]
155- Baseline/blockers: [known failures, risks, assumptions]
156
157Task contract
158- Success criteria: [observable completion bar]
159- Scope: [owned paths or subsystem]
160- Do not change: [explicit exclusions]
161- Authorization/stop rules: [side-effect and scope boundaries]
162
163Verification
164- Already run: [commands and results]
165- Run next: [commands and expected result]
166
167Output contract
168- [Deliverable shape and location]
169- [How to report mismatches, blockers, TODOs, and uncertainty]
170```
171
172Use `[TODO: exact path]` rather than inventing repository facts.
173
174## Apply Model-Specific Tuning
175
176After the base contract exists:
177
178- preserve the selected model and runtime settings exactly;
179- restructure to the vendor reference's **Good shape** when it differs;
180- add only guidance that changes behavior for this task and target model;
181- keep API-only controls outside plain chat prompts unless the handoff is for
182 an API harness configuration;
183- preserve the orchestrator's transport envelope. For example, a tmux worker's
184 worktree setup, commit policy, PM target, and exact DONE line remain intact.
185
186Do not assume every frontier model wants the same ordering. Gemini benefits
187from task and critical restrictions at the end; Claude often benefits from XML
188separation; GPT‑5.6 favors a lean outcome/evidence/completion contract; Grok
189Build benefits from precise paths while loading durable project rules itself.
190
191## Hold the Quality Bar
192
193- Keep a worker task atomic unless the chosen model was explicitly routed for
194 long-horizon orchestration.
195- Define what done means and what evidence supports it.
196- Name files and commands whenever known.
197- Preserve exact values, scope words, account boundaries, and stop rules.
198- Ask for findings first on review tasks.
199- Define source boundaries, freshness, and citations for research.
200- Require the receiver to report failed or skipped verification honestly.
201- Do not ask for private chain-of-thought; request conclusions, evidence,
202 assumptions, checks, and concise reasoning summaries instead.
203
204## Return Format
205
206When asked for a handoff prompt:
207
2081. Return the ready-to-send prompt in one fenced block.
2092. List unresolved assumptions or placeholders after the block.
2103. Return separate prompts when multiple target models need different tuning.