handoff
Hands finished sections to engineering. Runs /fig:lint as the gate, lets the person pick which passing sections go, hands over the section links, and writes one line into the task doc where a tracker
SKILL.mdplugins/fig/skills/handoff/SKILL.md
GitHubfig:handoff — hand finished sections to engineering
Part of a plugin. The scripts this skill runs ship beside it under ${CLAUDE_PLUGIN_ROOT}. If that path does not resolve, this file was installed on its own — stop and say the plugin itself is needed (claude plugin install fig@byjunyoung), rather than improvising what the scripts do.
The moment a feature's screens, states and arrows are drawn, somebody has to say "this is ready" where engineering looks. The signal is the section links, pinned to a named version of the file, written into the task doc engineering builds from — and only for sections that pass the audit.
The audit decides, the person chooses, the skill hands over. /fig:lint says which sections
are fit to hand over; the person says which of those go now; this skill pins the version, hands
over the links, and leaves one line in the task doc. It draws nothing, moves nothing, renames
nothing.
Prerequisites: load figma:figma-use before calling use_figma. Every write goes through
preview → go.
Dev Mode status (Ready for dev, Completed) is not part of this skill, and is never offered. use_figma rejects the getter and the setter alike — "devStatus" is not a supported API — on an Edit seat as much as a View one (checked on a live file, 2026-08-31), and Figma's REST API reads the status but has no endpoint that sets it. Kept as an option, it came back as "I can mark these ready for dev" run after run, a step the skill could not take. It was removed outright in 3.26.0. Do not propose it, and do not list it as something left to do; where the person wants the status, it is theirs to set in Dev Mode.
When to invoke
- A feature's screens, states and arrows are drawn and it is time to hand them to engineering
- Something handed over was revised and needs handing over again
- "Which of these sections is actually ready?" — the gate answers that even when nothing is marked
When NOT to invoke
- Laying the skeleton and stubbing missing states →
/fig:prep - Checking rules only →
/fig:lint - Looking at what changed between two versions of a design → Dev Mode's Compare changes in Figma — it needs a Dev Mode seat, and compares a frame with its own version history, not two separate frames
- Filing the task as a ticket →
/pm:task publish - After release, bringing canonical current →
/fig:sync
Inputs
page(required): the page the sections are onsections(optional): names or numbers. Omitted, every section on the page that passes the gate is a candidatetask(optional): where the line goes — a Notion page url, a GitHub issue, or a task file's path
Where the rules come from
python3 ${CLAUDE_PLUGIN_ROOT}/_common/scripts/lib/resolve-config.py --js <fileKey>
handoff.version — whether a handover pins a named version, and how that version is named, matched and written out. task_tracker.ui_section_heading — the heading the one line goes under in a Notion or GitHub doc; in pm's markdown records pm's task.design_heading decides it, and borrow-pm.py task returns the heading to use.
Where the line goes is not read off task_tracker.type here. Ask:
python3 ${CLAUDE_PLUGIN_ROOT}/_common/scripts/lib/borrow-pm.py task <fileKey>
It prints {"action", "dir", "heading", "script", "adapter", "note"}, and action decides:
| action | What this skill does |
|---|---|
write |
Write the line into a markdown task file (below). {script} is pm's markdown-tracker.py, {dir} the task folder, {heading} the heading. Show note beside the written line where there is one |
print |
Put the line in the response, with note beside it where there is one. Nothing is written |
notion |
Insert the line into the task page's {heading} section, after the last hand-over line already there — or, where there is none, directly after the heading and whatever block opens the section (below) |
github |
Insert the line into that section of the issue body, after the last hand-over line already there, or beneath the heading where there is none; where the body has no such section, add it as a comment (below) |
- Exit 3 — fig's own config has a
task_tracker.refwithout itstask_tracker.type. Stop, and name the setting the message names - Exit 1 — say what it printed and stop. Do not fall back to
print actionalways decides; thetaskinput never overrides it. Underprint, nothing is written even when a file path was given — show the line and the note. Undernotionorgithub, ataskurl names the page or issue to update, as before. When the input's kind disagrees with the action (a GitHub issue while the action iswrite, say), the action decides and the skill says so- The task file (
writeonly) is thetaskinput;Readthe path before the preview, and a missing file stops there and says so. Without one, runpython3 {script} list --dir {dir}and pick: one record whosetitleclearly matches the feature → use it, and say which; otherwise ask - No
taskinput undernotionorgithub— search the trackertask_tracker.refnames for the task, read-only, after step 2 (the section choice) and before step 3 — the terms need the sections chosen — and before any preview: Notion,notion-fetchthe database first (notion-searchscopes by a data-source URL, which the fetch returns), thennotion-searchscoped to it; GitHub,search_issuesin that repo. Wheretask_tracker.refisnullthe search would be unscoped, so it does not run: always ask. The terms are the file's name and the names of the sections chosen. Exactly one hit → name it in the preview and carry on to the usual preview → go. None, or several → list what was found and ask which; it never picks. Where nothing is found and nothing is chosen, print the line and say there was no page or issue to write into listprints nothing — the folder is missing or empty, so no task exists yet. Handle it asprint, with the note "no task file yet —/pm:task draftmakes one, and the next handoff writes into it"
Procedure
1. The gate — /fig:lint on the page (zero writes)
Call /fig:lint (via the Skill tool) on the page. No audit lives here; the verdict is lint's alone, and it is the only thing that makes a section a candidate.
The gate reads blocking only (lint, "Severity"). A section is not held back by how it is filed — it is held back by what engineering would build wrong.
- A section with zero blocking is a candidate, warnings and all
- Warnings never remove a candidate. They ride along to the step 4 preview and into the report, so the handover happens knowing what is still untidy
- A section carrying any blocking is out, with those reasons beside its name. It is not offered, and if the person names it anyway, say why it cannot go and leave it out — "hand it over now and fix it later" is what the gate is meant to prevent
2. Choose
Show the candidates as a table — name and warnings still open (— where none) — and ask which go: all, or some. One question. Sections held back by blocking appear below the table with those reasons, so the person sees why they are not offered.
3. Pin the version — preview → go → save → read back
Only where handoff.version.enabled. With it off, skip to step 4 and the doc line carries the links and a date alone.
This is the first write, so it has its own preview. Ask which release this handover belongs to, settle the name handoff.version.name produces, and show that name as the one entry about to be added to the file's version history. After the go, follow ${CLAUDE_PLUGIN_ROOT}/_common/version-pin.md from its save step (step 3) — the preview and go are already done here — to save it and read it back. Nothing is saved before the go.
Every section link from here on carries &version-id={version id}, and the date in handoff.version.ref is the version's own.
4. Preview the doc line → go → write
The second write has its own preview, so a version that went in is never followed by a doc line nobody has seen. One preview with everything this step will do:
- the sections going over
- the section links:
https://figma.com/design/{fileKey}/?node-id={section id with : replaced by -}— the same links/fig:prephands over, because engineering opens sections, not frames - where a version was pinned: the label, its date, and the
&version-id=every link now carries - where
actionis notprint: the one line that goes into the task doc — the links, "handed over {date}, {n} sections", and the pinned version written ashandoff.version.ref— under{heading}: after the last hand-over line already there, or, where there is none, directly after the heading and whatever block opens the section, so the lines read oldest to newest, the way markdown'sappend-underleaves them. Forwritethe preview names the file and shows the line under the heading; fornotionit names the page and the line or heading it goes after, and forgithubthe issue and whether it is the body or a comment. That line is what/pm:task publishreads to fill a ticket's referenced-version row, so the label and the date go in as they came back from the file, not as they were typed
Then the go. After it, the task-doc line, where action writes one — nothing in the Figma file. For write, with the heading and the line passed single-quoted and every ' inside them written as '\'' — a ", $ or backtick in a version label then reaches the file as it is, rather than ending the argument or being expanded by the shell:
python3 {script} append-under --path {file} --heading '{heading}' --line '{line}'
It adds the heading when it is missing, and a second run gives one heading. Exit 4 means the file named in the preview is missing — stop and say so. Under print the line goes in the response instead.
For notion and github the heading is task_tracker.ui_section_heading, or the default borrow-pm.py task returned, and the task input names the page or issue:
| action | Target | Method |
|---|---|---|
notion |
the ui_section_heading section of the task page — after the last hand-over line already there; where there is none, directly after the heading and whatever block opens the section (such as a callout) |
notion-update-page with update_content, taking that last hand-over line as old_str — or, in a section with none yet, the heading plus whatever opening block sits right under it — and inserting the line after it. old_str never relies on a particular block being there. Never replace the whole body |
github |
the task issue | If the body has that section, insert the line after the last hand-over line in it (beneath the heading where there is none) with issue_write — send the whole edited body back, changing nothing else. If it does not, add the line as a comment with add_issue_comment |
- Search for the target section first. Where the heading is missing or named differently, confirm where the line should go. Where earlier hand-over lines sit under it, do not overwrite — the new line goes after the last hand-over line, so they read oldest to newest
- Never replace the whole body of a page or an issue, and never touch a section other than that one
- If no task was found, say so and print the line instead
5. Read back
Re-read the task doc where the line went and confirm it landed under the heading, with the pinned links as written. For a file, Read it: the line sits under the heading, once. A mismatch is reported, not retried.
Report
[handed over]
· 01. Account - Login https://figma.com/design/…&version-id=…
· 02. Account - Signup https://figma.com/design/…&version-id=…
[not offered]
· 03. Account - Recovery blocking — 2 frames outside any section · Recovery-Error missing
[handed over with warnings open]
· 02. Account - Signup warning — section number 02 disagrees with its place on canvas
[version] {label} · {date} · version-id {id} (or "not pinned — handoff.version is off")
[task doc] {the file or the page (with `note` after it where there is one), "printed — {note}", or "no tracker configured"}
Constraints
- The writes are the version entry (through the web app) and the one doc line, each behind its own preview and go, in that order. Frames, sections, names, positions and Dev Mode status are never touched
- A section carrying a lint blocking is never handed over, whoever asks. A warning alone never withholds one
- Never hand over unpinned where
handoff.version.enabled. An unpinned handover reads as pinned to whoever gets it, and that is worse than stopping - Never save a version without the go, rename one, or write a date that is not the version's own
- Never offer to set Ready for dev or Completed, and never list it as remaining work