# AI agent handoff skill workflow

Use this workflow to install, inspect, and test an Agent Skill that transfers
unfinished work between models, hosts, people, or service agents.

Canonical guide:
https://handover.sh/guides/ai-agent-handoff-skill

Raw skill:
https://skills.handover.sh/handover-record/SKILL.md

Source:
https://github.com/44-pixels/handover-mcp/tree/main/skills/handover-record

## What this workflow proves

A passing run proves more than in-run delegation:

1. The host discovers the intended `SKILL.md`.
2. The skill activates from a natural-language handoff request.
3. Handover MCP resolves the expected authenticated identity.
4. The publishing agent preserves the required state and source artifacts.
5. The published revision can be read back exactly.
6. A separately authenticated successor can retrieve and continue it without
   receiving the original chat.
7. Denied, read-only, stale-revision, and revoked identities remain constrained.

## 1. Inspect and install

```bash
# List the collection before installing anything.
npx skills add 44-pixels/handover-mcp --list

# Install only the portable handoff-record skill.
npx skills add 44-pixels/handover-mcp \
  --skill handover-record \
  --copy \
  --yes
```

Project-scoped installation is the safest default. Review the installed
`SKILL.md` before granting the host access to Handover MCP.

## 2. Connect named identities

Use a distinct human or service identity for each actor. Do not share a token
between the publishing and receiving hosts.

```text
Publisher identity:  skill-publisher
Receiver identity:   skill-successor
Denied identity:     skill-denied
Read-only identity:  skill-reader
```

Keep credentials in the host's secret storage or environment. Never place a
credential in `SKILL.md`, a prompt, a repository, or a handoff artifact.

## 3. Verify the publisher

Ask the first host:

```text
Verify the active Handover identity and workspace. Stop if either differs from
the expected publisher boundary.
```

Expected MCP operation:

```text
handover.whoami
```

Pass only when the server reports the expected principal, organization,
workspace, role, and scopes.

## 4. Trigger the skill naturally

Use a request that describes the job rather than naming the skill file:

```text
Turn this unfinished work into a portable handoff. Preserve the source files,
decisions, constraints, and smallest useful next action. Publish it privately
and read the result back.
```

The record must contain:

- objective and observable acceptance criteria;
- completed, active, blocked, and unverified state;
- decisions and reasons;
- source evidence and original artifacts;
- operating constraints;
- one bounded next action and its verification;
- the next owner;
- open review or unresolved questions.

## 5. Publish and read back

Expected MCP sequence:

```text
handover.search
handover.get                 # when a canonical record already exists
handover.create              # or handover.continue
handover.get
handover.read_artifact
```

Use a unique marker such as:

```text
HANDOFF-SKILL-TEST-2026-08-04-01
```

Pass only when:

- the returned author is the server-resolved publisher identity;
- the record is private unless the user explicitly requested otherwise;
- every required artifact can be retrieved byte-for-byte;
- the current revision and stable link are recorded;
- the returned next action matches the published record.

## 6. Resume from a fresh successor

Start a fresh session under the receiving identity. Give it only the stable
link or unique marker, not the original conversation.

Ask:

```text
Resume this handoff. Verify the current revision, read the source artifact,
state one reproducible fact from it, inspect open feedback, and continue the
bounded next action with an expected-revision check.
```

Expected MCP sequence:

```text
handover.whoami
handover.search              # or resolve the stable link
handover.get
handover.read_artifact
handover.annotations
handover.continue
handover.get
```

Pass only when the successor:

1. reports the distinct receiving identity;
2. retrieves the exact current revision;
3. reproduces one meaningful fact from the source artifact;
4. preserves decisions and constraints;
5. creates an attributable successor revision;
6. uses the prior revision as the expected revision;
7. reads the new canonical revision back.

## 7. Run negative tests

### Denied identity

The denied identity must not discover the title, summary, artifacts,
annotations, or counts through search or direct reads.

### Read-only identity

The read-only identity may inspect only explicitly granted context. Create,
continue, annotate, assign, archive, and delete must remain denied.

### Stale revision

Attempt a continuation using an obsolete expected revision. The server must
reject the write and require a fresh read before retrying.

### Revoked credential

Revoke a dedicated test credential, then repeat identity and context reads.
Both must fail without falling back to another actor.

## 8. Record the result

```markdown
# AI agent handoff skill test

- Skill source:
- Skill commit:
- Publisher identity:
- Receiver identity:
- Workspace:
- Published handoff:
- Publisher revision:
- Successor revision:
- Artifact verified:
- Natural-language trigger passed:
- Denied identity passed:
- Read-only identity passed:
- Stale revision passed:
- Revocation passed:
- Overall result: PASS | FAIL
- First failing checkpoint:
- Evidence:
```

Connectivity is not continuity. Mark the workflow `PASS` only when the
successor retrieves the exact evidence and creates a verified new revision
under a different authenticated identity.