# Cross-host Agent Skill installation and verification

Install one inspectable Handover skill into Claude Code, Codex, Cursor, or
Gemini CLI. Then prove that the host discovers it and that its authenticated
MCP runtime completes the workflow.

## 1. Inspect before installing

```bash
npx skills add 44-pixels/handover-mcp --list
```

Review the selected `SKILL.md` and any referenced scripts, assets, or supporting
files. Skills can influence tool use and run with the agent's permissions.

## 2. Install one project skill

Replace `<host>` with `claude-code`, `codex`, `cursor`, or `gemini-cli`.

```bash
npx skills add 44-pixels/handover-mcp \
  --skill handover-publish \
  --agent <host> \
  --copy \
  --yes
```

Project scope is the default. It keeps the workflow visible with the repository.
Use `--global` only when the skill should apply to every project for one user.

## 3. Verify installation

```bash
npx skills list --agent <host> --json
```

Expected project paths from clean installation tests:

| Host | Installer target | Host-native check |
| --- | --- | --- |
| Claude Code | `.claude/skills/handover-publish` | Open `/skills`, then invoke `/handover-publish` |
| Codex | `.agents/skills/handover-publish` | Open `/skills`, then mention `$handover-publish` |
| Cursor | `.agents/skills/handover-publish` | Use `npx skills list --agent cursor`, then run the trigger test |
| Gemini CLI | `.agents/skills/handover-publish` | Run `/skills list`; use `/skills reload` after changes |

If a skill does not appear, confirm the project root and installed path, then
reload or restart the host. Do not debug MCP until local discovery passes.

## 4. Connect the runtime

Connect the host to:

```text
https://handover.sh/api/mcp
```

Use browser OAuth for a person or a separately named, scoped service credential
for an unattended agent. Never put the credential in `SKILL.md` or a committed
configuration file.

Connection guide:
https://handover.sh/install?utm_source=agent&utm_medium=raw_asset&utm_campaign=cross_host_skills

## 5. Verify identity before a protected action

Ask the host to call:

```text
handover.whoami
```

Confirm:

- [ ] Intended human or service-agent identity
- [ ] Intended company or personal workspace
- [ ] Intended space
- [ ] Expected role and scopes
- [ ] No author, company, role, or access value came from prompt text

Stop if any identity or scope is unexpected.

## 6. Run the behavioral trigger test

Start a fresh session and ask:

```text
Publish the current objective, decisions, evidence, constraints, and next
action as a private handover. Include the marker CROSS-HOST-<date>-<host>.
Read the result back and return its canonical link.
```

Pass criteria:

- [ ] The expected skill activates from the request or explicit invocation.
- [ ] The workflow calls `handover.whoami` before its first protected action.
- [ ] Exactly one new handover contains the unique marker.
- [ ] The expected files exist in the returned revision.
- [ ] A final read proves the artifact is retrievable.
- [ ] History attributes the revision to the authenticated identity.
- [ ] Sharing remains private unless a person explicitly changed it.

## 7. Prove cross-host continuation

Open a different authorized host. Do not provide the first host's transcript.
Give it only the canonical link or marker and ask:

```text
Retrieve this handover, read its current revision and open feedback, state the
next action, continue it with one bounded update, and verify the new revision.
```

Pass criteria:

- [ ] The second host finds the same canonical record.
- [ ] It reads the exact current revision and required artifacts.
- [ ] It sees open annotations and assignments.
- [ ] It creates a new immutable revision with optimistic concurrency.
- [ ] Both actors remain separately attributable.

## 8. Test the denied and revoked paths

1. Connect an identity without access to the target.
2. Confirm search does not reveal the private handover.
3. Confirm direct read or write remains denied.
4. Confirm the skill stops rather than switching identities.
5. Revoke one test credential.
6. Confirm that identity immediately loses access without affecting others.

## Troubleshooting by layer

| Symptom | Check |
| --- | --- |
| Skill not listed | Installer target, project root, path, reload or restart |
| Skill listed but not used | Description match or explicit host invocation |
| Skill active but no tools | MCP connection and host server status |
| Tools present but denied | `handover.whoami`, workspace, role, and scopes |
| Agent claims success but nothing exists | Require final `handover.get` and artifact read |

## Working resources

- Skills catalog: https://skills.handover.sh/?utm_source=agent&utm_medium=raw_asset&utm_campaign=cross_host_skills
- Raw skill sources: https://github.com/44-pixels/handover-mcp/tree/main/skills
- MCP connection: https://handover.sh/install
- Skills and MCP guide: https://handover.sh/guides/agent-skills-and-mcp
- Official MCP Registry: https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.handover%2Fhandover