| name | dev-handoff |
| description | Use when handing off Figma designs to developers as GitHub issues. Triggers include "hand off to dev", "create issues from Figma", "turn designs into tickets", "dev handoff", or when user shares a Figma URL and asks for GitHub issues to be created from it. |
Dev Handoff
Turn Figma design sections into GitHub issues for developer handoff. Reads the Figma hierarchy, extracts Developer Note components, and creates issues with the user's templates.
When to Use
- User shares a Figma URL and wants GitHub issues created from the designs
- User says "hand off", "create dev tickets", "turn designs into issues"
- User has a Figma section with multiple screens + dev notes ready for implementation
When NOT to Use
- User wants to implement the design (use
figma:figma-implement-design)
- User wants to organize/label Figma screens (use
design-superskills:design-organize)
- User wants to add dev notes to Figma (use
design-superskills:design-annotations)
- User just wants screenshots without issue creation
Quick Reference
| Step | What | Key Decision |
|---|
| 0 | Prerequisites | Figma MCP required, gh CLI optional (fallback to markdown files) |
| 1 | Gather user input | Figma URL, repo, issue templates, context |
| 2 | Read Figma structure | Get metadata, identify sections, skip WIP |
| 3 | Screenshot frames + read dev notes | Individual frames, not sections |
| 4 | Organize into issues | Group by section, detect issue type |
| 5 | Ask clarifying questions | Before creating any issues |
| 6 | Create GitHub issues | With Figma links |
| 7 | Add screenshots (optional) | Export, user drag-drops, then label via edit |
| 8 | Update PM tool (optional) | Update Asana/PM task with issue links if provided |
| 9 | Cleanup temp files | Offer to remove ./dev-handoff-issues/ and other handoff scratch |
STEP 0a — HARD-GATE: Create Tasks BEFORE Anything Else
**You MUST invoke TaskCreate with the full task list below before any substantive work in this skill — before checking `gh`, before reading Figma metadata, before asking the user any clarifying question.**
The only tool calls allowed before TaskCreate are the unavoidable bootstrap ones: reading this SKILL.md and loading TaskCreate's schema if deferred. Nothing else. Not "just a quick gh auth status," not "just a quick Figma metadata read to confirm the URL." Those are Step 0 and Step 2 — they come after the task list exists.
This applies even when this skill is chained after another skill (e.g., after design-organize or design-annotations). Chained invocations are the most common place where task setup gets skipped because the early steps "feel small" — they are not. If you skip this gate and only create tasks retroactively, the user cannot see structured progress and the skill's later HARD-GATEs lose their force.
If you cannot invoke TaskCreate for any reason, STOP and explain why to the user before proceeding.
Create these tasks in a single TaskCreate batch:
- "Step 0: Check prerequisites"
- "Step 1: Gather user input"
- "Step 2: Read Figma structure"
- "Step 3: Screenshot frames + read dev notes"
- "Step 4: Organize into issues"
- "Step 5: Ask clarifying questions — get user approval"
- "Step 6: Create GitHub issues"
- "Step 7: Add screenshots (optional)"
- "Step 8: Update PM tool (optional)"
- "Step 9: Cleanup temp files"
Mark each in_progress when starting and completed when done. Tasks ARE the early steps — do not treat the first few as too trivial to track.
Step 0: Prerequisites
Check before gathering input:
| Check | How | Fallback |
|---|
| Figma MCP | Check for mcp__figma__get_metadata in available tools | Cannot proceed without it — Figma MCP is required |
| gh CLI | gh auth status | If not available, offer the user a choice (see below) |
| FIGMA_TOKEN (optional) | [ -n "$FIGMA_TOKEN" ] && echo "set" || echo "not set" | Skip screenshot embedding, use Figma links only |
If gh CLI is missing or not authenticated
Ask the user which they prefer:
GitHub CLI isn't set up. Would you like to:
- Set it up now — I'll walk you through installing and authenticating
gh
- Skip it — I'll write the issues as markdown files you can copy-paste into GitHub
Option 1 — Setup gh CLI:
- If
gh is not installed: brew install gh (macOS) or point to cli.github.com
- If installed but not authenticated: ask user to run
! gh auth login in the prompt (the ! prefix runs it interactively in this session)
- After auth succeeds, re-check with
gh auth status and continue normally
Option 2 — Markdown output mode:
- Run the full workflow (Steps 1–6) as normal
- In Step 7, write each issue as a markdown file to
./dev-handoff-issues/
- Name files:
01-update-integration-layout.md, 02-zapier-integration.md, etc.
- Each file contains the full issue body ready to copy-paste into GitHub
Step 1: Gather User Input
Ask the user directly in conversation — do NOT use AskUserQuestion tool for this.
Pacing: Start with the 3 required fields. Then ask optional questions as follow-ups — don't dump everything at once.
Required — ask for each explicitly, never guess or assume:
- Figma URL — link to the parent section/page containing all design screens
- GitHub repo — ask the user to paste the repo link or
owner/repo. Never guess repo names — naming conventions vary and guessing wastes time
- Overall context — what is this feature/update about?
Optional (ask if not provided):
- Issue templates — does the team use specific templates? (Bug Report, Enhancement, New Feature, or custom)
- Asana/project management link — to include in issue headers and for optional PM updates in Step 8
- Sections to skip — any WIP or irrelevant sections?
- How to split issues — one per section? grouped? single mega-issue?
Issue templates: Ask the user: "Do you have specific GitHub issue templates you'd like me to follow, or should I use the default ones?" If they provide templates, use them exactly. If not, use the skill's built-in defaults in Step 4.
Step 2: Read Figma Structure
Use mcp__figma__get_metadata on the provided node to discover the hierarchy.
Parse the metadata to identify:
- Sections — top-level groupings (e.g., "Zapier", "Google Calendar", "Credit Use")
- Frames — individual screen designs within each section (e.g., "Not Connected", "Connected")
- Developer Note instances — components named "Developer Note" containing implementation context
- Labels/text nodes — screen labels at the section level (e.g., "Not Connected", "Connected > Error")
Skip sections whose names contain "(WIP)" or that the user explicitly excluded.
Present the discovered structure to the user for confirmation before proceeding:
Found N sections (skipping M WIP):
1. Section Name — X screens, Y dev notes
2. Section Name — X screens, Y dev notes
...
Step 3: Screenshot Frames + Read Dev Notes
For each non-WIP section:
- Get screenshots of individual frames using
mcp__figma__get_screenshot — capture each screen state separately (e.g., "Not Connected", "Connected", "Error"), NOT the entire section.
- Get screenshots of Developer Note instances to read their content — these contain implementation details, edge cases, and behavioral specs written by the designer.
Record all information per section:
- Frame name, node ID, and visual content
- Dev note content (transcribe from screenshot)
- Screen labels from text nodes
Step 4: Organize Into Issues
Based on user preferences from Step 1, organize the captured data into issues.
Templates, Detection & Extraction
If the user provided their own templates, use them exactly. Map the extracted information into their template fields. Do not improvise.
If using the skill's defaults, read issue-templates.md in this skill directory. It contains:
- 3 templates (Bug Report, Enhancement, New Feature)
- Issue type detection logic with keywords
- Information extraction rules for each template field
- Title generation guidelines
When the issue type is unclear, default to New Feature for new integrations/features or Enhancement for updates to existing functionality.
Figma Links
Always link to the specific subsection in Figma, not the parent section. Convert node IDs to URL format: node-id=XXXX-YYYY (replace : with -).
Step 5: Ask Clarifying Questions
**You MUST get explicit user approval before proceeding to Step 6.** Do not create any issues until the user says the plan looks good. If you catch yourself about to run `gh issue create` without having asked questions and received approval — STOP.
Ask questions as natural conversation, NOT via AskUserQuestion tool.
Part A: Present the plan in template format
Show each planned issue using the exact template format from Step 4 — same headers, same structure. The preview should look identical to what will be created. Include:
- How many issues
- Title and type of each
- Which screens map to which issue
Part B: Flag ambiguities (substance scan — NOT logistics)
**Do not proceed to Part C until you have produced an explicit red-flag scan output.** This is a substance scan of the dev notes, NOT logistics questions about Asana links / titles / screenshot hosts. Logistics ≠ substance — do not conflate them.
Scan every dev note for these red flags and produce explicit output of the form:
Red-flag scan:
- [dev note quote] → open question: ...
- [dev note quote] → open question: ...
(or: "No red flags found" with one-sentence reasoning per category)
Categories to scan:
- "Consult X" / "Check with X" references — who decides?
- "Placeholder" / "WIP" / "TBD" / "or similar" labels — include or skip?
- Open decisions — provider choices, URL fallbacks ("if there is none…"), credit allotments, scope boundaries ("we can look into having this on all pages")
- Missing edge cases — error states mentioned but not designed, empty states, fallback behavior when stored state is missing
- Dismissal/trigger conditions — ambiguous triggers like "any successful email" — does that include adjacent flows?
- Dependencies between issues — does one block another?
Quote the dev-note text verbatim for each finding so the user can confirm context.
Part C: Get approval
Ask: "Does this plan look good, or would you like to adjust anything?"
Iterate until the user approves. Only then proceed to Step 6.
Step 6: Create GitHub Issues
If gh CLI is available:
- Create each issue with
gh issue create --repo <repo> --title "<title>" --body "$(cat <<'EOF' ... EOF)". Use HEREDOC to preserve markdown formatting.
- Include Figma subsection links in the header table and Asana/PM link if provided.
- Report all created issue URLs in a summary table.
After each issue is created, fetch it with gh issue view and verify the body rendered correctly (tables, links, formatting). Fix any issues with gh issue edit --body-file.
If gh CLI is NOT available (markdown output mode):
Write markdown files as described in Step 0.
Step 7: Add Screenshots (Optional)
After issues are created, ask: "Would you like to add screenshots to the issues?"
If no, done. If yes, check for FIGMA_TOKEN:
- Not set: Tell the user they need a Figma Personal Access Token. Skip screenshots.
- Set: Proceed below.
Screenshot flow (one issue at a time):
-
Export via Figma REST API — batch all frames:
curl -s "https://api.figma.com/v1/images/<fileKey>?ids=<node1>,<node2>,...&format=png&scale=2" \
-H "X-Figma-Token: <token>"
-
Download PNGs to ./dev-handoff-issues/screenshots/, organized per issue:
screenshots/
01-layout/
disabled-state.png
gmaps-not-connected.png
02-zapier/
not-connected.png
connected.png
-
For each issue:
- Open the screenshot folder:
open ./dev-handoff-issues/screenshots/01-layout/
- Tell the user: "Drag-drop these images into [issue link] and save."
- Wait for the user to say done.
- Fetch the updated body with
gh issue view, then gh issue edit --body-file to label each screenshot under ### State Name subheadings in the ## Screenshots section.
Step 8: Update Project Management Tool (Optional)
If the user provided an Asana/PM link in Step 1, offer to update it with the GitHub issue links and a summary. If Asana MCP tools are available, use them. Otherwise, output the update text for the user to paste manually.
Also ask: "Would you like me to create a review subtask in Asana for reviewing the designs and GitHub issues?" If yes, create a subtask on the parent task with a summary of what was created and links to the GitHub issues and Figma section.
Step 9: Cleanup Temp Files
Once issues are created and (optionally) the PM tool is updated, list every scratch file/dir this run produced and offer to remove them. Common candidates:
./dev-handoff-issues/ (markdown drafts in markdown-output mode)./dev-handoff-issues/screenshots/ (downloaded PNGs from Figma export)- Any
/tmp/dev-handoff-* files (issue body drafts, scan outputs, etc.)
Ask the user: "I created the following temp files during this handoff: [list paths]. Want me to delete them now, or keep them for reference?"
Only delete after explicit user confirmation. Use rm for files and rm -rf for directories — and only on paths you actually created in this run. Do not touch files you didn't create.
Common Mistakes
| Mistake | Fix |
|---|
| Skipping task setup because early steps look trivial | Tasks ARE the early steps; user can't see hidden progress. Always create the full list first. |
| Skipping task setup when chained from another skill | Chained invocations are the most common skip-point. Step 0a applies regardless of how the skill was invoked. |
| Conflating logistics questions with the Step 5 Part B substance scan | Asana link / title / hosting questions are not red-flag findings. Both must happen. |
Using sed to modify issue bodies with markdown tables | Pipe characters in tables break sed — use Python for string replacement |
| Embedding screenshots as comments instead of in the issue body | Edit the issue body directly with gh issue edit --body-file |
Embedding Handoff/HTML-wrapper URLs as <img src> in GitHub issue bodies | GitHub's Camo proxy fetches the URL and renders broken because Handoff returns HTML, not raw image bytes. Use drag-drop into user-attachments.githubusercontent.com or a host that returns content-type: image/*. Verify with curl -I <url>. |
Guessing which user-attachments/assets/<uuid> URL is which screenshot | Those URLs 404 to unauthenticated curl. Ask the user to upload one screenshot at a time and label inline, OR confirm upload order against the numbered state list before labeling. |
| Drafting from stale dev notes after the user edited them mid-flow | If dev notes were empty when this skill started, or the user says they updated them, re-run the dev-note read before drafting. |
| Leaking FIGMA_TOKEN in env check output | Never echo the token — use the safe check in Step 0 |
| Screenshotting entire sections instead of individual frames | Sections are too small to read — always use individual frame node IDs |
| Forgetting to transcribe dev notes | Dev notes are the primary spec — screenshots alone miss edge cases |
Forgetting to clean up ./dev-handoff-issues/ and other scratch | Step 9 exists for this — offer cleanup before declaring done. |
Notes
- Cross-reference related issues — if the user mentions something is handled in a separate issue, link to it.
