Install Agent Skills in Claude Code, Codex, Cursor, and Gemini CLI

What is the shortest cross-agent install path?

Inspect the available skills first, then target one host explicitly. Project installation is the safest default because the skill remains visible with the repository and can be reviewed by the team. Add --global only when the workflow should be available in every project for one user.

# Inspect the collection without installing it
npx skills add 44-pixels/handover-mcp --list

# Install one skill into one project and host
npx skills add 44-pixels/handover-mcp   --skill handover-publish   --agent codex   --copy   --yes

Which host name and verification step should I use?

The installer supports all four hosts, but host-native discovery is not identical. Claude Code exposes skills through its skills menu and direct /skill-name invocation. Codex exposes /skills and $skill-name. Gemini CLI exposes /skills list and /skills reload. For Cursor, verify the installer record with the skills CLI and then run a natural-language trigger test because its public documentation does not currently describe the same native skills menu.

• Claude Code: use --agent claude-code, check /skills, then invoke /handover-publish or ask a matching request.
• Codex: use --agent codex, check /skills, then mention $handover-publish or ask a matching request.
• Cursor: use --agent cursor, run npx skills list --agent cursor, then ask a matching request and inspect the resulting behavior.
• Gemini CLI: use --agent gemini-cli, check /skills list, and use /skills reload after changing an installed skill.
• All hosts: inspect the installed SKILL.md before activation because skills can influence tool use and may include scripts.

Where does the installer place the skill?

Project installs use the location each host discovers. In current clean-install tests, Claude Code received .claude/skills/handover-publish while Codex, Cursor, and Gemini CLI received .agents/skills/handover-publish. Native host documentation remains the authority for manual installation paths, precedence, reload behavior, and enterprise controls.

# Verify the installer sees the skill for each target
npx skills list --agent claude-code --json
npx skills list --agent codex --json
npx skills list --agent cursor --json
npx skills list --agent gemini-cli --json

How do I connect the skill to Handover MCP?

A Handover skill teaches the workflow but does not contain credentials or replace the runtime. Connect each host to https://handover.sh/api/mcp using browser OAuth for a person or a scoped service credential for an unattended agent. Then call handover.whoami before the first protected action and confirm the returned person or service agent, company, workspace, role, and scopes.

• Use a separate named service identity for each unattended agent.
• Keep credentials in the host's secret store or environment, never in SKILL.md.
• Derive author, company, workspace, and access from the authenticated connection.
• Stop on denied access instead of retrying with another identity.
• Keep new context private unless a person explicitly selects broader sharing.

How do I prove the skill actually works?

Run a behavioral test, not only a filesystem check. Start a fresh session, request the skill's outcome in ordinary language, confirm the expected skill activates, verify identity through MCP, publish a uniquely marked handover, and read the exact revision and artifact back. A pass requires the correct authenticated author, workspace, files, access, and canonical link.

Request:
"Publish the current objective, decisions, evidence, and next action
as a private handover. Read it back and return the canonical link."

Expected proof:
1. handover.whoami reports the intended identity
2. one new handover contains the unique test marker
3. the artifact is readable from the returned revision
4. history attributes the revision to that identity
5. another authorized host can retrieve it without the original chat

What should I test when using the same skill in another host?

Do not transfer the first host's transcript. Give the second host only the canonical link or a search marker, then ask it to retrieve the current revision, state the next action, and continue the record with optimistic concurrency. This proves the durable Handover record, rather than hidden local memory, carries the work across models.

• The second host finds the same canonical handover.
• It reads the exact current revision and all required artifacts.
• Open review comments and assignments remain visible.
• A continuation creates a new immutable revision.
• Both human or service identities remain separately attributable.
• Revoking one credential removes only that principal's access.

What commonly causes an installed skill to appear broken?

Most failures belong to one of three layers: installation, activation, or runtime. First confirm the host-specific skill listing and installed path. Next test whether the skill description matches the request and invoke it explicitly when the host supports that. Finally verify MCP identity and scopes. Reinstalling a skill will not fix an expired credential, denied workspace, or missing MCP connection.

• Installed but not listed: reload or restart the host and check the project root.
• Listed but not activated: improve the description or invoke the skill explicitly.
• Activated but no Handover tools: connect MCP and inspect the host's server status.
• Tools available but writes denied: check handover.whoami, role, workspace, and scopes.
• Write reported as complete but no record exists: require a final read-back before claiming success.