From 8fa2729bbc0e04326500145b599976b2f27e5372 Mon Sep 17 00:00:00 2001
From: beads/crew/grip <steve.yegge@gmail.com>
Date: Fri, 2 Jan 2026 16:03:55 -0800
Subject: [PATCH] feat: add /handoff skill for session cycling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Code v2.0+ moved from .claude/commands/ to .claude/skills/.
This adds the handoff skill in the new format so workers can use
/handoff to cycle to fresh sessions.

The skill wraps `gt handoff` with optional message support.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/skills/handoff/SKILL.md | 71 +++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 .claude/skills/handoff/SKILL.md

diff --git a/.claude/skills/handoff/SKILL.md b/.claude/skills/handoff/SKILL.md
new file mode 100644
index 00000000..e7552e4b
--- /dev/null
+++ b/.claude/skills/handoff/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: handoff
+description: >
+  Hand off to a fresh Claude session. Use when context is full, you've finished
+  a logical chunk of work, or need a fresh perspective. Work continues from hook.
+allowed-tools: "Bash(gt handoff:*),Bash(gt mail send:*)"
+version: "1.0.0"
+author: "Gas Town"
+---
+
+# Handoff - Session Cycling for Gas Town Agents
+
+Hand off your current session to a fresh Claude instance while preserving work context.
+
+## When to Use
+
+- Context getting full (approaching token limit)
+- Finished a logical chunk of work
+- Need a fresh perspective on a problem
+- Human requests session cycling
+
+## Usage
+
+```
+/handoff [optional message]
+```
+
+## How It Works
+
+1. If you provide a message, it's sent as handoff mail to yourself
+2. `gt handoff` respawns your session with a fresh Claude
+3. New session auto-primes via SessionStart hook
+4. Work continues from your hook (pinned molecule persists)
+
+## Examples
+
+```bash
+# Simple handoff (molecule persists, fresh context)
+/handoff
+
+# Handoff with context notes
+/handoff "Found the bug in token refresh - check line 145 in auth.go first"
+```
+
+## What Persists
+
+- **Hooked molecule**: Your work assignment stays on your hook
+- **Beads state**: All issues, dependencies, progress
+- **Git state**: Commits, branches, staged changes
+
+## What Resets
+
+- **Conversation context**: Fresh Claude instance
+- **TodoWrite items**: Ephemeral, session-scoped
+- **In-memory state**: Any uncommitted analysis
+
+## Implementation
+
+When invoked, execute:
+
+1. If user provided a message, send handoff mail:
+   ```bash
+   gt mail send <your-address> -s "HANDOFF: Session cycling" -m "<message>"
+   ```
+
+2. Run the handoff command:
+   ```bash
+   gt handoff
+   ```
+
+The new session will find your handoff mail and hooked work automatically.