Agent Ops · agent skill

Handoff Memory

Resume any task in a minute, in any session.

What it does

Loads when it is needed

Your agent loads it when a task outlasts one session, context runs low or the user says resume. It carries 5 rules and reads a profile.md with your details before it starts, so the output matches your brand and project.

Same prompt, with and without

Hand off a half-finished migration

Prompt · Context is nearly full and I need to stop for the day. Set this up so I or a fresh session can resume tomorrow.

Task: move the FastAPI orders API from SQLAlchemy 1.4 to 2.0. Goal: all 118 tests pass on SQLAlchemy 2.0, no deprecation warnings.
Done so far: upgraded the pin in pyproject.toml; converted app/models/*.py to Mapped[] style (6 files); converted app/repos/orders.py and app/repos/customers.py to select() style.
In progress: app/repos/invoices.py, half converted; session.query() calls remain at lines 40-95.
Not started: app/repos/refunds.py, app/jobs/*.py, tests/conftest.py fixtures.
Last test run: 97 pass, 21 fail, all in invoices and refunds. `uv run pytest -x -q` takes 14s.
Decision made: keep the sync engine, do not move to async in this task (owner wants a separate PR). Dead end: tried the `sqlalchemy.future` shim, it conflicts with the 2.0 Session, abandoned.
No plan.md, progress.md or memory.md exist yet.

Profile used: Agents: Claude Code; Project: FastAPI orders API; Stack: Python, uv, pytest, Postgres; Team size: 1 (solo)

Without the skill

Nothing is saved (no file access here). One `progress.md` for the repo root: Goal: all 118 tests pass on SQLAlchemy 2.0 with no deprecation warnings. Last updated 2026-10-17. Decisions: keep the sync engine, async is a separate PR. Dead end: the `sqlalchemy.future` shim conflicts with the 2.0 Session. Done: pin upgraded; `app/models/*.py` on Mapped[] (6 files); orders.py and customers.py on select() style. In progress: `invoices.py`, `session.query()` remains at lines 40-95. Not started: refunds.py, `app/jobs/*.py`, `tests/conftest.py` fixtures. Last run: 97 pass, 21 fail, all in invoices and refunds. `uv run pytest -x -q` takes about 14s. Next: 1. finish invoices.py and re-run its tests. 2. refunds.py. 3. jobs. 4. conftest fixtures. 5. full suite with `-W error::sqlalchemy.exc.RemovedIn20Warning`. Done at 118/118 and a clean warning run. Add to `CLAUDE.md`: Migrating SQLAlchemy 1.4 -> 2.0. Read `progress.md` first and update it as you finish each item. Don't move to async or use `sqlalchemy.future`. Before you close the terminal: `git status`, then commit as `WIP: SQLAlchemy 2.0 migration (invoices.py half converted)`, or use a branch or stash. Rerun the tests once and update the counts. Prompt for tomorrow: "Resume the SQLAlchemy 2.0 migration. Read progress.md, run `uv run pytest -q` to confirm the state, then continue with app/repos/invoices.py." The line range will go stale once you edit invoices.py.

With the skill

Nothing is saved (no file access here). Four files, ready to paste into `.agent/`; branch and commit hashes are placeholders. `plan.md`: Goal: orders API on SQLAlchemy 2.0, no deprecation warnings. Done when `uv run pytest -q` shows 118 passed. Steps 1-3 ticked (pin, models, orders and customers repos); 4 invoices.py half done, `session.query()` at lines 40-95; 5 refunds.py; 6 jobs; 7 conftest fixtures; 8 full run with warnings as errors. Out of scope: async engine, separate PR. `progress.md` (2026-10-17): step 4 in progress, last run 97 pass / 21 fail, all in invoices and refunds. Tried the `sqlalchemy.future` shim: conflicts with the 2.0 Session, abandoned. `memory.md`, each entry with a date and reason: tests are `uv run pytest -x -q`, ~14s. Sync engine stays, async is the owner's separate PR. Don't use the `future` shim. `handoff.md`: Next action: convert the remaining `session.query()` calls in `app/repos/invoices.py:40-95` to `select()` with `session.execute()/scalars()`, then re-run the invoices tests. Verify: `uv run pytest -q` (expect 97 passed, 21 failed before the change, fewer after). Do not: use the `future` shim; move to async. Tree: unknown, run `git status`; invoices.py is likely uncommitted. One line for CLAUDE.md, waiting for your yes: + If .agent/handoff.md exists, read it first and resume from its next action. Tomorrow, say "resume": it reads the four files, runs the verify commands, reports in five lines and continues. Tonight: `git status`, commit the work in progress, fill in the hashes.

Both answers from the same model (Claude sonnet), 2026-10-17. The one without the skill was written in a separate session that never saw it. Shortened where marked with …

Install

One command, in your project

It detects your agent; add --agent all for every agent.

npx proskills-cli add handoff-memory --order <order id from your receipt>

Or copy the skill folder (the one holding SKILL.md) into the directory your agent reads, then restart it or start a new session.

Agent	This project	Every project
Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.agents/skills/ (or .cursor/skills/)	~/.cursor/skills/
Codex	.agents/skills/	~/.agents/skills/
Gemini CLI	.agents/skills/ (or .gemini/skills/)	~/.gemini/skills/

Changelog

What changed

v1.0.0 · 2026-10-17
- First versioned release: Plan, progress and memory files any session can resume from in a minute.
- Scanned 100/100 before release.

Keep it current with npx proskills-cli update; your profile.md is never touched. Everyone who bought it gets the update free and an email when it lands.

Same collection

More from Agent Ops

The scan checks spec compliance, token cost, clarity and security patterns. A clean scan is not a guarantee: static scanners can be evaded. Scan any skill yourself.