DEV Community: Felix Huang

Handing Work Between AI Agents Without Re-explaining Everything: project-handoff

Felix Huang — Sun, 08 Nov 2026 23:10:57 +0000

Handing Work Between AI Agents Without Re-explaining Everything: project-handoff

Reconstruct an afternoon you've probably lived through. In the morning you push a feature forward with Codex: the architecture trade-offs get talked through, a gnarly dependency pitfall gets smoothed over, one approach gets explicitly rejected. In the afternoon you switch to a different client to continue — and the new session knows nothing. What's the goal? Where did things stop? Which decisions are settled? You either re-narrate everything from scratch, or watch the agent enthusiastically rebuild the approach you rejected hours ago and step on the exact rake you already stepped on.

project-handoff-skill turns handoff into a set of files inside the project: every new session checks the handoff state before touching anything. It's bound to no particular client — it only relies on the AGENTS.md open convention that every agent already understands.

The skill comes from my own routine: five or six agent clients in rotation, every handoff done by re-explaining to a goldfish. I tried letting agents write handoff notes themselves; the problem was nobody could hold the notes to a shape — some ballooned until they ate the context window, some were written once and never read again. So the discipline itself became a skill: one setup question, records written to disk automatically, size on a hard budget.

Five situations where you want it

1. You switch between clients all day

Codex in the morning, ZCode in the afternoon, Kimi Code CLI at night — and you don't want to re-brief any of them. After install, one sentence sets it up: "Set up project-handoff mode for this project." It installs at user level and drops a toggle file in the project root. From then on every new session self-checks: never configured → asks once whether to enable; already configured → silently keeps going, never asks again.

2. The project spans days or weeks

You want to resume, not excavate chat history to reconstruct progress. Once enabled, the project gains a HANDOVER.md — goals, current progress, settled decisions, pitfalls — and every new session reads it before working. What's done, what's next, what must not be touched: visible at a glance.

3. You're forced to switch tools mid-flight

Quota exhausted, context window full, a provider having a bad day — the switch isn't optional, and the new tool needs to know immediately where things stand and what's off-limits. This is exactly the handoff file's home turf: it doesn't depend on any client's session memory. The files live in the project; anyone can read them.

4. You've been burned by "I forgot to mention one thing"

Forgot to say approach A was rejected → the agent rebuilds it. Forgot to say that dependency is a trap → the agent steps in it again. Handoff records pin these negative facts in plain sight — rejected approaches, dead-end paths, reproduced pitfalls — where the new session sees them before starting, instead of after the collision.

5. Several people (or agents) rotate through one project

You log off; whoever picks it up next — human or agent — needs the same "where we are" picture. The handoff file sits in the repo, readable by both. Both sides of the relay are looking at the same facts.

When NOT to install it

The honest part of a recommendation is the reverse list. If you use exactly one client and never switch, that client's own session memory is enough and handoff files are pure overhead. One-off script repos have no "next session" to hand off to. And if agents are entirely managed for you and you never touch the workflow, extra files and prompts will only add noise.

How it stays contained

The three classic failure modes of agent-written handoff notes — unbounded growth, write-once-never-read, uncertainty about what belongs — each get a gate:

Bounded footprint: handover records over 8KB / 300 lines auto-slim down to the three most recent sections, the rest archived. Run records keep 20 entries per agent; older ones compress into an archive index. The agent normally reads only small files.
Self-explaining footprint: one sentence — "run a health check on the handoff setup" — has the agent execute --status: what this is, whether it's on, which files are its own, how to turn it off, how to remove it. One command, full answer.
Heartbeat lock for orphans: a session that dies halfway without closing out gets auto-flagged as "interrupted, awaiting pickup" after a timeout — the next agent sees it immediately.
Privacy red line: hooks record event names, timestamps, and session IDs only — never prompts, replies, or command contents. A dedicated test pins this promise, and 45 replay cases run on macOS + Linux CI.

Install and use

# Option 1: skills CLI (recommended)
npx skills add kelegele/project-handoff-skill

# Option 2: drop it into a skills dir manually (dir name must be project-handoff)
# Cross-agent: ~/.agents/skills/   ZCode: ~/.zcode/skills/   Codex: ~/.codex/skills/

