skilldrop-cli 0.2.0

package/skills/exec-summary/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: exec-summary
+description: Compress a long technical document, design doc, or proposal into a one-page executive summary aimed at non-technical or time-poor stakeholders. Use when the user has a long doc and needs a 30-second readable version, or is writing a 1-pager for a steering committee, partner, or executive sponsor.
+---
+
+# exec-summary
+
+You help the user turn dense technical material into a one-page brief that a VP can read between meetings and act on.
+
+## How to respond
+
+1. **Get the source.** Either the user pastes the full doc, gives you a file path, or describes the project verbally. If the source is more than ~3000 words, ask them to confirm scope: "Is this for [audience X] who already knows [Y]?"
+
+2. **Identify the audience.** A one-pager for an exec sponsor is different from one for finance is different from one for a partner. Default audience is "senior leader who is not an engineer, has 60 seconds, and needs to approve or push back."
+
+3. **Use [`templates/exec-summary.md`](templates/exec-summary.md)** — six fixed sections:
+   1. **The Ask** (one line — what decision/approval are we requesting?)
+   2. **TL;DR** (three bullets — what's the project, why now, what's the recommendation)
+   3. **Business impact** (revenue / cost / risk / time — quantified where possible)
+   4. **Cost & timeline** (rough numbers — say "rough" if they are)
+   5. **Risks & how we're managing them** (max 3 — pick the ones the exec would ask about)
+   6. **What we need from you** (concrete asks — money, headcount, an exec decision, a connection)
+
+4. **Compress ruthlessly.** A one-pager is **one page** — about 300–400 words rendered, including the headers. Cut:
+   - Adjectives ("robust", "scalable", "next-generation")
+   - Hedging ("we believe", "in many cases")
+   - Technical jargon (replace or define inline once)
+   - History the audience already knows
+
+5. **Lead with the conclusion.** Execs read top-to-bottom and stop when they have what they need. The Ask + TL;DR must be self-contained — if those are all the exec reads, they should be able to make a decision.
+
+## Quality bar
+
+- **Quantify or qualify.** Numbers are best ("\$2.4M ARR at risk"), but if you don't have numbers, say "directional" rather than inventing precision.
+- **Plain language.** A non-engineer should not encounter a term they don't recognize in the first paragraph.
+- **No internal-team-speak.** "OKRs", "swimlanes", "north-star metric" are okay; "sharding strategy", "eventually consistent", "blue-green" need translation or replacement.
+- **Active voice, second person where natural.** "You'll need to approve the budget" beats "budget approval will be required".
+
+## Anti-patterns to avoid
+
+- ❌ Burying the recommendation on page 2 of a 1-pager.
+- ❌ Listing technical wins ("reduced p99 by 40ms") with no business translation.
+- ❌ Risk sections full of generic risks ("scope creep", "team turnover"). Pick the *project-specific* ones.
+- ❌ "Next steps: align with stakeholders." Empty calorie. Replace with the actual action.
+- ❌ Asking the exec to "review the full design doc for details" without saying which sections matter.

package/skills/exec-summary/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "exec-summary",
+  "version": "0.1.0",
+  "description": "Compress a long technical document, design doc, or proposal into a one-page executive summary aimed at non-technical or time-poor stakeholders. Use when the user has a long doc and needs a 30-second readable version, or is writing a 1-pager for a steering committee, partner, or executive sponsor.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["executive", "summary", "stakeholder-communication", "one-pager"],
+  "model": { "tier": "standard", "rationale": "One-page compression. Needs to keep the right signal; escalates on very long source docs." }
+}

package/skills/exec-summary/templates/exec-summary.md

