call-handoff

Files (3)

• SKILL.md
• layouts.md · references/
• sibling-handshake.md · references/

SKILL.md (first lines)

# Call Handoff — token-efficient cold start

Goal: **one pass, ≤2 tool round-trips to the briefing** (script + ToolSearch, then
Step 3's first message, alongside any one follow-up Read; the other-session renames follow),
know what the project is, where the last session stopped, what is open, what must not
break — brief the user, fix session titles, then stop. This is the single session-start
ritual (the `session-start` skill is a stub that points here): orientation only, with
the code read later, once a task is chosen (last section).

## Budget

- Every round-trip re-reads the session's entire fixed context (tens of k tokens), so
  batching is the saving. Target: the one-shot script below + at most one
  follow-up Read (a >600-line handoff sliced, or one superseded handoff the newest one
  explicitly defers to) + the Step-3 pass (one message: self-rename + Remote Control on +
  `list_sessions`; then one batched rename message).
- **Load the Step-3 tools with the script, not after it.** The `ccd_session_mgmt` tools
  are deferred: send ONE `ToolSearch` (`select:mcp__ccd_session_mgmt__set_session_title,mcp__ccd_session_mgmt__list_sessions,mcp__ccd_session_mgmt__set_remote_control`)
  in the same message as the Step-1 Bash call, so loading costs no round-trip.
- **No dollar sign followed by a digit in this file**: the Skill tool replaces it with a
  word of the invocation's arguments, which breaks shell and awk code.
- **No codebase exploration.** No directory walks, no grep sweeps, no source files, no
  subagents. The handoff is the index; code gets read later, when a task is chosen.
- The project's `CLAUDE.md` and memory are already auto-loaded into context, so a
  re-read spends a round-trip on nothing. Skim what's in context instead.

## Step 1 — the one-shot script (single Bash call; Git Bash works on Windows)

Set `S` to the local clone of your skills repo if you keep one in git (leave it empty
to skip the sync block).

```bash
S="${SKILLS_REPO:-}"; echo "=== SKILLS SYNC (${S:-none configured})"
if [ -n "$S" ] && [ -d "$S/.git" ]; then D=$(git -C "$S" status --porcelain=v1 | head -3); if [ -n "$D" ]; then echo "DIRTY skills clone - not pulling:"; echo "$D"; else B=$(git -C "$S" rev-parse HEAD); git -C "$S" pull --ff-only 2>&1 | tail -1; git -C "$S" diff --name-only "$B" HEAD | grep -qE '^(skills|agents|hooks)/' && echo "SKILLS CHANGED -> re-install needed"; fi; git -C "$S" log -1 --format='skills @ %h %ad %s' --date=short; git -C "$S" status -sb | head -1
elif [ -n "$S" ]; then echo "NO CLONE at $S - clone your skills repo there first"; fi
echo "=== ENTRY POINT?"; SP=; [ -n "$S" ] && SP=$(cd "$S" 2>/dev/null && pwd -P); SP="${SP:-/nonexistent-skills-clone}"; MV=$(find . -maxdepth 1 -name '_MOVED-TO-*.txt' 2>/dev/null | head -1); FZ=; T=; [ -n "$MV" ] && { echo "FROZEN COPY ($MV): never write here"; [ -n "$S" ] && [ -d "$S/.git" ] && [ "$(basename "$PWD")" = "$(basename "$S")" ] && [ "$(pwd -P)" != "$SP" ] && FZ=1; }
if [ -n "$FZ" ]; then echo "-> real clone $S (cd there)"; cd "$S"; elif [ -n "$MV" ] || { [ -z "$(find _claude _claude/handoffs . docs handoffs -maxdepth 1 -name 'HANDOFF-*.md' 2>/dev/null | head -1)" ] && [ ! -d .git ] && ! grep -q '^## Topic table' CLAUDE.md 2>/dev/null; }; then for P in "$MV" _claude/WHERE-IS-THE-CODE.md WHERE-IS-THE-CODE.md CLAUDE.md; do [ -f "$P" ] || continue; T=$(grep -oE '(^|[[:space:]`"(])(%USERPROFILE%[\/]|[A-Za-z]:[\/]|~/)[^`"<>|*?]+' "$P" | sed -E -e 's/^[[:space:]`"(]+//' -e 's/[[:space:]]+\(.*//' -e 's/[).,;:[:space:]]+$//' -e p -e 's/[[:space:]].*//' | tr '\134' '/' | sed -e "s|^%USERPROFILE%|$HOME|" -e "s|^~|$HOME|" | while read -r c; do case "$c" in [A-Za-z]:/*) c="/$(printf %s "${c%%:*}" | tr 'A-Z' 'a-z')${c#?:}";; esac; [ -d "$c" ] || continue; c=$(cd "$c" && pwd -P); case "$c" in "$SP"|"$SP"/*|"$HOME/.claude"|"$HOME/.claude"/*) continue;; esac; echo "$c"; break; done); [ -n "$T" ] && { echo "pointer $P -> $T (cd there; this folder is the entry point only)"; cd "$T" || true; break; }; done; [ -n "$MV" ] && [ -z "$T" ] && echo "FROZEN COPY: no live target found - write nothing here"; fi; pwd
echo "=== PROJECT SYNC"; if [ "$(pwd -P)" = "$SP" ]; then echo "this is the skills clone (synced above)"; elif git remote get-url origin >/dev/null 2>&1; then if [ -z "$(git status --porcelain=v1 -uno)" ]; then git pull --ff-only 2>&1 | tail -1; else echo "dirty tree - not pulling"; fi; git status -sb | head -1; else echo "no remote"; fi
C=_claude; if [ ! -d _claude ]; then C=.; [ -n "$(ls -d HANDOFF-*.md NEXT-SESSION-PROMPT.md BUG_LIST.md WHERE-IS-THE-CODE.md handoffs 2>/dev/null)" ] && echo "LEGACY LAYOUT: continuity files at project root -> update-handoff moves them into _claude/"; fi
if grep -q '^## Topic table' CLAUDE.md 2>/dev/null; then echo "=== LAYERED HANDOFFS (router = CLAUDE.md topic table, already in context - read ONE topic file)"; find "$C/handoffs" -maxdepth 1 -name '*.md' 2>/dev/null | sort | while read -r f; do echo "$f · $(grep -m1 -i '^Last updated' "$f")"; done
else
HL=$( { find _claude . docs -maxdepth 1 -name 'HANDOFF-*.md'; find _claude/handoffs handoffs -maxdepth 2 -name 'HANDOFF-*.md'; } 2>/dev/null | while read -r f; do k=$(printf %s "${f##*/}" | sed -nE 's/^HANDOFF-([0-9]{4}-[0-9]{2}-[0-9]{2})(-([0-9]{4}))?.*/\1-\3/p'); case "$k" in *-) k="${k}0000";; '') m=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f"); k="0000-$(date -d "@$m" +%F-%H%M 2>/dev/null || date -r "$m" +%F-%H%M)";; esac; printf '%s|%s|%s\n' "$k" "${f##*/}" "$f"; done | sort)
H=$(printf '%s\n' "$HL" | tail -1 | cut -d'|' -f3); HP=; [ -n "$H" ] && HP=" · prior: $(printf '%s\n' "$HL" | tail -3 | sed '$d' | cut -d'|' -f3 | tr '\n' ' ')"
echo "=== NEWEST HANDOFF: ${H:-NONE}$HP"
if [ -n "$H" ]; then sed -n '1,600p' "$H"; elif [ -f README.md ]; then echo "=== README (no handoff)"; sed -n '1,60p' README.md; fi; fi
echo "=== RECENCY"; git log --oneline -5 2>/dev/null; git status --porcelain=v1 -uno 2>/dev/null | head -10; ls -t | head -8
B="$C/BUG_LIST.md"; [ -f "$B" ] || B=BUG_LIST.md; echo "=== OPEN BUGS ($B)"; [ -f "$B" ] && grep -n "^## \|Status:" "$B" | head -40 || echo "no BUG_LIST.md"
N="$C/NEXT-SESSION-PROMPT.md"; [ -f "$N" ] || N=NEXT-SESSION-PROMPT.md; echo "=== NEXT SESSION PROMPT ($N)"; [ -f "$N" ] && cat "$N" || echo "none"
```

Optional final line, if you use the `usage-here` skill — it records a usage baseline
for the session so a later report can isolate this session's burn:

```bash
echo "=== USAGE BASELINE"; "$(command -v python3 || command -v python)" "$HOME/.claude/skills/usage-here/usage_report.py" --snapshot
```

## Step 2 — reconcile and (rarely) follow up

- **Sync lines first.** `SKILLS CHANGED` ⇒ the installed copies under `~/.claude/skills`
  are stale: re-run your install step from the clone in one Bash call of its own and
  report its last lines. `DIRTY skills clone` or `ahead` in the status line ⇒ a previous
  session on THIS machine left work uncommitted/unpushed: say so in the briefing (it is
  invisible to other machines) and offer `update-handoff` to finish it. `NO CLONE` ⇒
  tell the user to clone the repo and stop. A pull that fails (offline, diverged) is
  reported, never retried with force.

- **`_claude/NEXT-SESSION-PROMPT.md`** (written by `update-handoff`) is the fastest
  orientation: if its date matches or post-dates the newest handoff, build the
  briefing around it. If it's OLDER than the handoff or the latest commits, it's
  stale — say so and trust the handoff instead (on any conflict the handoff wins).
- Commits or mtimes post-dating the handoff's date ⇒ handoff is **STALE** — say so in
  the briefing and treat git/files as truth.
- Bug entries: read in full only open/reopened ones (one targeted Read if the grep
  headers aren't enough). A ✅ entry matching a fresh symptom ⇒ suspect regression.
- Script printed `pointer …` or `LAYERED HANDOFFS`? Read this skill's
  `references/layouts.md` before the briefing (one extra Read that only these two
  layouts pay).
- **`LEGACY LAYOUT` printed?** The assistant's continuity files (handoffs, prompt, bug
  ledger, pointer) still sit at the project root; they belong in `_claude/` (layout:
  `update-handoff` → "The `_claude/` folder"). Say so in one briefing line; the next
  `update-handoff` moves them. Don't move them during orientation.
- **Flat handoff juggling several independent issues** (≥2 unrelated threads — different
  devices, vendors, customer contacts, or source folders — each with its own TODO)?
  Mention once in the briefing that `update-handoff` can split it into layered topic files.
- **`FROZEN COPY` printed?** This folder is a frozen copy (it has a `_MOVED-TO-*.txt`
  marker). Brief from the folder the script moved to; if it printed `no live target
  found`, say so and write nothing here, not even a handoff.
- **No handoff at all?** The script already printed README's head (if there is one) and
  the git log: orient from those, say plainly there is no handoff, note one must be
  created before session end (`update-handoff` skill).

## Output — the briefing (≤200 words; written once Step 3's first message has returned, so the title and Remote Control lines are real; then the other renames, then STOP)

- **Project:** 1–2 sentences. · **Last session (date, source file):** what landed.
- **Freshness:** current, or stale vs. git (evidence).
- **Open now:** unfinished work, open bugs, NOT-verified items.
- **Highest-value next item.** · **Dead paths / must-not-break** (constraints, not
  suggestions). · **Session title:** `<topic> · <YYYY-MM-DD>` · **Remote Control:**
  the state the Step-3 call returned. · **Fable guardrails** (Fable/Mythos sessions
  only): `on (hook)` or `on (read)`.
- **Ready — what do you want to work on?**

## Step 3 — Remote Control on + session-title hygiene (desktop app only; skip in the plain CLI)

*Requires the desktop app's `ccd_session_mgmt` MCP tools. If they aren't available,
skip this whole step silently.*

Order: script result → ONE message with the self-rename, Remote Control on and
`list_sessions` (plus any Step-2 follow-up Read) → the briefing → ONE batched message
renaming the other sessions.

**Remote Control on.** Invoking this skill is the user's standing request to reach the
session from claude.ai/code and the phone: call
`mcp__ccd_session_mgmt__set_remote_control` `{"session_id": "self", "enabled": true}`
(the app may ask them to approve). Report the returned state in the briefing (`on`,
`connecting`); a refusal (phone-started sessions have it on and locked), `unavailable`, or
a declined/auto-mode-denied approval → one line saying which, never a retry. THIS
session only; `update-handoff` Step 6 switches it off.

From mhshaon98/agent-skills, MIT.

More from mhshaon98/agent-skills