collaboration

What problem does it solve?

This Skill helps coordinate agent collaboration patterns and session handoffs to manage multi-agent workflows more predictably.

Core Features & Use Cases

1. Subagent (Agent tool, same session)

• Agent spawns a child agent within its own session
• Child runs in foreground (blocking) or background (non-blocking)
• Child returns results to parent — child cannot message Jörn or other subagents
• Child has its own context window but shares the session's worktree unless isolation: worktree
• Parent summarizes child's results into its own context Use when: Task is self-contained, benefits from isolated context (large output, focused checklist), and results are needed in this session. Cost model: Subagent tokens are cheap. Spawn liberally, especially in parallel.

2. Agent team (TeamCreate, same session)

• Agent promotes to team lead, spawns teammates as separate Claude Code instances
• Teammates work asynchronously in parallel, communicate via direct messaging
• Jörn communicates with the team lead; teammates are invisible to Jörn
• Shared task list for coordination; teammates self-assign work
• Each teammate has its own context window and tmux pane Use when: Multiple agents need to coordinate on related work within one session — e.g., parallel reviews where reviewers benefit from communicating findings, or parallel implementation of coupled components. Cost model: Token-heavy (N separate context windows). Best for 2-4 teammates.

3. Deferred session (handoff file, separate session)

• Current agent writes a handoff file describing a scoped task
• Handoff file is committed to the repo
• Jörn opens a new session later and points it at the handoff file
• New session starts cold — no shared context beyond the repo state and the handoff file Use when: Work is independent of the current session's outcome, or the current session is done and remaining work should continue later. Typical: implement tube algorithm step 3 prepared by a planning session, "clean up experiment X" identified during a review session. Cost model: Zero immediate cost. The handoff file is the only coordination artifact.

4. Parallel sessions (multiple terminals, Jörn orchestrates)

• Jörn runs multiple Claude Code sessions simultaneously in separate terminals
• Each session works on its own branch/worktree
• No built-in inter-session communication — Jörn coordinates manually
• Sessions can be on the same repo via worktrees or different repos Use when: Jörn wants to parallelize across independent work streams that he orchestrates directly. Each session gets its own scope phase with Jörn.

Choosing a pattern

• Need results in this session? Yes, if task is self-contained, choose subagent.
• Need coordination between multiple agents? Yes, choose agent team.
• No, use a deferred session (one handoff file per stream).
• For multiple independent work streams and direct orchestration, use parallel sessions.

Writing Handoff Files

• A handoff file is the sole context bridge between sessions. The receiving agent starts cold — it has CLAUDE.md and the repo, but no memory of the current session. The handoff file must make the receiving agent productive immediately.

Where to put handoff files

• handoffs/name.md in the repo root
• Committed to the branch so the receiving session can read them
• Jörn tells the new session: read and execute handoffs/name.md

Structure

• Task: <imperative verb phrase>

Context

• Why this task exists. 2-4 sentences max. Link to the goal it serves.

Scope

• What to do — concrete, numbered steps if possible.

Out of scope

• What NOT to do. Prevents drift. Name specific temptations.

Key files

• Absolute paths to files the agent must read. Not summaries — pointers.

Prior findings

• Facts discovered in the current session that the receiving agent would otherwise need to re-derive. Only include findings that are NOT in the repo (i.e., not in code comments, commit messages, or docs). If a finding is already in the repo, point to it instead of repeating it.

Success criteria

• How the agent knows it's done. Concrete and verifiable.

Dependencies

• What this task needs from other sessions, if anything.
• E.g., "blocked on KKT refactor session merging first".
• Also: what other tasks depend on THIS task's output.