// Use when work is changing sessions, agents, or machines and the next pass needs a compact handoff document with current state, open questions, and next steps instead of raw chat history.
Use when Copilot CLI's built-in tools do not cover a service you need — for example PostgreSQL, Redis, Jira, Slack, or an internal API — and you need to add an MCP server beyond the default GitHub MCP. NOT when the built-in tools already cover the task.
Use when designing or reviewing an AI agent system that needs policy-based access controls, intent classification, tool-level rate limiting, trust scoring for multi-agent workflows, or append-only audit trails.
Use when auditing an AI agent system against the OWASP Agentic Security Initiative Top 10 — checks tool access, prompt boundaries, memory handling, and operational safeguards across the agent pipeline.
Use when you need to evaluate an LLM pipeline or AI feature systematically — sets up an eval harness with test cases, scoring rubrics, and pass/fail tracking rather than one-off manual spot-checks
Use when reviewing or planning QA strategy for a feature, PR, or release so test coverage, test quality, reliability, and defect reporting are handled as a coherent engineering discipline instead of ad hoc checks.
Use when creating or validating a Git branch name so the branch follows a conventional type/description format, matches the work being done, and starts from the right base branch.
| name | handoff |
| description | Use when work is changing sessions, agents, or machines and the next pass needs a compact handoff document with current state, open questions, and next steps instead of raw chat history. |
| metadata | {"category":"workflow","agent_type":"general-purpose","origin":"adapted from mattpocock/skills productivity handoff"} |
Handoff turns the current state of work into a portable markdown brief that another session, agent, or collaborator can pick up quickly.
The goal is not "summarize everything." The goal is to capture only the information that would otherwise be expensive to rediscover.
| Instead of handoff | Use |
|---|---|
| Continuing the same Copilot CLI session later | cross-session-memory or /resume |
| Recording durable project guidance for everyone | knowledge-curator |
| Writing a committed spec, ADR, PRD, or issue | the destination artifact itself |
Start with one sentence:
If the user gave a follow-up goal, tailor the handoff around that goal instead of the whole conversation.
Prefer a temporary markdown file outside the repo unless the user explicitly wants a committed file.
Examples:
# PowerShell
$path = Join-Path $env:TEMP ("handoff-" + [System.Guid]::NewGuid().ToString("N") + ".md")
# POSIX shell
path="$(mktemp -t handoff-XXXXXX.md)"
If a path already exists, read it before overwriting.
Do not restate content that already lives in:
Link to those artifacts by path, URL, or commit hash and explain only why they matter.
Before writing the handoff document, actively redact sensitive data in the captured context:
[REDACTED][REDACTED][REDACTED][INTERNAL URL]Do not simply omit the fact that something existed. Replace the value with a placeholder so the next session knows there was sensitive context without seeing the secret itself.
Good handoffs usually include:
Skip long narrative unless it changes the next decision.
If the handoff is crossing sessions, machines, or agents, capture the minimum task ledger needed to resume without guesswork:
ready, blocked, awaiting-review, needs-verification)For parallel work, list each active lane separately instead of flattening it into one vague status paragraph.
If another skill would help the next session, name it explicitly and explain why.
Examples:
implementation-review for "compare this delivered diff against the original ask"grill-me for "the plan still has unresolved assumptions"verification-before-completion for "prove the claim before reporting success"The handoff is only useful if the next person can find it quickly. End by giving the exact saved path.
# Handoff
## Objective
- ...
## Current State
- ...
## Task Ledger
| Task | Owner | Status | Resume Trigger |
|------|-------|--------|----------------|
| ... | ... | ... | ... |
## Key Decisions
- ...
## Important Files and Refs
- path or URL - why it matters
## Open Questions
- ...
## Risks or Gotchas
- ...
## Suggested Skills
- ...
## First Next Step
- ...
| Rationalization | Reality |
|---|---|
| "The next session can just read the chat." | Raw chat is slow to rehydrate and easy to misread. |
| "I'll copy every detail so nothing is lost." | Bloated handoffs hide the actual next action. |
| "I'll paste the whole diff again." | Existing artifacts should be referenced, not duplicated. |
cross-session-memory - resume or search prior Copilot sessionsknowledge-curator - promote repeated lessons into durable project guidanceimplementation-review - compare delivered work against the original request