Skip to main content
skill CX Codex

relay — Claude Code skill: hand off context between sessions

relay builds a one-line /compact command and a handoff document with the next task so work survives a context reset.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sangrokjung/claude-forge --skill relay -a claude-code
Open on GitHub

What relay does

The skill triggers once context hits 70% usage or the user asks to hand off, relay, or continue after compact. It gathers git, plan and task state through relay-collect.sh, builds the /compact line with relay-build-focus.sh, and immediately writes a skeleton baton file via relay-write-baton.sh so something valid exists on disk even if context runs out before prose gets added. The skill itself never triggers /compact — it cannot execute platform slash commands, so it hands back the line inside a fenced code block for the user to paste in.

Clipboard copying stays off unless the user adds --copy, since overwriting the clipboard silently could wipe something the user already had there. An optional post-compact-restore.sh hook can reinject the next task and baton path into context right after /compact fires, once per compaction; if the hook misses, the baton path is still printed separately so it can be read manually.

A tests/relay.bats suite exists for local testing and depends on bats-core, but running the skill itself doesn't require it.

What it helps with

  • carry the next task across a context reset
  • generate a one-line /compact command
  • hand off work between sessions without losing details
  • pin down key decisions and files before context runs out
  • restore context automatically right after /compact

Example prompts for the agent

  • Hand off this session to the next one
  • Build a baton for continuing after /compact
  • Compact the context and draft the next task with --quick

How to install relay

1Skills CLI (Vercel)

npx skills add sangrokjung/claude-forge --skill relay -a claude-code

2Manually: put the files in place

~/.claude/skills/relay/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/relay/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about relay

How to install relay in Claude Code?

Run npx skills add sangrokjung/claude-forge --skill relay -a claude-code; the skill lands at ~/.claude/skills/relay/SKILL.md.

What does relay do?

It captures the current session's state, builds a /compact one-liner, and writes a baton document carrying the next task forward so work continues without losing context.

Does relay run /compact on its own?

No, the skill can't execute /compact directly — it only produces the ready-made line that the user pastes in themselves.

Source text

SKILL.md · MIT
---
name: relay
description: Session relay — compresses what's been done so far (writes a one-liner for /compact) and generates a "next task" prompt (a baton) for the user to hand off. Use on requests like "relay / hand off / next session / continue after compact / baton / handoff / clean up context and continue next task." Does not run /compact itself (a skill cannot do that) — it produces the one-liner the user pastes in.
allowed-tools: Bash(bash:*), Bash(git:*), Bash(date:*), Bash(hostname:*), Bash(uname:*), Read, Write, Glob, Grep, AskUserQuestion
disable-model-invocation: true
---

# relay — session relay (compact + next-task baton)

> Think of a relay race: the runner hands off the baton before stopping. Before context fills up, this
> skill produces two things: ① a one-line `/compact` command that compresses everything so far, and
> ② a handoff document (a "baton") that lets the next session start running immediately on the next task.

**When**: context is 70%+ used, work is about to be interrupted, or the user asks to "relay / hand off / next session / baton / handoff."

**Important (invariant)**: this skill **never runs `/compact` directly** (a skill cannot execute `/compact`).
It only produces **the one-liner the user pastes in**.

Let `$SKILL` be the absolute path of the directory containing this SKILL.md. Scripts live in `$SKILL/scripts/`.

## Flow

### 0) Parse arguments
From `$ARGUMENTS`:
- First positional argument = **next task (NEXT_TASK)**.
- Flags: `--new-session` (for a brand-new session — instructs the user to paste the whole baton), `--no-ask` (skip the clarifying question), `--quick` (skip prose, skeleton only), `--copy` (opt-in clipboard copy — off by default, see §6).

### 1) Collect state
Run `bash "$SKILL/scripts/relay-collect.sh"` → capture one JSON object. (facts about git/plan/session-summary/tasks/artifacts)
This JSON is the source of truth for every "fact." **Do not retype it from memory — quote it verbatim.**

### 2) Confirm the next task
If NEXT_TASK is empty and `--no-ask` was not passed, ask **one** AskUserQuestion:
"What's the first thing to do next?" — options pulled from `plan.next_unchecked` / `session_summary.next_steps`
/ `tasks.items` in the collect JSON, plus "type it myself." Tag the answer `[from-user]`.

### 3) Write the `/compact` one-liner
`bash "$SKILL/scripts/relay-build-focus.sh" "<NEXT_TASK>" "<files>" "<decision>"`
- `<files>` = key files relevant to the next task (space/comma separated, optional).
- `<decision>` = one line capturing a key decision to preserve (optional).

### 4) Write the skeleton baton immediately (guarantees an artifact even at 95% context)
`bash "$SKILL/scripts/relay-write-baton.sh" "<NEXT_TASK>" <path-to-collect.json or -> "<focus line>"`
- Save the collect JSON to a file and pass its path, or pipe it via stdin with `-`.
- This step leaves a valid (skeleton) baton on disk **even without prose**.

