From 270be9b65c560879cfb4ea3079a3a1eabfd8859c Mon Sep 17 00:00:00 2001
From: rictus <steve.yegge@gmail.com>
Date: Fri, 2 Jan 2026 18:23:41 -0800
Subject: [PATCH] feat: Migrate handoff from commands to skills format
 (gt-nqtqp)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Code v2.0+ deprecated .claude/commands/ in favor of .claude/skills/.
This migrates the handoff skill to the new format with proper YAML frontmatter.

Changes:
- Create .claude/skills/handoff/SKILL.md with frontmatter
- Remove deprecated .claude/commands/handoff.md

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

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

diff --git a/.claude/commands/handoff.md b/.claude/commands/handoff.md
deleted file mode 100644
index 6f9e880c..00000000
--- a/.claude/commands/handoff.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: Hand off to fresh session, work continues from hook
-allowed-tools: Bash(gt mail send:*),Bash(gt handoff:*)
-argument-hint: [message]
----
-
-Hand off to a fresh session.
-
-User's handoff message (if any): $ARGUMENTS
-
-Execute these steps in order:
-
-1. If user provided a message, send handoff mail to yourself first.
-   Construct your mail address from your identity (e.g., gastown/crew/max for crew, mayor/ for mayor).
-   Example: `gt mail send gastown/crew/max -s "🤝 HANDOFF: Session cycling" -m "USER_MESSAGE_HERE"`
-
-2. Run the handoff command (this will respawn your session with a fresh Claude):
-   `gt handoff`
-
-Note: The new session will auto-prime via the SessionStart hook and find your handoff mail.
-End watch. A new session takes over, picking up any molecule on the hook.
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.