# Update
npx skills update project-handoff

After install, two phrases drive everything:

Set up project-handoff mode for this project

Run a health check on the handoff setup

Daily service commands (all plain speech; the agent runs the scripts):

You say	It runs	What it does
enable / disable handoff	`--enable` / `--disable`	idempotent toggle; disabling flips the switch and keeps every record
health check	`--doctor`	config / hook wiring / permissions / timezone, graded PASS/FAIL/WARN
handoff status	`--status`	mode, file ownership, recent runs, footprint, uninstall instructions
clean up records	`--gc`	run-record rotation + handover slimming

Three quick answers

Does it work with an agent it's never heard of? Yes. The shared artifacts rely only on the AGENTS.md convention; any compatible client reads the same files. Automatic recording is a bonus, not a dependency.

Will it keep asking whether to enable? No. Asked once, then silent while config is valid. If config breaks, it names the specific problem instead of pretending nothing was ever configured.

How do I remove it completely? --status prints the full list: delete the project toggle file and docs/execution/, remove the handoff section from AGENTS.md, delete the skill directory. No residual dependencies anywhere.

Start small

Pick a project where you genuinely switch between tools. Install it, enable handoff, work half a day normally, then continue once from a different client. You'll see immediately how much re-explaining the file just saved you.

Repo on GitHub; issues and ideas welcome. It's the other half of the same puzzle as agentsmd-skill: agentsmd turns lessons into rules (scene guide, design reasoning), project-handoff carries progress to the next session — one makes the AI remember how to work, the other makes it know where you left off.

Stop Re-explaining Your Project to AI Coding Agents: Distill Session Lessons into AGENTS.md

Felix Huang — Sun, 08 Nov 2026 23:10:56 +0000

Stop Re-explaining Your Project to AI Coding Agents: Distill Session Lessons into AGENTS.md

It's Monday. You tell your AI coding agent: "this project uses pnpm, not npm." By Wednesday, a fresh session runs npm install again. Your corrections live in dozens of session logs; switch machines or switch tools and they're gone. Ask the AI to write a project conventions file instead, and you get a 500-line "best practices" dump — half common sense, half commands that were never run. The fatter the file, the more selectively the model reads it.

agentsmd-skill is built for exactly these moments: it distills the lessons from your current session into one-line, executable rules in an AGENTS.md file at your project root. Every new session — Claude Code, Codex, Cursor — reads it before starting work. It holds four hard lines: one rule says one thing, the whole file stays under 120 lines, every command is actually run before being written, and every change waits for your approval.

This post walks through five real scenarios — when to use it and how.

kelegele / agentsmd-skill

WorkBuddy skill: distill lessons into AGENTS.md (concise, spec-compliant, no bloat)

English | 简体中文

agentsmd

The pitfalls you hit — your AI never hits them twice.

Hand this session's pitfalls and corrections to your AI, say "write the lessons into AGENTS.md", and it distills them into one-line executable rules in the project root's AGENTS.md. From then on, every new session — Claude Code, Codex, or Cursor alike — reads it before starting work and follows it.

This skill came from my own endless "re-training" sessions. In every project there are things you want to cement: how this project builds, which boundaries must not be crossed, what coding conventions apply. If they don't live in AGENTS.md, you re-teach them to the agent in every new session — the same mistake three times, three corrections, all day gone.

It became a habit: whenever there was a general rule to keep, I had the agent write it into AGENTS.md. Then a new problem crept…

View on GitHub

1. The same pitfall, re-discovered every session

The classic case. In this session you corrected the AI three times: tests need a local database running first, the deploy script must never touch main, read logs with pnpm logs. Next session, it does all three wrong again.

At the end of the session, say:

Distill this session's lessons into project rules

It runs a fixed pipeline. Collect: only mistakes you pointed out, pitfalls actually hit, and preferences repeated twice or more count — one-off details and common sense are excluded up front. Distill: generalize, compress to one line, route to the right section, and pass three gates — "will recur", "violating it costs something", "fits in one line". Fail any gate, drop the rule. Merge: compare against existing rules — duplicates are discarded, overlaps merged, conflicts resolved in favor of the newer. Approve: the full change plan is shown to you; nothing is written until you approve.

