create-handoff

Original：🇺🇸 English

Translated

Generate a handoff document after implementation work is complete — summarizes changes, risks, and review focus areas for the review pipeline. Use when done coding and ready to hand off for review.

2installs

Sourcegeneraljerel/chalk-skills

Added on2026-03-10

NPX Install

npx skill4agent add generaljerel/chalk-skills create-handoff

SKILL.md Content

View Translation Comparison →

Create Handoff

Generate a structured handoff document summarizing implementation work for the review pipeline.

Step 1: Determine the session name

Derive a session name from context:

If the user provided
```
$ARGUMENTS
```
, sanitize it to a safe kebab-case string (lowercase, strip any characters that aren't alphanumeric or hyphens, collapse multiple hyphens) and use that as the item name
Otherwise, infer from the current branch name (e.g.
```
feature/issue-24-authentication
```
→
```
issue-24-authentication
```
)
If on
```
main
```
/
```
master
```
, ask the user what to name the session

Step 2: Create the review session

Create the session directory and handoff file:

sh

SESSION_DIR=".chalk/reviews/${session_name}"
HANDOFF_PATH="$SESSION_DIR/handoff.md"
mkdir -p "$SESSION_DIR"

If the handoff file already exists with content beyond the template, ask the user whether to overwrite or create a new timestamped session.

Step 3: Determine the base branch

Figure out what the current branch was based on:

Check for a merge base with
```
main
```
:
```
git merge-base main HEAD
```
If that fails, try
```
origin/main
```
If that fails, try
```
master
```
/
```
origin/master
```

Store this as

{base}

for later steps.

Step 4: Gather context

Run these to understand the scope of changes:

sh

git log --oneline {base}..HEAD
git diff --stat {base}..HEAD
git diff {base}..HEAD

Step 5: Detect and run project checks

Auto-detect the project's build/check tooling and run what's available. Check for these in order:

Node.js — if

package.json

exists:

Detect package manager:
```
yarn.lock
```
→ yarn,
```
pnpm-lock.yaml
```
→ pnpm, else npm
Run build:
```
{pm} run build 2>&1 | tail -5
```

Run typecheck:

{pm} run typecheck 2>&1 | tail -5

OR

npx tsc --noEmit 2>&1 | tail -5

Run lint:
```
{pm} run lint 2>&1 | tail -5
```
Run test:
```
{pm} run test 2>&1 | tail -5
```

Rust — if

Cargo.toml

exists:

```
cargo check 2>&1 | tail -5
```
```
cargo test --no-run 2>&1 | tail -5
```
```
cargo clippy 2>&1 | tail -5
```

Go — if

go.mod

exists:

```
go build ./... 2>&1 | tail -5
```
```
go vet ./... 2>&1 | tail -5
```
```
go test ./... -short 2>&1 | tail -5
```

Python — if

pyproject.toml

or

requirements.txt

exists:

```
python -m py_compile
```
on changed
```
.py
```
files
```
python -m pytest --co -q 2>&1 | tail -5
```
(collect only, don't run)

Make — if

Makefile

exists with

build

/

check

/

test

targets:

```
make build 2>&1 | tail -5
```
```
make check 2>&1 | tail -5
```
```
make test 2>&1 | tail -5
```

If no build system is detected, note "No build system detected — skipped automated checks".

Important: If any check fails, note the failure — do NOT try to fix it. The handoff should report the current state honestly.

Step 6: Write the handoff

Write to

HANDOFF_PATH

. Use this format:

markdown

# Handoff

## Scope
- Item: {item reference — e.g. "#24 — Add authentication" or "Refactor IPC layer"}
- Goal: {1-sentence summary of what was accomplished}

## What Changed
{bullet list of logical changes — describe WHAT each change does, not just file names}

## Files Changed
{bullet list of every file modified/created, from git diff --stat}

## Risk Areas
{bullet list of things that could break, have edge cases, or need careful review}

## Commands Run
{bullet list of every command run and its pass/fail status}

## Known Gaps
{bullet list of things NOT done — e.g. "no tests written", "error handling incomplete", "hardcoded values"}

## Suggested Focus For Reviewers
{bullet list of what reviewers should look at most carefully — prioritize by risk}

Step 7: Report to the user

Show:

The handoff file path
A brief summary of what was captured
Suggest next step: run
```
/create-review
```
to generate a review prompt for any AI reviewer

Rules

Do NOT modify any source code — this skill is read-only except for the handoff file
Be honest about failures — if build/typecheck fail, report that clearly
Keep descriptions concrete and actionable — avoid vague statements like "various improvements"
List ALL files from
```
git diff --stat
```
, don't summarize or skip any
If there are no commits ahead of base, warn the user that there's nothing to hand off

create-handoff

NPX Install

Tags

SKILL.md Content

Create Handoff

Step 1: Determine the session name

Step 2: Create the review session

Step 3: Determine the base branch

Step 4: Gather context

Step 5: Detect and run project checks

Step 6: Write the handoff

Step 7: Report to the user

Rules