Skip to content
Skills Library
AI & agents · Writing

document-handoff

/document-handoff

Creates comprehensive handoff documentation before a /compact operation, enabling a new agent with fresh context to seamlessly continue the work. Activate when the user says "prepare a handoff", "document before compact", "context is getting too large", "I need to hand this off", "create a handoff document", "end of session notes", or "document the current state for tomorrow". Supports --output and --linear-issue options.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Creates comprehensive handoff documentation before a /compact operation, enabling a new agent with fresh context to seamlessly continue the work. Activate when the user says "prepare a handoff", "document before compact", "context is getting too large", "I need to hand this off", "create a handoff document", "end of session notes", or "document the current state for tomorrow". Supports --output and --linear-issue options.

Triggers from the description

prepare a handoffdocument before compactcontext is getting too largeI need to hand this offcreate a handoff documentend of session notesdocument the current state for tomorrow
Original author description

Creates comprehensive handoff documentation before a /compact operation, enabling a new agent with fresh context to seamlessly continue the work. Activate when the user says "prepare a handoff", "document before compact", "context is getting too large", "I need to hand this off", "create a handoff document", "end of session notes", or "document the current state for tomorrow". Supports --output and --linear-issue options.

How it works

  1. When to Use
  2. Parameters
  3. Workflow
  4. Quality Standards
  5. Handoff + Compact Sequence
  6. Additional Resources
Original SKILL.md headings · 124 lines, 566 words
SKILL.md preview
---
name: document-handoff
description: >
  Creates comprehensive handoff documentation before a /compact operation,
  enabling a new agent with fresh context to seamlessly continue the work.
  Activate when the user says "prepare a handoff", "document before compact",
  "context is getting too large", "I need to hand this off", "create a handoff
  document", "end of session notes", or "document the current state for
  tomorrow". Supports --output and --linear-issue options.
---

# Document Handoff

Create a self-contained handoff document that gives a fresh agent everything it
needs to continue without any prior context.

## When to Use

**Use when:**
- Context window is approaching its limit and `/compact` is necessary
- Handing off to another developer or agent
- Interrupting a complex task mid-way
- Ending a working session and resuming the next day
- Multiple failed attempts have accumulated useful learning

**Skip when:**
- The task will finish in the next five minutes
- Only research was done — no implementation changes
- The task is trivial and the context is minimal

## Parameters

| Parameter | Default | Description |
|---|---|---|
| `[task-name]` | derived from git branch | Name for the handoff document |
| `--output <dir>` | `.claude/handoffs/` | Output directory |
| `--linear-issue <ID>` | — | Pull issue details from Linear (e.g. `TF-177`) |

## Workflow

### Step 1 — Gather information automatically

**Git status:**
```bash
git branch --show-current
git status --short
git log --oneline -5
git diff --stat HEAD
```

**TODO/FIXME in code:**
```bash
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.py" --include="*.ts" \
  --include="*.java" . 2>/dev/null | head -20
```

**Linear issue (if `--linear-issue` is specified):**
Use `mcp__linear__get_issue` to retrieve title, description, status, comments.

### Step 2 — Structure the document

| Section | Content |
|---|---|
| **Original Task** | What was the goal? What definition of done was agreed? |
| **Already Completed** | Concrete changes made — file paths, commit hashes, PR numbers |
| **Failed Attempts** | What was tried, what failed, and the exact reason why |
| **Current State** | Git branch, uncommitted files, environment specifics, running services |
| **Next Steps** | Prioritised list with specific file paths and line numbers where relevant |
| **Important References** | Key files, docs, code patterns, external resources |
| **For the Next Agent** | 2–3 sentence executive summary: pick this up and do X next |

### Step 3 — Save the document

**Output path:**
```
.claude/handoffs/YYYY-MM-DD_<task-slug>.md
```

Examples:
- `.claude/handoffs/2026-05-08_auth-refactor.md`
- `.claude/handoffs/2026-05-08_rbac-regression-fix.md`

Create the directory if it does not exist: `mkdir -p .claude/handoffs/`

### Step 4 — Output summary

After saving:
1. Display the full path to the handoff file
2. Highlight the **top 3 next steps** in order
3. Print the continuation instruction:

```
To continue after /compact:
  "Please read .claude/handoffs/YYYY-MM-DD_<task-slug>.md and continue with the next steps."
```

## Quality Standards

A good handoff document is:

**Self-explanatory** — the next agent needs no prior knowledge. Every relevant
file path includes a line number. No implicit assumptions.

**Actionable** — "Modify line 123 in `src/auth/service.py`" not "adjust the
auth code". Next steps are prioritised and have clear acceptance criteria.

**Complete** — both successful *and* failed attempts are documented. Error
messages are quoted verbatim, not paraphrased. Dependencies and external
factors that affect the task are noted.

**Safe** — no API keys, passwords, tokens, or credentials. If any were
encountered, note their *location* (environment variable name or file path),
not their values.

## Handoff + Compact Sequence

```bash
# 1. Create the handoff
/project-management:document-handoff "My Task Name"

# 2. Compact the context
/compact

# 3. In the new session, load and continue
# "Please read .claude/handoffs/2026-05-08_my-task-name.md
#  and continue with the next steps."
```

## Additional Resources

- **`../references/document-handoff/templates.md`** — Full and minimal handoff templates
- **`../references/document-handoff/examples.md`** — Annotated real-world examples
- **`../references/document-handoff/best-practices.md`** — Effective handoff patterns and common mistakes

Versions

The database has no other skills named document-handoff.

Database snapshot: 13.11.2026 · package version 5c20deaf9e94 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86handoff
    Write or update a HANDOFF.md so a fresh agent can continue this work. Use when the user says "handoff", "compact this", "context is full", or "/clear and continue".
  • 90handoff
    Write a handoff document so another agent or a fresh session can continue this work. Use for "handoff", "hand this off", "write a handoff", "continue this in a new session" or "pass this to another agent". For deciding whether to compact or clear, use session-budget.
  • 100handoff
    Compact the current session into a handoff document so another agent or fresh session can continue the work. Use when user asks to hand off, transfer context, continue in another session, start a parallel agent, or preserve only the next-useful context instead of using /compact.
  • 95handoff
    Compact the current conversation into a handoff document for another agent to pick up. Use when the user says handoff, is running out of context, or wants a fresh agent to pick the work up. Triggers on: handoff, hand this off, compact this conversation.
  • 100session-handoff
    Package current session context so another agent can continue without starting cold. Use when the user says "hand this off", "continue in a new session", "save session state", or context limit is approaching.
  • 90handoff
    Compact the current conversation into a handoff document for another agent to pick up. Use this skill whenever the user asks for a handoff, continuation note, session summary for another agent, compacted context, or a document that lets a fresh agent continue the work. Load with…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.