portable-handoff
Skill0 starsChanged 2 months agoMITView on GitHub
Package any handoff, brief, or context transfer as ONE self-contained artifact Nick can copy or attach in a single action. Fires whenever he asks to hand work to another chat, carry context into a new session, package something up, write a brief for a fresh chat, or continue work elsewhere. Also fires proactively at the end of a substantial session when clear next steps exist. Never split a handoff across a document plus attachments, zips, or folders.
In this repository15 other files it gives its agents.
- blog-cold-readSkill
- content-proportion-checkSkill
- defensibility-checkSkill
- giving-feedbackSkill
- hamming-taste-principlesSkill
- idea-to-briefSkill
- learning-mediumSkill
- linear-write-cleanupSkill
- saddles-positioningSkill
- session-stateSkill
- skill-auditSkill
- strategy-decisionsSkill
- transcript-auditSkill
- uncertainty-killerSkill
- writing-craftSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
Gotchas: Every trap that cost time.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Portable handoff
Nick moves work between chats often, and the thing that keeps breaking is not the content of the handoff. It is the packaging. A document that says "attach the zip alongside this" means he has to find the zip, find the document, and do two things in the right order — and he loses track. He has asked for single-artifact handoffs repeatedly.
One artifact. One copy action. Nothing attached.
The rule
A handoff is finished when Nick can select all of one file, copy, paste into a fresh chat, and that chat can do the work with no further input from him. If it needs a second file, a zip, a folder, or a "you'll also need to attach…", it is not finished.
Deliver it as a single .md file so he has the choice of pasting the contents or attaching the one file. Both are one action.
What goes inside
Inline every text file the next chat needs. Source code, config, templates, copy decks — all of it, verbatim, in fenced code blocks at the bottom under Appendix A, Appendix B, and so on. Reference them from the setup steps. Do not summarize code and hope the next chat reconstructs it; a rebuild from prose loses the exact constants, timings and bug fixes that took iterations to get right.
Long is fine. A 60 KB handoff that works beats a 5 KB one that needs a scavenger hunt.
Binaries cannot be pasted, so give the command that regenerates them. Fonts from npm, images rendered by a script, sample data generated by a snippet. If a binary genuinely cannot be regenerated, say so explicitly at the very top under a heading Nick cannot miss, and name the single file he must attach. That is the only acceptable exception, and it should be rare.
Never assume file paths carry over. A new session gets a new working folder, so absolute paths from the old one are dead. Write setup steps that create files from scratch in a relative folder.
Structure that works
- Step 0 — recreate the working files. Commands and appendix pointers, in order. End with a verification step: run something, and describe in plain words what a correct result looks like so the next chat can confirm its starting point before changing anything.
- What exists today. The current state, concretely. Timings, structure, what each part does.
- The change requested. What Nick actually wants, and why the current version falls short.
- Reference specs. Anything the next chat cannot see — screenshots described in words with coordinates and colours, verbal feedback, decisions made in conversation. Assume zero shared context.
- Non-negotiables. Brand tokens, product-truth rules, anything already corrected that must not drift back. Say why, or the next chat will "improve" it back to the bug.
- Build and verify. Exact commands.
- Gotchas. Every trap that cost time. Bugs hit and fixed, tools missing from the sandbox, permissions that are blocked and should not be worked around.
- Appendices. The full source of every file.
Write it cold
The next chat has no memory of the conversation. Anything that lives only in chat history — a screenshot, a preference, a rejected approach and the reason it was rejected — is lost unless it is written down. Re-read the draft as someone who has never seen the project. Ambiguity that feels obvious in context becomes a wrong guess in a fresh session.
Include what was tried and abandoned. Without it the next chat re-proposes the thing already rejected.
Assembling it
Build the file with a script rather than retyping code by hand. Read the source files, concatenate them into the appendices, and write the result. Retyping is slow and introduces errors in exactly the places that matter, like long numeric arrays and path data.
Why paste beats a pointer here
Two findings from a ten-session audit, kept because they are not re-derivable:
- The write-doc → open-chat → paste round trip taxed 4 of 10 consecutive sessions. That tax is real and it applies to this skill too — which is why the close-out should offer to launch the work now and only package it if Nick declines. A handoff is the fallback, not the finish line.
- Pasting the body has tripped policy filters and killed 2 of 10 sessions on the first turn. This is the known cost of the path Nick chose. Mitigate it, do not ignore it: when the file is long or quote-heavy, tell him to attach the file rather than paste its contents — both are one action, and attaching does not get scanned as a wall of pasted text. Keep verbatim customer quotes as transcript references rather than inline blocks.
- Pasted context arrives as one undifferentiated block, which bypasses the skill triggers that would have fired on the same request phrased normally. So lead the handoff with the request in Nick's own register — a plain first line like "continue the paid ads campaign" above the appendices — rather than opening cold with a state dump. The block still carries everything; the first line is what lets the next session route correctly.
Nick chose this skill over Linear-backed state on 2026-08-06. If a session-state skill is present and
says never to produce a paste-me document, this skill wins — say so once and move on. Do not silently do
the opposite of what he asked.
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
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.

