How to use the Artifact Handoff agent skill (handoff)

What the handoff skill makes the agent do

An Open Design run is not finished when the artifact exists. It is finished when the artifact reaches the surface you will keep iterating on. The handoff skill is the step that pushes an accepted artifact somewhere else. It is the counterpart to the diff-review step, which is where you accept or partially accept the output.

The skill takes two inputs: the accepted artifact set and an export target. It supports seven surfaces: cli, desktop, web, docker, github, figma and code-agent. Each surface has a typical follow-on action, described below. Every push is written to the artifact manifest as a new row, so the distribution history is append-only and earlier entries are never replaced.

• cli: you run od files read against the project; no extra push is needed.
• desktop: the project opens in the Open Design desktop app.
• web: the artifact is published to the public marketplace through an od:// deep link.
• docker: the artifact is wrapped into a self-contained container.
• github: a pull request is opened with od plugin publish --to <catalog>.
• figma: the output is round-tripped back into the figma-migration source file.
• code-agent: the project is handed to Cursor, Claude Code or Codex working on the project directory.

Install the handoff skill

Download the handoff skill as a ZIP from the directory page. Then choose one of two routes.

For a personal install, unzip the file into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

The package contains two files: open-design.json and SKILL.md. SKILL.md holds the instructions the agent reads.

• Personal: ~/.claude/skills/
• Per project: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What you need before it works

The skill only works inside an Open Design environment. The source describes it as an Open Design daemon and project environment, with the handoff runner in apps/daemon. If you have not set up the daemon and a project, install the skill later; it will have nothing to act on.

Some surfaces need more. The Open Design CLI (od) is required for the cli, github and file-read follow-ons. Docker is required for the docker surface. Figma access is required for the figma surface. GitHub credentials are needed for the github surface. The source does not state the GitHub requirement directly; it is inferred from opening a pull request.

• Open Design daemon and project environment (handoff runner in apps/daemon)
• Open Design CLI (od) for cli, github and file-read follow-ons
• Docker for the docker surface
• Figma access for the figma surface
• GitHub credentials for the github surface (inferred, not stated in the source)

Trigger the skill with natural requests

You do not need a special command. Ask in plain language, naming the artifact and the place you want it to go. The skill is meant for the moment after you have accepted an output, so make the acceptance explicit first.

Name the surface in your request. If you do not name one, the agent should work from the targets you intended. The skill is designed not to push to surfaces outside your intent list.

• "I accept this design. Open it in the desktop app."
• "Hand this accepted artifact to Cursor so I can keep editing the code."
• "Push the accepted plugin to a GitHub pull request for the catalog."
• "Round-trip this output back to my Figma source file."

Safety notes: scripts and network

The skill runs scripts and uses the network. Pushes to the web marketplace or to GitHub expose content to other people. The source says the push is hard to undo. Review an artifact before sending it to a public surface, and do not send sensitive or unreviewed work there.

The skill also has rules against certain actions. It must not push to a surface that was not on your intent list. It must not change sourcePluginSnapshotId, which is immutable; the export trail is additive only. It must not treat a Figma-sourced artifact as a no-op, because round-trip is the purpose of that scenario.

• Public surfaces (web, github) are hard to reverse; review first.
• Only surfaces on your intent list should receive the artifact.
• sourcePluginSnapshotId must not be changed.

Tips for reliable handoffs

Accept or partially accept the artifact in the review step before asking for a handoff, since the skill expects an accepted set. Keep one clear export target per request so the manifest row is easy to read later. Check the manifest history after a push to confirm the entry was appended.

The handoff is considered complete when at least one export target matches your intent, or when you explicitly skip it through the confirmation step.

• Accept or partially accept first; the skill expects an accepted set.
• Ask for one target at a time.
• Check the manifest's export history after each push.