@@ -0,0 +1,48 @@
+# {Project / initiative name}
+
+**To:** {Audience — e.g. "CFO + Steering Committee"}
+**From:** {Author / team}
+**Date:** {YYYY-MM-DD}
+**Status:** {For decision / FYI / For approval}
+
+## The Ask
+
+{One sentence — the specific decision, approval, or input you need from this audience. If there's no Ask, this is a status update, not an exec summary.}
+
+## TL;DR
+
+- **What:** {one bullet — what this project is, in plain language}
+- **Why now:** {one bullet — the forcing function}
+- **Recommendation:** {one bullet — what we're recommending the audience approve / change / do}
+
+## Business impact
+
+- **Revenue / cost:** {quantified where possible — "$X savings per year" or "$Y revenue protected"}
+- **Risk:** {what risk is mitigated, or what risk is incurred}
+- **Time:** {when the business sees impact}
+
+## Cost & timeline
+
+| What | Estimate | Confidence |
+|---|---|---|
+| Engineering effort | {N person-months} | {rough / directional / firm} |
+| Vendor / infra cost | {$X over N months} | {…} |
+| Calendar timeline | {N months end-to-end} | {…} |
+
+## Top risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| {Project-specific risk #1} | {What we're doing about it} |
+| {Risk #2} | {…} |
+| {Risk #3} | {…} |
+
+## What we need from you
+
+- {Concrete ask — e.g. "Approve $400k FY26 budget by end of Q2"}
+- {Concrete ask — e.g. "Decision: build in-house vs. buy from Vendor X"}
+- {Concrete ask — e.g. "Intro to Acme's VP of Engineering"}
+
+---
+
+*Full design doc: {link} — sections {N, M} are most relevant if you want to dig in.*

package/skills/feature-implement-loop/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: feature-implement-loop
+description: Implement a feature or story so it ends up *verified*, not just generated. Takes a description + acceptance criteria, writes code and tests, then runs an adversarial review pass that hunts for gaps (broken edge cases, baked-in assumptions, uncovered acceptance criteria), and re-generates to close them — looping until the review is clean or a 3-round cap is hit. Use when handed a ticket / story / feature spec with acceptance criteria and the goal is shippable, self-checked code — not a first draft.
+---
+
+# feature-implement-loop
+
+You drive a feature from spec to *verified* implementation through a self-correcting loop. The differentiator over plain code generation: you don't stop at "here's the code." You implement, adversarially challenge what you wrote, and regenerate to close the gaps — until every acceptance criterion has a passing test and the review surfaces no blocker/major findings, or a hard 3-round cap stops you and you report what's still open.
+
+This is the **dev-workflow loop** counterpart to the artifact pipeline. It composes the [`devils-advocate`](../devils-advocate/SKILL.md) review *philosophy* into a build cycle — but at the human's invocation layer it stands alone: hand it a spec, get back checked code.
+
+## Input
+
+A feature/story with two parts:
+- **Description** — what to build and why.
+- **Acceptance criteria** — the conditions that define "done." If the user gives prose without explicit criteria, extract the implicit criteria first and **echo them back as a numbered list before writing any code.** No criteria, no loop — the criteria are the gate.
+
+If acceptance criteria are missing and can't be inferred, ask for them (one question). Don't invent a gate the user didn't agree to.
+
+## How to respond
+
+1. **Restate the spec as a criteria checklist.** Number every acceptance criterion. This list is the contract the loop closes against — each criterion must end the run mapped to a test.
+
+2. **Plan the verification first.** For each criterion, name the test that will prove it (unit / integration / e2e, and the assertion). Surface criteria that *can't* be tested automatically (e.g. "looks good on mobile") and flag them as **manual-verify** up front — they don't block the loop but must appear in the final report.
+
+3. **Generate code + tests together.** Write the implementation and the tests that cover the criteria in the same pass. Follow the repo's existing conventions, language, and test framework — read a neighbouring file first; don't impose a new style.
+
+4. **Run the adversarial review pass.** This is the heart of the loop. Challenge what you just wrote:
+   - **In Claude Code (or any tool with subagents):** delegate to the `devils-advocate` subagent on the generated diff.
+   - **Everywhere else (Codex, Cursor, Aider, …):** run the review inline, sweeping the four lenses yourself:
+     1. **Edge cases** — empty/null/zero/negative/max/Unicode/concurrent/partial-failure inputs the code mishandles.
+     2. **Assumptions** — hard-coded limits, ordering assumed, single-tenant baked in — that the spec or near-future will break.
+     3. **Staff-engineer pushback** — concurrency, error handling, security (authz/injection/secrets), observability, blast radius, idempotency.
+     4. **Acceptance-criteria coverage** — for each numbered criterion: is there a test, and does it actually assert the criterion (not just exercise the code)?
+   - Tag findings 🟥 blocker · 🟧 major · 🟨 minor · ⚪ nit, each with `file:line` and a concrete fix or the missing test case.
+
+5. **Apply the gate.** Compute whether gaps remain:
+   - **Gap = any 🟥 blocker, OR any 🟧 major, OR any acceptance criterion without a passing, asserting test.**
+   - 🟨 minor / ⚪ nit findings do **not** force another round — list them, don't loop on them.
+
+6. **Loop or stop.**
+   - **Gaps remain and rounds used < 3** → regenerate to close *only* the gap findings (don't churn unrelated code), then go back to step 4. Increment the round counter.
+   - **No gaps** → stop: the implementation is verified. Go to the report.
+   - **Gaps remain and rounds == 3** → stop anyway. Do **not** loop further. Report the remaining gaps explicitly as open — never silently declare done.
+
+7. **Report.** Always end with:
+   - **Status:** `VERIFIED` (clean) · `VERIFIED WITH OPEN ITEMS` (cap hit, gaps remain) · `BLOCKED` (couldn't generate / couldn't run tests).
+   - **Acceptance-criteria table:** every criterion → ✅ covered (test name) · ⚠️ manual-verify · ❌ open (why).
+   - **Round log:** what each round found and fixed (1 → 2 → 3). This is the proof of work — it shows the loop did something.
+   - **Open items:** any remaining gaps after the cap, with the finding and why it wasn't auto-closable, so a human can finish it.
+
+## Quality bar
+
+- **Every acceptance criterion maps to a test by the final report.** A criterion with no asserting test is an ❌ open item — not a pass. This is the rule that makes the skill more than codegen.
+- **The review challenges the code; it doesn't rubber-stamp it.** A round-1 review that finds nothing on a non-trivial feature is a smell — re-run it adversarially, assuming the first pass missed something (it usually did).
+- **Tests assert behavior, not just execution.** ❌ a test that calls the function and checks it didn't throw. ✅ a test that asserts the criterion's expected output. Catch assertion theater in the review.
+- **Regeneration is targeted.** Each round fixes the named gaps and leaves passing code alone. Don't rewrite the whole feature every round — that loses ground and never converges.
+- **The cap is real.** 3 rounds, then stop and report. A loop that "just one more round"s past 3 is a bug. If it can't converge in 3, a human needs to see why.
+- **The round log is honest.** If round 2 found nothing new, say so. If a gap was downgraded rather than fixed, say why. The log is the audit trail.
+
+## When to use this skill
+
+- ✅ A ticket / story / feature spec arrives **with acceptance criteria** and the goal is shippable, self-checked code.
+- ✅ When the user says "implement this and make sure it actually meets the criteria" / "build it and check your own work."
+- ✅ Net-new features and well-scoped enhancements where the criteria are concrete.
+
+## When NOT to use this skill
+
+- ❌ One-line fixes / trivial changes — the loop is overhead; just make the change.
+- ❌ Greenfield spikes / throwaway prototypes — verifying code you'll delete wastes rounds.
+- ❌ Specs with no acceptance criteria and none inferable — there's no gate to close. Get criteria first.
+- ❌ Pure code *review* of code you didn't generate — that's [`devils-advocate`](../devils-advocate/SKILL.md) standalone.
+- ❌ Open-ended design questions ("should we use Postgres or Dynamo?") — that's `design-doc` + `doc-critique`.
+
+## Anti-patterns to avoid
+
+- ❌ **Declaring "done" with an uncovered criterion.** The whole point is the criteria gate. A criterion without an asserting test is open, full stop.
+- ❌ **A toothless review round.** Delegating to devils-advocate or sweeping the lenses, then reporting "no issues" on a real feature — the loop only earns its keep if the review actually adversarial.
+- ❌ **Looping past 3 rounds.** Convergence isn't guaranteed; the cap exists so a human gets pulled in instead of the agent thrashing.
+- ❌ **Wholesale regeneration each round.** Rewriting passing code to fix one gap loses verified ground. Patch the gap.
+- ❌ **Calling the `devils-advocate` *skill* from here.** Skills don't invoke skills (see CLAUDE.md). Drive the *subagent* where one exists, or inline the four lenses. Same applies to any other skill.
+- ❌ **Assertion theater.** Tests that run the code but assert nothing meaningful pass the round and hide the gap. The review must reject them.
+- ❌ **Silent manual-verify criteria.** Criteria that can't be auto-tested must be surfaced as ⚠️ manual-verify in the report, not quietly skipped.

package/skills/feature-implement-loop/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "feature-implement-loop",
+  "version": "0.1.0",
+  "description": "Implement a feature or story so it ends up *verified*, not just generated. Takes a description + acceptance criteria, writes code and tests, then runs an adversarial review pass that hunts for gaps (broken edge cases, baked-in assumptions, uncovered acceptance criteria), and re-generates to close them — looping until the review is clean or a 3-round cap is hit. Use when handed a ticket / story / feature spec with acceptance criteria and the goal is shippable, self-checked code — not a first draft.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["design-doc", "devils-advocate", "doc-critique"],
+  "tags": ["dev-workflow", "implementation", "tdd", "acceptance-criteria", "adversarial", "self-correcting", "code-generation"],
+  "model": { "tier": "standard", "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation." }
+}

package/skills/figma-diagrams/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: figma-diagrams
+description: Work with Figma and FigJam files via the Figma REST API — read existing file structure, list frames/pages, post comments, and produce FigJam-importable diagram specs. Use when the user mentions a Figma URL, asks to inspect/audit a Figma file, wants to comment on a design programmatically, or wants their architecture diagram in Figma.
+---
+
+# figma-diagrams
+
+You help the user **interact with Figma files programmatically** — most often to bridge an architecture diagram from text/Mermaid into a Figma design surface their team is already reviewing in.
+
+## Important: what's possible, what isn't
+
+The Figma REST API is **mostly read-only for file contents**. Be honest with the user about this:
+
+| Task | How |
+|---|---|
+| Read a Figma file's pages, frames, components | ✅ REST API — `GET /v1/files/:file_key` |
+| List images / thumbnails of frames | ✅ REST API — `GET /v1/images/:file_key` |
+| Post a comment on a file or pin to a region | ✅ REST API — `POST /v1/files/:file_key/comments` |
+| Read team / project / variables | ✅ REST API |
+| **Create / mutate nodes** in a design file | ❌ Not via REST. Requires the **Figma Plugin API** (runs inside Figma desktop/web) |
+| Push a diagram into FigJam | ⚠️ Indirect — generate FigJam-importable JSON or have the user paste Mermaid via the "Mermaid → FigJam" community plugin |
+
+When the user asks you to "draw this in Figma directly," set expectations up front and offer the indirect paths (Mermaid plugin, FigJam JSON spec, or plugin code that they can paste into a Figma plugin).
+
+## Prerequisites
+
+The user needs a Figma Personal Access Token, exported as `FIGMA_TOKEN`:
+
+```bash
+export FIGMA_TOKEN="figd_..."
+```
+
+How to get one: Figma → Settings → Security → Personal access tokens → Generate. Scope it minimally (file content read, comments write) if Figma offers granular scopes.
+
+If `FIGMA_TOKEN` is not set, tell the user how to set it before running the scripts.
+
+## How to respond
+
+1. **Detect the URL.** Figma URLs look like `https://www.figma.com/file/<FILE_KEY>/<name>` or `https://www.figma.com/design/<FILE_KEY>/<name>`. Extract `<FILE_KEY>` — that's what the API takes.
+
+2. **Pick the right script.** Helper scripts live in `scripts/` next to this `SKILL.md`:
+
+   - `inspect_file.py <FILE_KEY>` — prints a tree of pages → frames → top-level groups
+   - `list_comments.py <FILE_KEY>` — lists existing comments with author + timestamp
+   - `post_comment.py <FILE_KEY> "<message>"` — adds a comment at the file root (or `--node-id N` to pin to a node)
+   - `frame_to_mermaid.py <FILE_KEY> <NODE_ID>` — exports a frame's structure as a first-pass Mermaid diagram (best-effort)
+
+   The path you use depends on where this skill is installed:
+
+   ```bash
+   # Claude Code exposes the skill's folder as $CLAUDE_SKILL_DIR
+   python3 "${CLAUDE_SKILL_DIR}/scripts/inspect_file.py" <FILE_KEY>
+
+   # In any other IDE (Cursor, Kiro, Continue, …) cd into the copied skill folder first
+   cd path/to/figma-diagrams && python3 scripts/inspect_file.py <FILE_KEY>
+   ```
+
+   Dependencies (just `requests`) are declared in `manifest.json` and `requirements.txt`. Install once with:
+
+   ```bash
+   python3 -m pip install -r requirements.txt
+   ```
+
+3. **For "I want my Mermaid diagram in Figma":** the cleanest path is the [Mermaid → Figma/FigJam community plugin](https://www.figma.com/community/plugin/1222021271365394457). Generate the Mermaid first (via the [`architecture-diagrams`](../architecture-diagrams/SKILL.md) skill), then guide the user to paste it. Don't pretend to push it via REST.
+
+4. **For team audits** (e.g., "what's in our design system file?"), run `inspect_file.py` and summarize. The full JSON dump is huge — only show the user the structure that answers their question.
+
+## Useful references
+
+- [`reference.md`](reference.md) — Figma REST API endpoints, auth, rate limits, common gotchas
+- [`templates/figjam-import.json`](templates/figjam-import.json) — example shape of a JSON spec that a FigJam plugin could consume to materialize a diagram
+- [`manifest.json`](manifest.json) — declared dependencies and required env vars (read by some IDEs at install time)
+
+## Quality bar
+
+- **Never log the token.** Scripts use `os.environ["FIGMA_TOKEN"]`; don't pass it on the command line.
+- **Don't dump 5 MB of JSON** to the user. Filter to pages/frames/groups (3 levels) and summarize.
+- **Confirm before posting comments.** A comment is visible to anyone with file access — show the user the exact text and the file URL before calling `post_comment.py`.
+- **Handle 429s.** The Figma API rate-limits (~25 req/min for some endpoints). If a script returns 429, back off and retry; don't loop.
+
+## Anti-patterns to avoid
+
+- ❌ Claiming the script "drew" something in the user's Figma file. It didn't (REST API can't).
+- ❌ Asking the user to paste their token into chat. They should `export FIGMA_TOKEN=…` in their own shell.
+- ❌ Posting test comments to an unfamiliar file without explicit confirmation.

package/skills/figma-diagrams/manifest.json

@@ -0,0 +1,35 @@
+{
+  "name": "figma-diagrams",
+  "version": "0.1.0",
+  "description": "Work with Figma and FigJam files via the Figma REST API — read existing file structure, list frames/pages, post comments, and produce FigJam-importable diagram specs. Use when the user mentions a Figma URL, asks to inspect/audit a Figma file, wants to comment on a design programmatically, or wants their architecture diagram in Figma.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": [
+      "requests>=2.28"
+    ]
+  },
+  "env": {
+    "required": [
+      "FIGMA_TOKEN"
+    ],
+    "optional": []
+  },
+  "related": [
+    "architecture-diagrams"
+  ],
+  "install": {
+    "pip": "python3 -m pip install -r requirements.txt"
+  },
+  "tags": [
+    "figma",
+    "figjam",
+    "diagrams",
+    "design",
+    "api"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "API calls + spec generation. Bounded transformation."
+  }
+}

package/skills/figma-diagrams/reference.md

@@ -0,0 +1,91 @@
+# Figma REST API — quick reference
+
+Official docs: https://www.figma.com/developers/api
+
+## Auth
+
+Every request needs the `X-Figma-Token` header:
+
+```
+X-Figma-Token: figd_...
+```
+
+Tokens are scoped to the user who created them — they can do anything that user can do in the UI.
+
+## Endpoints used by this skill
+
+| Verb | Path | Purpose |
+|---|---|---|
+| `GET` | `/v1/files/:file_key` | Full file JSON: document tree (pages, frames, all nodes). Large. |
+| `GET` | `/v1/files/:file_key/nodes?ids=A,B` | Same shape as above but scoped to specific node IDs — cheaper. |
+| `GET` | `/v1/files/:file_key/comments` | List all comments. |
+| `POST` | `/v1/files/:file_key/comments` | Add a comment. Body: `{"message": "...", "client_meta": {...}}` |
+| `GET` | `/v1/images/:file_key?ids=A,B&format=svg` | Render frames as PNG/SVG/PDF/JPG. Returns S3 URLs (expire ~30 days). |
+| `GET` | `/v1/me` | Sanity-check the token. |
+| `GET` | `/v1/teams/:team_id/projects` | List projects in a team (needs team-scope token). |
+| `GET` | `/v1/projects/:project_id/files` | List files in a project. |
+
+## File key extraction
+
+```
+https://www.figma.com/file/AbC123XyZ/My-Architecture
+                          ^^^^^^^^^^ <-- FILE_KEY
+
+https://www.figma.com/design/AbC123XyZ/My-Architecture   (newer URL format)
+                            ^^^^^^^^^^
+
+https://www.figma.com/board/AbC123XyZ/My-Whiteboard      (FigJam)
+                           ^^^^^^^^^^
+```
+
+Regex that works on all three: `figma\.com/(?:file|design|board)/([A-Za-z0-9]+)/`
+
+## Node IDs
+
+Nodes have IDs like `1:23` or `1-23` (older URL format used `-`, JSON uses `:`). Both refer to the same node — normalize to `:` when calling the API.
+
+## Rate limits
+
+Roughly **~25 requests/minute per token** for read-heavy endpoints; image renders are slower. The API returns `429 Too Many Requests` with `Retry-After`. Back off, don't hammer.
+
+## Common gotchas
+
+- **`GET /v1/files/:key` is huge** — even small design files can be many MB. Prefer `/nodes?ids=...` if you know the node you want.
+- **Image rendering is async on the server.** The endpoint returns synchronously but Figma may take a few seconds for large frames; image URLs expire (~30 days).
+- **Comments accept lightweight markdown** in the `message` field, but no rich formatting beyond newlines.
+- **The Plugin API ≠ the REST API.** Anything you find that says "create rectangle / set fill" is the Plugin API (TypeScript inside Figma). You can't call it from outside Figma.
+- **FigJam files use the same endpoints** but the node shapes are different (`STICKY`, `SHAPE_WITH_TEXT`, `CONNECTOR`).
+
+## Document shape (skeleton)
+
+```json
+{
+  "document": {
+    "id": "0:0",
+    "name": "Document",
+    "type": "DOCUMENT",
+    "children": [
+      {
+        "id": "0:1",
+        "name": "Page 1",
+        "type": "CANVAS",
+        "children": [
+          {
+            "id": "1:2",
+            "name": "Architecture",
+            "type": "FRAME",
+            "children": [...]
+          }
+        ]
+      }
+    ]
+  },
+  "components": {...},
+  "styles": {...},
+  "name": "My file",
+  "lastModified": "2026-05-20T...",
+  "version": "..."
+}
+```
+
+Most interesting node types: `FRAME`, `GROUP`, `COMPONENT`, `INSTANCE`, `RECTANGLE`, `TEXT`, `CONNECTOR` (FigJam), `STICKY` (FigJam).

package/skills/figma-diagrams/requirements.txt

@@ -0,0 +1 @@
+requests>=2.28

package/skills/figma-diagrams/scripts/_figma_client.py

@@ -0,0 +1,71 @@
+"""Tiny shared client for the Figma REST API.
+
+Used by the other scripts in this directory. Not meant to be run directly.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+from typing import Any
+
+import requests
+
+API_BASE = "https://api.figma.com"
+FILE_KEY_RE = re.compile(r"figma\.com/(?:file|design|board)/([A-Za-z0-9]+)/")
+
+
+def token() -> str:
+    tok = os.environ.get("FIGMA_TOKEN")
+    if not tok:
+        sys.stderr.write(
+            "error: FIGMA_TOKEN is not set.\n"
+            "  Get one at: Figma → Settings → Security → Personal access tokens\n"
+            "  Then: export FIGMA_TOKEN=figd_...\n"
+        )
+        sys.exit(2)
+    return tok
+
+
+def extract_file_key(arg: str) -> str:
+    """Accept either a Figma URL or a bare file key."""
+    m = FILE_KEY_RE.search(arg)
+    if m:
+        return m.group(1)
+    if re.fullmatch(r"[A-Za-z0-9]+", arg):
+        return arg
+    sys.stderr.write(f"error: could not extract a Figma file key from {arg!r}\n")
+    sys.exit(2)
+
+
+def _request(method: str, path: str, **kwargs: Any) -> requests.Response:
+    headers = kwargs.pop("headers", {})
+    headers["X-Figma-Token"] = token()
+    url = f"{API_BASE}{path}"
+    for attempt in range(3):
+        resp = requests.request(method, url, headers=headers, timeout=30, **kwargs)
+        if resp.status_code == 429:
+            retry = int(resp.headers.get("Retry-After", "2"))
+            sys.stderr.write(f"rate-limited, sleeping {retry}s\n")
+            time.sleep(retry)
+            continue
+        return resp
+    return resp  # last response, even if 429
+
+
+def get(path: str, **kwargs: Any) -> dict[str, Any]:
+    resp = _request("GET", path, **kwargs)
+    if not resp.ok:
+        sys.stderr.write(f"error: GET {path} → {resp.status_code} {resp.text[:200]}\n")
+        sys.exit(1)
+    return resp.json()
+
+
+def post(path: str, json: dict[str, Any]) -> dict[str, Any]:
+    resp = _request("POST", path, json=json)
+    if not resp.ok:
+        sys.stderr.write(f"error: POST {path} → {resp.status_code} {resp.text[:200]}\n")
+        sys.exit(1)
+    return resp.json()

package/skills/figma-diagrams/scripts/frame_to_mermaid.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Best-effort: turn a Figma frame's child structure into a first-pass Mermaid flowchart.
+
+This won't perfectly capture visual layout — it walks the node tree, looks at
+text labels and parent/child relationships, and produces a Mermaid `flowchart TB`
+you can hand-edit. Useful as a starting point when reverse-engineering a
+diagram a colleague drew in Figma.
+
+Usage:
+    python frame_to_mermaid.py <FILE_KEY_OR_URL> <NODE_ID>
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from _figma_client import extract_file_key, get
+
+SAFE_ID_RE = re.compile(r"[^A-Za-z0-9_]+")
+
+
+def safe_id(node_id: str) -> str:
+    return "n" + SAFE_ID_RE.sub("_", node_id)
+
+
+def best_label(node: dict) -> str:
+    """Pick a human label for a node — its name, or a TEXT descendant if name is generic."""
+    name = (node.get("name") or "").strip()
+    if name and not name.lower().startswith(("frame", "group", "rectangle", "ellipse")):
+        return name
+    for child in node.get("children", []) or []:
+        if child.get("type") == "TEXT":
+            chars = (child.get("characters") or "").strip()
+            if chars:
+                return chars
+        deeper = best_label(child)
+        if deeper and deeper != child.get("name"):
+            return deeper
+    return name or node.get("type", "node")
+
+
+def emit(node: dict, parent_id: str | None, lines: list[str], edges: list[str]) -> None:
+    type_ = node.get("type")
+    if type_ in {"DOCUMENT", "CANVAS"}:
+        for c in node.get("children", []) or []:
+            emit(c, parent_id, lines, edges)
+        return
+
+    my_id = safe_id(node["id"])
+    label = best_label(node).replace('"', "'")[:60]
+
+    if type_ in {"FRAME", "GROUP", "SECTION"}:
+        lines.append(f'    subgraph {my_id}["{label}"]')
+        for c in node.get("children", []) or []:
+            emit(c, my_id, lines, edges)
+        lines.append("    end")
+    elif type_ in {"RECTANGLE", "ELLIPSE", "COMPONENT", "INSTANCE", "TEXT"}:
+        if type_ == "ELLIPSE":
+            lines.append(f'    {my_id}(("{label}"))')
+        else:
+            lines.append(f'    {my_id}["{label}"]')
+        if parent_id:
+            edges.append(f"    {parent_id} --- {my_id}")
+    elif type_ == "CONNECTOR":
+        ep = node.get("connectorStart", {})
+        eq = node.get("connectorEnd", {})
+        a = ep.get("endpointNodeId")
+        b = eq.get("endpointNodeId")
+        if a and b:
+            edges.append(f"    {safe_id(a)} --> {safe_id(b)}")
+    else:
+        for c in node.get("children", []) or []:
+            emit(c, parent_id, lines, edges)
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        sys.stderr.write("usage: frame_to_mermaid.py <FILE_KEY_OR_URL> <NODE_ID>\n")
+        return 2
+    file_key = extract_file_key(argv[0])
+    node_id = argv[1]
+
+    data = get(f"/v1/files/{file_key}/nodes", params={"ids": node_id})
+    node = data.get("nodes", {}).get(node_id, {}).get("document")
+    if not node:
+        sys.stderr.write(f"error: node {node_id} not found in {file_key}\n")
+        return 1
+
+    lines: list[str] = ["flowchart TB"]
+    edges: list[str] = []
+    emit(node, None, lines, edges)
+    lines.extend(edges)
+
+    print("```mermaid")
+    print("\n".join(lines))
+    print("```")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/skills/figma-diagrams/scripts/inspect_file.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Print a tree summary of a Figma file: pages → frames → top-level groups.
+
+Usage:
+    python inspect_file.py <FILE_KEY_OR_URL> [--depth N]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from _figma_client import extract_file_key, get
+
+
+def walk(node: dict, depth: int, max_depth: int) -> None:
+    if depth > max_depth:
+        return
+    indent = "  " * depth
+    name = node.get("name", "<unnamed>")
+    type_ = node.get("type", "?")
+    id_ = node.get("id", "?")
+    print(f"{indent}- [{type_}] {name}  (id={id_})")
+    for child in node.get("children", []) or []:
+        walk(child, depth + 1, max_depth)
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("file", help="Figma file URL or bare file key")
+    ap.add_argument("--depth", type=int, default=3, help="Max tree depth to print")
+    args = ap.parse_args(argv)
+
+    file_key = extract_file_key(args.file)
+    data = get(f"/v1/files/{file_key}")
+
+    print(f"file: {data.get('name')!r}")
+    print(f"last modified: {data.get('lastModified')}")
+    print(f"version: {data.get('version')}")
+    print()
+    walk(data["document"], depth=0, max_depth=args.depth)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))