### 5) Add prose (optional — skip if `--quick`)
Follow `references/next-prompt-spec.md` to write §2 (context needed) and §4 (repro pitfalls), plus §1's body.
- Apply the **relevance filter** (KEEP / one-line / DROP) based on the next task.
- Facts come **verbatim** from the collect JSON; inferences get tagged `[from-claude]`.
- Save the prose to a temporary markdown file (use the `---§4---` marker to separate §2/§4), then re-run
  write-baton **with the prose file as the 4th argument** to splice it in.
- **Copy/prose text should read like a relaxed expert**, not a stiff, over-formal tone.

### 6) Output (three items — (c) must always be a code block)

(a) absolute path of the baton
(b) preview of the next prompt — excerpt from §1 MISSION
(c) the `/compact` one-liner, output **as a single fenced code block, verbatim**

**Never write (c) inline.** A long inline line wraps in the terminal and becomes hard to select and copy. A code block keeps it as one selectable unit.

- **Do not put it on the clipboard by default.** The clipboard is a single, volatile slot — if the user copies
  anything else in the meantime, the line is gone, and whatever was on the clipboard before gets silently
  overwritten without consent. On-screen text stays in scrollback and can be copied again anytime.
- If clipboard is actually needed, opt in explicitly with `--copy`, which sets `RELAY_COPY=1` on the write-baton
  call in step 4. Even then, still emit the (c) code block.
- With `--new-session`, instead of (c), tell the user to **paste the entire baton into the new session** (path from (a)).

## CRITICAL guards

- **Skeleton first, prose later**: if context runs out at step 4, a valid baton still remains.
- **MISSION-first**: oriented toward "what to do next," not a "log of what was done." §1 comes first.
- **Facts stay verbatim**: pulled directly from the collect JSON. Never retype from memory.
- **Never runs `/compact` directly** — the skill only produces the one-liner.
- **Always emit absolute paths** (no relative paths, no unexpanded `~`).
- **Can finish with just the skeleton** if context is running low.

## Opt-in auto-restore (SessionStart:compact)

`hooks/post-compact-restore.sh` is wired to settings.json's SessionStart (matcher `"compact"`). Right after
`/compact`, this hook injects the pointer (the carryover left by write-baton) into the session **exactly once
(consume-once)**.
- When auto-restore fires, the next task, carryover, and baton path reappear in context right after compaction.
- If the hook doesn't fire (no pointer / expired / already consumed), it **degrades gracefully** to the (a) baton
  path above — just Read that path.

## References

- Baton 7-section template + relevance filter + prose format: `references/next-prompt-spec.md` (SSOT)
- Scripts: `scripts/relay-lib.sh`, `relay-collect.sh`, `relay-build-focus.sh`, `relay-write-baton.sh`
- Auto-restore hook: `hooks/post-compact-restore.sh`

## Dev dependency (optional)

`tests/relay.bats` uses [bats-core](https://github.com/bats-core/bats-core). It is **not required** to use the
skill — only to run the test suite locally (`bats tests/relay.bats` from `skills/relay/`). If `bats` isn't
installed, the scripts still work standalone; just skip the test run.

© sangrokjung · MIT · sangrokjung/claude-forge

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set44

The whole set →
workflow-classify The workflow-classify command grades a task from S to XL and recommends a workflow. Run it before implementation to get a plan matched to the change’s scope and risk. CX Codex +1 ★ 880repo stars build-error-resolver build-error-resolver turns a failing build green with the smallest possible diff: type errors, compile failures, imports, dependencies. Refactoring and architecture work are ruled out. CX Codex ★ 880repo stars review-loop review-loop runs an adversarial verification loop where a fresh, isolated checker inspects behavioral changes until reaching a strict APPROVE verdict. CX Codex +1 ★ 880repo stars adversarial-review The adversarial-review rule requires an independent check for behavioural changes and defines three outcomes. It helps teams avoid treating a failed review as approval. CX Codex +1 ★ 880repo stars adversarial-reviewer The adversarial-reviewer subagent for Claude Code checks behavioural changes before a task is marked complete, reproducing issues and returning a verdict without modifying repository files. CX Codex ★ 880repo stars rca-debugger rca-debugger investigates complex failures when ordinary debugging has stalled, including flaky bugs and differences between CI and local runs. CX Codex ★ 880repo stars security-reviewer security-reviewer scans a diff for OWASP Top 10 flaws, hardcoded secrets and shaky dependencies, then ranks what it finds. You get a report with secure code samples. CX Codex ★ 880repo stars systematic-debugging The systematic-debugging skill guides an agent through finding an error’s cause before suggesting a fix. Use it for failed tests, builds, deployments, configuration conflicts, or repeated failed attempts. CX Codex +1 ★ 880repo stars

Project sponsors

Companies that keep this analytics open