agentleFS
Sign inStart free
t1mericksont1merickson/skills/handoff/SKILL.md

handoff

Skill1 starsChanged 2 months agoMITView on GitHub

Write one self-contained markdown doc so another agent, a PR reviewer, or a future session can pick up the work with zero context. Use on /handoff, "write a handoff", "note for another agent", "handoff doc for the merge agent", "write down everything so it survives", or /handoff closeout / "closeout" at the end of a project or phase. Not for mid-task save points the current session will reload (use checkpoint) or for explaining a root cause to the user (use explaining-problems).

191 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use decision-mapping, setup-ts-deep-modules and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • FabienDehopreSkill

    decision-mapping

    Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.

    Also in 8 projects that use this

  • liufeng1976Skill

    setup-ts-deep-modules

    Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.

    Also in 42 projects that use this

  • AWSSkill

    to-questionnaire

    Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

    Also in 93 projects that use this

  • GoogleSkill

    ask-matt

    Ask which skill or flow fits your situation. A router over the skills in this repo.

    Also in 87 projects that use this

  • RoentekSkill

    loop-me

    Grill me about specs for the workflows I want to build, within this workspace.

    Also in 51 projects that use this

  • LesaniSkill

    writing-beats

    Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.

    Also in 54 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 172 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If a HANDOFF.md already exists from earlier work, read it first.

    line 13
  2. Distinctive:

    Never a hidden path, never memory, never a scratch folder.

    line 14
  3. Distinctive:

    Use these sections in order.

    line 18
  4. Distinctive:

    Before writing, check the live state you're about to describe: git status, git log -1, and the latest build or test result if one exists.

    line 30
  5. Distinctive:

    Keep it tight. A reader should get the picture from the first screen.

    line 32
  6. Distinctive:

    Do everything above, plus move durable knowledge out of the chat into the project's real docs:

    line 38
  7. Distinctive:

    Not into memory files, not into hidden folders.

    line 43
  8. Distinctive:

    When the reader is a PR reviewer or merge agent, write the same file, framed as a review note: what changed, what to look at hardest, how …

    line 51

“Common” is measured: kept by at least 6 in 10 of the 172 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

handoff

The reader has none of this conversation. They have the repo, this one file, and nothing else. Write for them.

Default output

  • One file. Default HANDOFF.md at the repo or project root. If the user names a path or filename, use that.
  • If a HANDOFF.md already exists from earlier work, read it first. Update it in place when it covers the same work; otherwise use HANDOFF-<slug>.md. Never silently drop someone else's content.
  • Never a hidden path, never memory, never a scratch folder.

What goes in

Use these sections in order. Skip a section only when it's truly empty, and say "none" rather than padding.

  1. Goal. What we're building or fixing and why, in two or three sentences.
  2. State now. What works, what doesn't, what's half done. Branch name and last commit hash.
  3. Verified, and how. Each claim with its check: build passed, tests green (which ones), ran it and saw X. Anything not checked is marked unchecked.
  4. Corners cut and known risks. Be honest. Shortcuts, hacks, flaky bits, things that will bite later. This is the section reviewers need most.
  5. Data model and schema changes. Migrations, format changes, anything that touches stored data. "None" if none.
  6. Decisions and rejected paths. What was chosen, what was tried and dropped, and what killed it, so the reader doesn't retry it.
  7. Open questions. What's unresolved and who decides it (the user or the next agent).
  8. Next steps. Numbered, concrete, first one doable right away.
  9. Files. Absolute paths to every file, doc, log, or artifact referenced above.

Before writing, check the live state you're about to describe: git status, git log -1, and the latest build or test result if one exists. Don't describe state from memory of earlier in the session.

Keep it tight. A reader should get the picture from the first screen. Detail goes lower.

Closeout mode

Triggered by "closeout", "/handoff closeout", or asks like "write down everything hard won" or "postmortem, discoveries, my preferences" at the end of a project or phase.

Do everything above, plus move durable knowledge out of the chat into the project's real docs:

  • Postmortems and hard-won findings go in the project's docs folder (e.g. docs/), or a new docs/NOTES.md if none exists.
  • API quirks and undocumented behavior go next to the code or in the project's API docs.
  • The user's stated preferences for this project go in the project's CLAUDE.md. Add to it; don't rewrite what's there. If the repo has no CLAUDE.md, ask before creating one.
  • Not into memory files, not into hidden folders.

The test for each item: would someone who read the whole repo still not know this? If they'd know it, skip it.

List every doc you added to or changed at the end of the handoff file and in your reply.

PR handoffs

When the reader is a PR reviewer or merge agent, write the same file, framed as a review note: what changed, what to look at hardest, how it was verified, risks.

Posting it as a PR comment or description sends it off this machine. Only do that if the user asked for it in this request. Otherwise write the file and offer.

Finishing

  1. Write the file.
  2. Open it yourself (open <path> on macOS) so the user sees it.
  3. Reply with the one file to hand over, by absolute path, first line. Then any closeout docs changed. Then anything you couldn't verify.

Committing the handoff follows the repo's normal git rules. In a solo repo, commit it with the work. In a shared repo, ask.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free