--- name: figma-comments-waiting-on-you description: "Each weekday morning: open Figma comment threads that mention you or that you are part of, where the last word is not yours, oldest first. Use when the user asks for this, or when it runs on a schedule." --- # Figma comments waiting on you Each weekday morning: open Figma comment threads that mention you or that you are part of, where the last word is not yours, oldest first. Figma notifications arrive by email and in the bell menu, mixed with every reaction and resolved thread, and they disappear once read. A question from engineering on Monday about a spacing value is easy to lose by Wednesday, and the developer builds their best guess. The agent reads the comments on the files you work in, rebuilds the threads, and keeps the unresolved ones that mention you or that you replied to, where someone else spoke last. You get them oldest first, each with a link to the exact frame, and can ask for draft replies to check before anything is posted. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - A Figma personal access token with `file_comments:read`, `current_user:read` and, to list a folder's files, `folders:read` (the old `projects:read` scope is deprecated), in `FIGMA_TOKEN`; add `file_comments:write` only if you want replies posted. - This skill uses the REST API for comments; the Figma MCP server is built for design context, not comment threads. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Pick the files** (Figma): Use the file keys in the prompt, or list a folder (Figma's current name for a project) with `GET /v1/projects/:project_id/files` and keep files whose `last_modified` is within 30 days. Find your own `id` and `handle` with `GET /v1/me`. 2. **Read the comments** (Figma): For each file, `GET /v1/files/:key/comments?as_md=true`. Build threads from `parent_id` (replies point at the root comment) and drop threads whose root has `resolved_at` set. 3. **Keep what waits on you**: Keep a thread when its messages mention your handle, or you started or replied to it, and the newest message is from someone else. Note the waiting time from that message's `created_at` and the frame from `client_meta.node_id`. 4. **Rank and ask**: Oldest first, questions (a message ending in "?") ahead of comments. Link each thread to `https://www.figma.com/design/?node-id=`, post the list and ask whether to draft replies. 5. **Post only what you approve** (Figma): Drafts stay in the card. Only after you approve a reply does the agent post it with `POST /v1/files/:key/comments` and `comment_id` set to the thread root, which needs the `file_comments:write` scope. ## Route B: the browser ### What you need - Signed in to Figma with an account that can view each file (viewer is enough to read comments; commenter or editor to reply). Choose the right team or organization in the file browser first. If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://www.figma.com/files/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Start from Notifications**: In the file browser, open **Notifications** in the left sidebar (the bell). Mentions and replies from the last 30 days are listed newest first; note every file that appears, since those are the threads most likely to be waiting on you. 2. **Open each file's comments**: Open the file and press `C` or click the comment tool; the comments sidebar lists threads. Turn on **Only your threads**, leave **Show resolved comments** off, and sort by date so the oldest come first. 3. **Keep what waits on you**: Open each thread and keep it when the newest message is from someone else. Note who wrote last, how long ago (the timestamp on the message), and whether it is a question. Clicking the thread selects the frame; copy the link from **Share** > **Copy link** or the address bar, which carries `node-id`. 4. **Rank and ask**: List the threads oldest first, questions ahead of comments, with file, frame, who wrote last, waiting time and the message shortened. Ask whether to draft replies; type nothing into a comment box unless a specific reply is approved. Note: Figma loads comments per file, so the run is as long as the number of files. The Notifications list drops items after 30 days and clears when read, so the comments sidebar, not the bell, is the source of truth. ## The report - **Waiting on you**: count, and the oldest one's age. - One row per thread: file, frame, who wrote last, how long ago, the message shortened. - **Questions** marked, since they block someone. - The ask: draft replies, or leave them. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "figma-comments-waiting-on-you/", "item_key": "figma-comments-waiting-on-you", "project": "Acme Design", "source": "Figma comments waiting on you skill", "kind": "action", "title": "6 Figma comments waiting on you", "summary": "**6** open threads in 3 files wait on your reply. The oldest is a question from Tom on **Checkout v3**, unanswered for **3 days**.", "action": { "request": "Want me to draft replies for you to check before anything is posted?", "options": [ "Draft replies for all 6", "Only the questions", "Open the oldest", "Not today" ] }, "widget": { "type": "Table", "props": { "columns": [ "File and frame", "From", "Waiting", "Message" ], "rows": [ [ "Checkout v3 / Payment step", "Tom", "3 days", "Is the error state 12 or 16 px from the field?" ], [ "Checkout v3 / Order summary", "Priya", "2 days", "@you can we drop the coupon row on mobile?" ], [ "Design system / Button", "Lena", "2 days", "Disabled tertiary fails contrast, ok to darken?" ], [ "Onboarding / Step 2", "Sam", "1 day", "Copy here needs legal review, flagging" ], [ "Onboarding / Empty state", "Tom", "6 h", "Which illustration is final?" ], [ "Design system / Toast", "Priya", "2 h", "Thanks, looks good. One question on timing?" ] ] } } } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. ## Run it on a schedule Suggested: Weekdays at 9:00 (`0 9 * * 1-5`). From cron, with the agent signed in on that machine: ```bash 0 9 * * 1-5 claude -p "Run the figma-comments-waiting-on-you skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/figma-comments-waiting-on-you#schedule Source: https://briefkin.dev/skills/figma-comments-waiting-on-you