2. Your AGENTS.md is already a junk drawer

Four hundred lines of mutually contradicting rules, half of them common sense? The model reading it is functionally reading nothing.

Same one-liner:

Update project rules: merge this session's lessons via the merge decision table; over 120 lines, cut before adding

It merges organically rather than appending: five gates (drop equivalents / merge overlaps / replace special cases with their general version / resolve conflicts toward the newer / delete outdated) filter everything, and as the file nears the 120-line hard cap it cuts before it adds. Content that still has value but doesn't clear the bar — say, rarely-used operational details — moves to docs/<topic>.md with a one-line reference left in the root file. What gets deleted is redundancy, not memory.

3. Cold start: you want a spec that actually runs

New project, no AGENTS.md yet. You want a first version that grows out of the directory structure, README, and build config — not a template with blanks.

No AGENTS.md yet — generate a first version with agentsmd; verify every command by actually running it

The difference here is command verification: every build and test command is executed for real before being written. Commands that can't safely run — deploys, migrations — are cross-checked line by line against package.json scripts, the Makefile, and CI config; anything that doesn't match doesn't get written. Why so stubborn? Because this file is trusted context for the agent: one hallucinated command is more dangerous than ten missing rules — the agent will believe it and run it.

4. A directory with no code, only documents and data

Report libraries, writing collaboration folders, data workspaces — there's no package.json, so "build commands" and "lint rules" are meaningless sections. What actually needs governing is data definitions, naming and archiving conventions, delivery review.

Settle working rules for this collaboration directory, and gather the scattered reports, data, and reference material

Before starting, it classifies the project as coding or work. Work-mode scans the document structure and naming conventions; rules lean toward data definitions, archiving, and delivery. Gathering moves documents into docs/, machine-readable data into data/, reference material into references/ — after checking references project-wide first, leaving cited files in place, and fixing links after every move. And every move requires your approval.

5. Your agent has personal memory, but it's disconnected from the project

Personal agents with memory systems (Hermes, OpenClaw) accumulate entries that drift away from specific projects: which project does this lesson belong to? Still valid here next week?

The low-effort move is to fold it into the same request:

Write the lessons into AGENTS.md, and gather the documents and data scattered in the root

It doesn't invent a private memory format — it rides the host. If your agent has a memory system, project-level memory is persisted in the host's own format, deduplicated and written only after approval; no memory system, it silently skips. TODO and CHANGELOG get updated along the way. Wherever it's installed, it grows into that agent's shape.

Install

# Option 1: skills CLI (recommended; one-liner updates later)
npx skills add kelegele/agentsmd-skill
npx skills update agentsmd

# Option 2: git clone into your skills dir (project-level: .claude/skills/agentsmd)
git clone https://github.com/kelegele/agentsmd-skill.git ~/.claude/skills/agentsmd
git -C ~/.claude/skills/agentsmd pull

# Option 3: install nothing — hand the repo URL to your agent:
# "Install this skill for me: https://github.com/kelegele/agentsmd-skill"

Also listed on ClawHub (clawhub install agentsmd) and the LobeHub Skills Marketplace. Some agents need a restart or a fresh session to pick it up. AGENTS.md itself follows the open spec — Claude Code, Codex, Cursor, and Gemini CLI all read the same file.

Three quick answers

Will it stuff the file with generic filler? No — piling up common sense to look productive is an explicit ban, and one-off details are filtered at the collection stage.

Will the file grow forever? No. 120-line hard cap, appending is forbidden, cuts come first; valuable detail migrates to docs/ with a one-line reference.

Will it touch files without asking? No. Rules file, memory, progress files, document moves — all come back to you as a complete plan before anything executes.

Start small

Pick a project where you keep correcting the same mistakes. Install the skill, end your next session with one sentence, and read the change plan it hands you — what enters, what merges, what gets cut, and why each rule reads the way it does. You'll know within one review whether this is your kind of tool.

Repo on GitHub; issues and ideas welcome. If you want the design reasoning, I wrote about why 120 lines beats 500, and how four of my design assumptions got falsified in two months.