{"id":51226793,"url":"https://github.com/uchimata2/handoff-skill","last_synced_at":"2026-06-28T12:31:15.554Z","repository":{"id":366387530,"uuid":"1276018132","full_name":"uchimata2/handoff-skill","owner":"uchimata2","description":"Portable, project- and agent-neutral skill for transferring working context between AI sessions, with a strict single source of truth.","archived":false,"fork":false,"pushed_at":"2026-06-21T15:49:21.000Z","size":27,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T16:26:48.496Z","etag":null,"topics":["agent-skill","ai-agents","ai-tools","claude-code","context-management","copilot","developer-tools","handoff","llm","markdown","session-handoff","single-source-of-truth"],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uchimata2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T12:43:51.000Z","updated_at":"2026-06-21T15:49:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uchimata2/handoff-skill","commit_stats":null,"previous_names":["uchimata2/handoff-skill"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/uchimata2/handoff-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchimata2%2Fhandoff-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchimata2%2Fhandoff-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchimata2%2Fhandoff-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchimata2%2Fhandoff-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uchimata2","download_url":"https://codeload.github.com/uchimata2/handoff-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchimata2%2Fhandoff-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34889047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agents","ai-tools","claude-code","context-management","copilot","developer-tools","handoff","llm","markdown","session-handoff","single-source-of-truth"],"created_at":"2026-06-28T12:31:15.058Z","updated_at":"2026-06-28T12:31:15.548Z","avatar_url":"https://github.com/uchimata2.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Handoff skill — portable package\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Latest release](https://img.shields.io/github/v/release/uchimata2/handoff-skill?sort=semver)](https://github.com/uchimata2/handoff-skill/releases)\n\nA drop-in **handoff** skill: it lets any AI working session — a later session, another\nagent, or another person — pick up work seamlessly, while keeping a strict single source\nof truth. Every fact has exactly one home, and the handoff only *points* to those homes.\nIt works in any project (development or not), with or without an external task tracker,\nand across agents.\n\n## What's in here\n\n- `handoff.core.md` — the always-loaded **spine**: configuration, the routing model, detection,\n  session types, and the binding contract.\n- `flows/` — the two on-demand flow files the spine loads per run: `create.md` (Create / Close)\n  and `resume.md` (Resume / Status).\n- `config.example.md` — the per-project config schema.\n- `bindings/` — tracker bindings (`notion`, `local-markdown`) + how to write your own.\n- `agents/` — per-agent stub templates (`claude.SKILL.md`, `copilot.agent.md`), plus\n  optional Claude Code hook reminders (`claude.hooks.md`).\n- `EXAMPLES.md` — annotated good-vs-bad handoffs and walkthroughs by session type.\n- `README.md` — this file.\n\nNothing here is project-specific; all specifics live in the config you create. The above is a\nconceptual overview; the authoritative list of files bundled into the `handoff.skill` artifact is\nthe `$items` manifest in [`scripts/build-skill.ps1`](scripts/build-skill.ps1).\n\n## Install in a new project\n\n1. **Copy the package.** Drop this folder into the new repo (e.g. at\n   `.agents/handoff-skill/`).\n2. **Create a config.** Copy `config.example.md` to a project location (e.g.\n   `.agents/handoff/config.md`) and fill in `handoff_file`, `tracker`, `project_docs`,\n   and `language`.\n3. **Choose a tracker.** Set `tracker` to a binding in `bindings/` and fill its\n   `tracker_*` keys — or `tracker: none`. Need a different tracker? See\n   `bindings/README.md`.\n4. **Wire your agent.** Copy the matching template from `agents/` into your agent's native\n   location and replace `{{package}}` (this folder's path) and `{{config}}` (your config\n   path):\n   - **Claude Code** → `.claude/skills/handoff/SKILL.md`. That one skill is enough: invoke it\n     with `/handoff` (or just say \"handoff\" / \"resume\" — its description lets Claude trigger it\n     automatically), and the core's §4 detection routes to Create (§5), Resume (§6), Status\n     (§6.5, a read-only preview), or Close (§5 *Close*, wrap up with no handoff), then loads the\n     matching on-demand flow file (`flows/create.md` or `flows/resume.md`).\n     - *Optional — distinct commands:* to expose each mode as its own command, add separate\n       skills `.claude/skills/handoff-{create,resume,status,close}/SKILL.md` (each pointing\n       straight at its flow file) → `/handoff-create`, `/handoff-resume`, `/handoff-status`,\n       `/handoff-close`.\n     - *Optional — reminders:* wire Claude Code hooks to nudge you to handoff/close at session\n       start or before a compaction — see [`agents/claude.hooks.md`](agents/claude.hooks.md).\n   - **GitHub Copilot CLI** → `.github/agents/handoff.agent.md`.\n   - **Another agent** → copy the closest template, point it at the core + config, and set\n     its `memory` value (its store, or `none`).\n5. **Done.** Trigger it by saying \"handoff\", \"resume\", \"hand off\", etc. (see core §4).\n\n## Build an installable artifact (optional)\n\nThe package is plain Markdown and needs no build to use — just copy it per the steps above.\nFor distribution you can bundle it into a single `handoff.skill` archive:\n\n```sh\npwsh scripts/build-skill.ps1\n```\n\nThis writes `dist/handoff.skill` — a zip of the package under a top-level `handoff/` folder.\nUnzip it into your project and follow the install steps above. The artifact is regenerated on\ndemand and is git-ignored. See [CHANGELOG](CHANGELOG.md) for release history.\n\n## How it works (one paragraph)\n\nThe core sorts every piece of session information into one of four stores — handoff file,\ntask docs, project docs, agent memory — using a short routing procedure (core §2–§3). The\nhandoff file holds only a pointer to what to resume plus pure session-ephemeral state;\neverything durable goes to its real home. Trackers are reached through a binding; memory\nis whatever your agent supplies (or none).\n\n## The routing model (visual)\n\nEvery piece of session information runs through the routing procedure (core §3). A single\ndiscovery can split into several facets — each is written to its own home — while the handoff\nkeeps only a pointer plus pure ephemeral state:\n\n```mermaid\nflowchart TD\n  start([\"Each piece of session info\"]) --\u003e q1{\"Secret / sensitive / user-private?\"}\n  q1 -- yes --\u003e drop[\"Exclude — store nowhere\"]\n  q1 -- no --\u003e q2{\"Task-specific facet?\"}\n  q2 -- yes --\u003e td[(\"Task docs\u003cbr/\u003evia tracker binding\")]\n  q2 -- no --\u003e q3{\"Generic / reusable facet?\"}\n  td --\u003e q3\n  q3 -- \"project-scoped \u0026 shareable\" --\u003e pd[(\"Project docs\")]\n  q3 -- \"cross-project / private\" --\u003e mem[(\"Agent memory\u003cbr/\u003eelse project docs\")]\n  q3 -- no --\u003e q4{\"Pure ephemeral,\u003cbr/\u003erecorded nowhere else?\"}\n  pd --\u003e q4\n  mem --\u003e q4\n  q4 -- yes --\u003e ho[[\"Handoff file\"]]\n  q4 -- no --\u003e pt[\"Already has a home —\u003cbr/\u003ehandoff only points to it\"]\n```\n\nThe four modes that consume this model — **Create** (§5) and **Close** (§5, *Close*) on the\nwrite side, **Resume** (§6) and **Status** (§6.5) on the read side:\n\n```mermaid\nflowchart LR\n  subgraph \"Create / Close\"\n    direction TB\n    c1[\"Route every discovery\u003cbr/\u003ethrough §3 to its home\"] --\u003e c2[\"Create: write handoff —\u003cbr/\u003epointer + ephemeral state only\"]\n    c1 --\u003e c3[\"Close: write no handoff —\u003cbr/\u003earchive any live one\"]\n  end\n  subgraph \"Resume / Status\"\n    direction TB\n    r1[\"Read handoff\"] --\u003e r2[\"Summarize\"]\n    r2 --\u003e r3[\"Resume: open homes,\u003cbr/\u003earchive, then continue\"]\n    r2 --\u003e r4[\"Status: stop —\u003cbr/\u003eno changes\"]\n  end\n```\n\nSee [`EXAMPLES.md`](EXAMPLES.md) for annotated good-vs-bad handoffs that put this into practice.\n\n## Degrades gracefully\n\n- **No tracker** (`tracker: none`): every session is treated as ad-hoc — the skill offers\n  to create a tracked item, or captures specifics in the handoff snapshot (core §7.1).\n- **No memory** (`memory: none`): memory-bound items fall back to project docs; nothing is\n  silently lost.\n\n## Learn more\n\nFor a one-minute conceptual overview of the skill, the four stores, and the modes, see the\n[project wiki](https://github.com/uchimata2/handoff-skill/wiki). For worked examples, see\n[`EXAMPLES.md`](EXAMPLES.md).\n\n## Roadmap\n\nPlanned work is tracked on the [project board](https://github.com/users/uchimata2/projects/1) —\na kanban auto-synced from issue `status:` labels. See [`PROJECT_BOARD.md`](PROJECT_BOARD.md) for\nhow it works, and [`CONTRIBUTING.md`](CONTRIBUTING.md) (with our\n[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)) to get involved.\n\n## License\n\n[MIT](LICENSE) © 2026 uchimata2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuchimata2%2Fhandoff-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuchimata2%2Fhandoff-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuchimata2%2Fhandoff-skill/lists"}