🤝 handoff

Verify you actually understood the code Claude wrote — before you ship it.

handoff is a Claude Code skill that turns passive review of AI-written code into an active comprehension check. When a feature is complete, it interviews you with a short quiz — where the logic lives and why the decisions were made — then reports a score and the exact spots to re-read.

The name captures the idea: the handoff of the code from Claude to you. You shouldn't merge what you can't explain.

Table of Contents

• Why
• Features
• Demo
• Installation
• Usage
• Auto-suggestion hook
• Configuration
• Requirements
• Project layout
• Packaging
• Contributing
• License

Why

AI writes code fast. The risk is shipping it without reading it. Tests catch broken code; nothing catches code you don't understand. handoff closes that gap by checking that the human who clicks "merge" can actually explain the change — its location, its rationale, and its behavior.

Features

• 🧬 Hybrid question source — combines conversation context (the why: decisions, trade-offs, what could break) with git diff (the where: real file:line locations), and degrades gracefully when there's no git.
• 📏 Scaled to the change — ~3 questions for a small diff, 5 for medium, 8–10 for a large feature.
• 🔀 Mixed question types — multiple-choice for "where / what behavior", open-ended for "why".
• 1️⃣ One question at a time — you answer, it evaluates, then continues.
• 🎯 Wrong-answer flow — points you to the file:line without revealing the answer, lets you retry once, then reveals it with a short explanation.
• 🏁 Score + weak areas — Score: N/total plus the topics to revisit, each with a file pointer. Encouraging, not punitive.
• 🌍 Your language — the quiz runs in whatever language you're writing in.

Demo

Installation

Via the Vercel skills CLI (recommended)

npx skills add arimet/handoff

This scans the repo's SKILL.md, detects your installed agent, and installs handoff into the right path (~/.claude/skills/ for Claude Code).

Manually

# Symlink (handy while developing — edits stay live)
ln -s "$(pwd)/skills/handoff" ~/.claude/skills/handoff

# …or copy
cp -r skills/handoff ~/.claude/skills/handoff

Full instructions — including enabling and tuning the optional hook — are in skills/handoff/references/install.md.

Usage

After Claude finishes a feature, trigger it manually:

/handoff

…or just ask in natural language: "quiz me on what you built", "vérifie que j'ai compris", "test my understanding", "comprehension check".

Auto-suggestion hook

An optional, non-blocking Stop hook nudges you to run /handoff when a session produced a large diff. It only prints a suggestion — it never forces the quiz and never blocks Claude. Register it in ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/skills/handoff/scripts/suggest-quiz.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Configuration

The hook suggests /handoff when either threshold is reached. Override the defaults with environment variables:

Counts include tracked changes (staged + unstaged) and new untracked files, so files Claude just created are counted.

Requirements

• Claude Code with skills support.
• git (optional) — anchors questions on real file:line locations and drives the hook. Without git, the skill still works from conversation context.
• No extra tools to install. The hook parses its event with node (always present — Claude Code runs on Node) and falls back to jq if available. You do not need to install jq.

Project layout

.
├── README.md
├── LICENSE
└── skills/
    └── handoff/
        ├── SKILL.md             # the skill: triggering + quiz procedure
        ├── scripts/
        │   └── suggest-quiz.sh  # optional, non-blocking Stop hook
        ├── references/
        │   └── install.md       # install + hook setup and thresholds
        └── evals/
            └── evals.json       # test cases (excluded from the packaged .skill)

Packaging

Produce a distributable .skill archive (a zip with handoff/ at its root, excluding evals/):

# Using Anthropic's skill-creator
python -m scripts.package_skill skills/handoff

Install the result by unzipping handoff.skill into ~/.claude/skills/.

Contributing

Issues and pull requests are welcome. When changing the skill:

1. Keep SKILL.md lean — push detail into references/.
2. Update evals/evals.json with a test case for new behavior.
3. Run bash -n skills/handoff/scripts/suggest-quiz.sh and smoke-test the hook.

License

Released under the MIT License.