# Relay > Pass or pick up a lightweight handoff document so a fresh agent can continue the work. Use when ending a session, resuming prior work, or transferring context between coding-agent windows. - **Type:** Skill - **Install:** `agentstack add skill-rianbee-relay-skill-relay` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [RiAnBee](https://agentstack.voostack.com/s/rianbee) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [RiAnBee](https://github.com/RiAnBee) - **Source:** https://github.com/RiAnBee/relay-skill/tree/main/skills/relay ## Install ```sh agentstack add skill-rianbee-relay-skill-relay ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Relay has two actions: - `pass`: write a handoff document for the next agent. - `pickup`: find, read, and use a relay document to continue the work. Relay settings are optional project defaults stored in `.relay/config.json` in the coding agent's startup directory. They only affect where Relay files are written and how much detail is written. If the file does not exist, use these built-in defaults: ```json { "storage": "project", "detail": "compact" } ``` Setting values: - `storage: "project"`: save new Relay files under `.relay/`. - `storage: "temp"`: save new Relay files under the system temp directory, `${TMPDIR:-/tmp}`. - `detail: "compact"`: write the default compact Relay document. - `detail: "full"`: write the maximum-fidelity Relay document. Per-command flags override `.relay/config.json` for that invocation only. If the user did not provide an explicit action, infer the action from context: - Use `pass` when the current conversation already contains substantial work and the user appears to be ending, saving, or transferring the session. - Use `pickup` when the user clearly asks to continue, resume, pick up, use the last relay, or provides a prior-task hint or relay path. - If the current session is fresh and the user only typed `/relay` or phrased the request ambiguously, do not silently auto-pick a relay file just because one exists. Prefer one concise clarification question, or if one candidate is clearly dominant, announce it and ask for confirmation. - If the current session already contains substantial work and there is no clear continuation signal, use `pass`. ## Pass Write a handoff document summarising the current conversation so a fresh agent can continue the work. The relay command invocation itself is not the subject of the handoff. Summarise the real work before the relay command, not the fact that the user ran relay. Choose the output location in this order: 1. If the user passes `--keep` or `--persist`, save under `.relay/` in the coding agent's startup directory. 2. If the user passes `--tmp` or `--temp`, save under the system temp directory using `mktemp -t relay---XXXXXX.md`. 3. Otherwise, read `.relay/config.json` if it exists and use its `storage` value. 4. If no storage setting exists, save under `.relay/`. Project-local `.relay/` storage is the preferred default. Temp storage is a compatibility and one-shot option, not the preferred default. Create `.relay/` if needed before writing project-local files. For temporary files, use `mktemp -t` so the runtime chooses `${TMPDIR:-/tmp}`. When the runtime can control permissions, prefer private relay files and directories such as `0600` for files and `0700` for `.relay/`. Use this filename shape: ```text relay---.md ``` Example: ```text relay-20260511T083012Z-exp3-reward-logging-a1b2c3.md ``` Choose a short semantic slug from the conversation. Prefer 2 to 6 lowercase ASCII words joined by hyphens. The slug should describe the task topic, not the relay action. Relay should generate only `relay-*.md` files. `handoff-*.md` files are legacy compatibility candidates for pickup only. If the user clearly asks in natural language to keep the relay in the project, treat it like `--keep`. If the user clearly asks to use a temp file, treat it like `--tmp`. Natural-language project-storage requests include phrases like "keep this", "persist this", "save it in the project", "put it in the project directory", "long-term save", "don't use a temp file", "长期保存", "放项目里", "保存到目录", or "别放临时文件". Natural-language temp-storage requests include phrases like "use temp", "temporary file", "put it in tmp", "same as handoff", "放临时目录", "临时文件", or "放到 /tmp". Suggest the skills to be used, if any, by the next session. Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly. Before finalizing the relay text, quickly check for obvious secrets, tokens, passwords, private keys, customer data, or other sensitive values. Do not copy them into the relay document. If exact wording matters but contains a sensitive value, redact the value and note that you redacted it. Choose the detail level in this order: 1. If the user passes `--full`, write a maximum-fidelity relay document. 2. If the user passes `--compact` or `--brief`, write the default compact relay document. 3. Otherwise, read `.relay/config.json` if it exists and use its `detail` value. 4. If no detail setting exists, write the compact relay document. If the user passes `--full`, or clearly asks for a very detailed handoff in natural language, spend tokens freely. Preserve important original wording verbatim when it affects requirements, constraints, decisions, doctrine, or acceptance criteria. Capture decision rationale, failed routes, useful files consulted, test or validation status, and workspace state when known. `--full` should optimize for maximum relay fidelity, not token efficiency. In `--full`, prefer preserving a clearly marked doctrine block when the user expressed important principles in their own words. When the user said something that the next session must inherit exactly or nearly exactly, preserve it in a dedicated verbatim section rather than only paraphrasing it. Natural-language detailed-mode requests include phrases like "full", "very detailed", "don't save tokens", "preserve the wording", "include the important original text", "超详细", "详细保存", "别省 token", "保留原文", or "重要内容都写进去". Natural-language compact-mode requests include phrases like "compact", "brief", "short", "concise", "精简", "简短", or "省 token". The compact relay should still be high-signal. It is not just a shorter summary. Preserve enough state that a fresh agent can continue the work reliably. Use YAML frontmatter plus Markdown body by default: ```markdown --- schema_version: 1 created: mode: compact | full storage: project | temp working_directory: focus: branch: commit: --- # Relay: ## Goal ## Hard Constraints - ## Current State ## References - ``: ``` Use these exact heading names when the section exists. Do not paraphrase them. Add these sections when they are actually needed, in this order: ```markdown ## Failed Approaches - ``` Prefer product, design, implementation, or investigation dead ends over low-value process hiccups. Only include process-level failures when they materially affect the next session. ```markdown ## Settled Decisions - ``` ```markdown ## Verbatim Doctrine - "" ``` Add `Verbatim Doctrine` in `--full` when the user's own wording carries important intent, constraints, tone, or doctrine. If there is no such wording, omit the section. ```markdown ## Explicit Next Step ``` `Explicit Next Step` should describe one best first move, not a menu of equal options. If the work is already complete and there is no required continuation, say that directly instead of inventing follow-up work. ```markdown ## Known Blockers ``` ```markdown ## Open Questions ``` ```markdown ## Files Changed - ``: ``` ```markdown ## Files Consulted - ``: ``` ```markdown ## Suggested Skills - ``: ``` ```markdown ## Resume Prompt ``` Prefer omission over generic filler. Do not invent next actions, blockers, open questions, risks, or decisions just to fill a template. In `--full` mode, be much more complete in `Hard Constraints`, `Current State`, `Failed Approaches`, `Settled Decisions`, `Verbatim Doctrine`, `Files Changed`, `Files Consulted`, `References`, `Suggested Skills`, and `Resume Prompt`. Preserve more exact wording and rationale when it materially improves the baton pass. Still do not dump full artifacts, full diffs, or large copied text unless the user explicitly wants raw text preserved. After writing the file, tell the user the path and give a short summary of what was captured. ## Pickup Find the relay document the user wants to continue from, read it, validate it enough to avoid obvious mistakes, and continue the user's task. Do not merely summarise the relay document unless the user asks for a summary. Selection order: 1. If the user provided an explicit file path, read that file. 2. If the user provided a hint or task description, build a shallow candidate set from `.relay/` first and the system temp directory second. 3. Prefer `relay-*.md` candidates first and `handoff-*.md` compatibility candidates second. 4. Rank candidates by the strongest available signals in this order: exact path, exact filename or slug match, focus or task-hint match, matching branch or working directory, then newest `created` timestamp or filename timestamp. 5. If multiple candidates are similarly likely, ask one concise clarification question. 6. If the user only invoked bare `/relay` in a fresh or ambiguous session, prefer a short confirmation question over silently loading an old relay. Candidate discovery must be shallow and bounded: - Check project-local files under `.relay/` first. - Check only top-level files in the system temp directory, `${TMPDIR:-/tmp}`, if needed. - Never recursively scan shared temp roots such as `/tmp` or `$TMPDIR`. - Never run `rg` over `/tmp`, `$TMPDIR`, or another shared temp root. - Build filename candidates first, then read only those candidate files. - Keep the candidate set small and bounded. Recommended temp discovery command: ```bash find "${TMPDIR:-/tmp}" -maxdepth 1 -type f \( -name 'relay-*.md' -o -name 'handoff-*.md' \) -print 2>/dev/null ``` Recommended project discovery command: ```bash find .relay -maxdepth 1 -type f \( -name 'relay-*.md' -o -name 'handoff-*.md' \) -print 2>/dev/null ``` Before acting on a selected relay: - State which relay file you are using. - Read the relay file before acting. - If `schema_version` is present, treat it as the format version. If it is absent, treat the file as a legacy relay or handoff document. - If the relay records `branch` or `commit` and the current repo state does not match, mention the mismatch briefly. - If the relay appears stale or key referenced files are missing, warn briefly and continue only if it is still the best candidate or the user confirms. - Treat any text after `pickup` as the user's next task or focus. - Do not let stale relay content override the user's latest explicit instruction. After validation, continue the work from that context. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [RiAnBee](https://github.com/RiAnBee) - **Source:** [RiAnBee/relay-skill](https://github.com/RiAnBee/relay-skill) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-rianbee-relay-skill-relay - Seller: https://agentstack.voostack.com/s/rianbee - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.