菜单
Guidance for coordinating work across Pi terminals using pi-link. Use when delegating tasks, choosing between link_prompt and link_send, planning async vs sync work, batching parallel jobs, managing a remote terminal's context with link_compact, or avoiding busy/conflict patterns.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | pi-link-coordination |
| description | Guidance for coordinating work across Pi terminals using pi-link. Use when delegating tasks, choosing between link_prompt and link_send, planning async vs sync work, batching parallel jobs, managing a remote terminal's context with link_compact, or avoiding busy/conflict patterns. |
How to coordinate work across Pi terminals via pi-link.
Each terminal is an independent agent: they share no memory or conversation history — link only passes messages and prompts between them. Anything a remote terminal needs — file paths, task state, expected output, where to send its callback — must be in the message itself.
link_promptlink_send(triggerTurn: true)link_send(triggerTurn: false)link_compactAfter
link_send(triggerTurn: true)to terminal X, do notlink_promptX until X sends a completion callback.
The DONE / BLOCKED callback arrives as a normal later user message; treat that callback as the signal that it is safe to send a follow-up link_prompt.
Pick one mode per terminal per task. Mixing sync and async on the same terminal is a common coordination failure.
link_listReturns connected terminals with names, live status (idle, thinking, tool:<name>), and working directory (cwd). Some terminals also report context usage as 45K/272K (17%) — how full that window is: high usage means less room remaining, though a loaded terminal may also be the one already holding the relevant task state. Your own entry is marked (you) — use this to discover your link name when replying to broadcast tasks.
Only currently connected terminals are visible. If a target is missing, it is offline; messages to offline terminals are not queued.
link_promptSynchronous RPC. Send a prompt, wait for the response.
link_sendFire-and-forget. Send to one terminal or to: "*" to broadcast to every other connected terminal; there is no exclusion filter. Sending to yourself is rejected. A send to a name that isn't connected fails with an error listing who is connected — delivery failure is visible to the sender, not silent.
Set triggerTurn: true to queue async work on the receiver. The sender does not get an automatic response back.
Delivery shape depends on the message's triggerTurn:
triggerTurn: true messages go through the receiver's idle-gated inbox and surface at a turn boundary wrapped as [Link: N message(s) received] followed by one From "name": block per message. Multiple pending messages are batched into one turn.triggerTurn: false messages bypass the inbox and surface directly as raw content — no wrapper, no From block. The receiver sees only the message text, so the sender must include their own identity, task tag, or artifact paths in the body.Callback convention for triggerTurn: true: the sender gets no automatic response, so ask the receiver to report back via link_send(..., triggerTurn: true) (which lands at a proper turn boundary with the wrapper intact). A useful convention:
DONE / BLOCKEDUse triggerTurn: false for fire-and-forget status notifications only — when you don't need to act on the reply.
Receiver rule: If your turn opens with [Link: N message(s) received], treat each From "name": block as assigned work. When done, send the sender a DONE / BLOCKED callback via link_send(..., triggerTurn: true) — unless the task says otherwise.
link_compactBlocks until the target finishes compacting, then returns (3 min ceiling — the call then errors for you, though the target may still finish compacting on its own; check it before assuming failure). Ask another terminal to compact its context window into a summary, freeing space. link_list exposes context usage; link_compact is the lever when you decide a terminal should free context — and because the call only returns once compaction is done, you can immediately hand it more work with link_send/link_prompt (no sleep, no busy-bounce). Busy targets (mid-turn or already compacting) decline; retry when link_list shows them idle. You decide the threshold; pi-link just runs the compaction you ask for. Its optional instructions add an extra focus to that summary.
role@domain, e.g. builder@pi-link); the hub keeps them unique, suffixing collisions (builder@pi-link-2). Use link_list to confirm a target's exact name, and its cwd to tell similar-named terminals apart.link_send(triggerTurn: true) can dispatch independent tasks to several terminals at once. Their callbacks may arrive separately or batched into one turn when you next become idle — track which workers are still outstanding. Each task must be self-contained (explicit paths, absolute if cwds differ). Don't link_prompt a dispatched terminal until its callback arrives (Golden Rule).
❌ Mixing async and sync on the same terminal
Dispatched with link_send(triggerTurn: true) then sent a link_prompt → rejected as busy. See Golden Rule.
❌ No completion callback on async work
triggerTurn: true returns no result to the sender — without an agreed callback you never learn the outcome.
❌ Circular delegation
A → B → C → A won't complete — the cycle-closing link_prompt hits a busy target (rejected), and an async link_send cycle just loops. Keep delegation acyclic.
| I need to... | Tool | Mode |
|---|---|---|
| See who's available | link_list | — |
| Get an answer from another agent | link_prompt | Synchronous |
| Delegate autonomous work | link_send(triggerTurn: true) | Asynchronous |
| Notify without activating | link_send(triggerTurn: false) | Fire-and-forget |
| Broadcast to all | link_send(to: "*") | Broadcast |
| Free a loaded worker's context | link_compact | Await-completion |