skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/solution-architect/skills/design-doc/manifest.json

@@ -0,0 +1,14 @@
+{
+  "name": "design-doc",
+  "version": "0.1.0",
+  "description": "Generate a Google-style engineering design doc (problem, goals/non-goals, options considered, recommended approach, risks, rollout) from a feature brief or short description. Use when the user wants to draft a design doc, technical proposal, or one-pager for an engineering review.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["architecture-diagrams"],
+  "handoff": [
+    { "to": "architecture-diagrams", "when": "the design is written and needs rendering", "purpose": "Render the prose as a diagram that must not disagree with it.", "fallback": "If architecture-diagrams is absent, emit Mermaid inline and check every node against a claim in the doc." }
+  ],
+  "tags": ["design-doc", "documentation", "engineering", "review"],
+  "model": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalates to opus on big or genuinely contested inputs." }
+}

skilldrop_cli/data/packs/solution-architect/skills/design-doc/templates/design-doc.md

@@ -0,0 +1,98 @@
+# {Title — what we're building, as a noun phrase}
+
+| Field | Value |
+|---|---|
+| Status | {Draft / In Review / Approved / Implemented} |
+| Author(s) | {Names} |
+| Reviewers | {Names — list the people whose approval you need} |
+| Date | {YYYY-MM-DD} |
+| Related | {Links to ADRs, prior design docs, tickets} |
+
+## TL;DR
+
+- {One bullet — what we're doing}
+- {One bullet — why now}
+- {One bullet — what changes for callers / users}
+
+## Context
+
+{Two or three paragraphs. What's the current state? What's the forcing function? Why is this design doc happening *now* rather than 6 months ago or in 6 months?}
+
+## Goals
+
+- {Goal — measurable where possible: "p99 latency under 100ms"}
+- {Goal}
+- {Goal}
+
+## Non-goals
+
+- {Non-goal — something a reasonable reader might assume is in scope but isn't, e.g. "migrating existing customers' historical data"}
+- {Non-goal}
+
+## Proposal
+
+{The actual design. This is the largest section. Cover:}
+
+### High-level architecture
+
+{Embed a Mermaid or PlantUML diagram showing the major components and data flow. Keep it under 15 nodes.}
+
+```mermaid
+flowchart LR
+    A[Component A] --> B[Component B]
+    B --> C[(Store)]
+```
+
+### Key design decisions
+
+- **{Decision 1}:** {What we chose and the one-line why.}
+- **{Decision 2}:** {What we chose and the one-line why.}
+- **{Decision 3}:** {What we chose and the one-line why.}
+
+### API / interface
+
+{For each new or changed endpoint, show a small example. Don't dump the OpenAPI spec — point to it instead.}
+
+### Data model changes
+
+{Schema changes, migrations needed, backfill plan.}
+
+## Alternatives considered
+
+### {Alternative 1}
+
+{2–3 sentences: what it is, why we didn't pick it.}
+
+### {Alternative 2}
+
+{2–3 sentences.}
+
+## Risks & mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| {Risk — e.g. "migration script takes longer than the maintenance window"} | M | H | {Mitigation — e.g. "rehearse on prod-shape staging; have a no-op rollback path"} |
+| {Risk} | L | H | {Mitigation} |
+
+## Rollout plan
+
+1. **{Phase} — {behind feature flag, internal only}:** {Concrete criteria for advancing to next phase, e.g., "no new errors in error budget for 48h"}
+2. **{Phase} — {1% of traffic}:** {Criteria}
+3. **{Phase} — {10% / 50% / 100%}:** {Criteria}
+
+**Rollback criteria:** {When do we revert? Be specific.}
+
+## Observability
+
+- **New metrics:** {what we'll instrument}
+- **New alerts:** {pages on what conditions}
+- **Dashboard:** {link, or "TBD before launch"}
+
+## Open questions
+
+- **{Question}** — owner: {name}, due: {date}
+- **{Question}** — owner: {name}, due: {date}
+
+## Appendix
+
+{Optional — link out to longer materials. Don't inline. Common contents: benchmarks, full schema diffs, security review notes.}

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/SKILL.md

@@ -0,0 +1,87 @@
+---
+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`, pinned) are declared in `manifest.json` and `requirements.txt`.
+   **Requires Python 3.10+** — the pinned `requests` drops older interpreters. 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.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "List the frames in our Figma file",
+    "should_trigger": true
+  },
+  {
+    "query": "Read this Figma file structure via the API",
+    "should_trigger": true
+  },
+  {
+    "query": "Post a comment on this Figma frame",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert this FigJam connector graph into a diagram spec",
+    "should_trigger": true
+  },
+  {
+    "query": "Draw an architecture diagram in Mermaid from this description",
+    "should_trigger": false
+  },
+  {
+    "query": "Reverse-engineer our architecture from the repo",
+    "should_trigger": false
+  },
+  {
+    "query": "Build a PowerPoint deck from this content",
+    "should_trigger": false
+  },
+  {
+    "query": "Audit this UI for accessibility issues",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/evals/evals.json

@@ -0,0 +1,15 @@
+{
+  "skill_name": "figma-diagrams",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "List the pages and frames in this Figma file and post a comment on the checkout frame.",
+      "assertions": [
+        "The token is read from the FIGMA_TOKEN environment variable and never logged or passed on the command line",
+        "Output is filtered to pages, frames, and groups (about three levels) and summarized rather than dumping raw JSON",
+        "Before posting any comment, the exact comment text and target frame are shown for confirmation",
+        "The skill states clearly when FIGMA_TOKEN is missing rather than failing opaquely"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/manifest.json

@@ -0,0 +1,36 @@
+{
+  "name": "figma-diagrams",
+  "version": "0.1.1",
+  "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.34.2"
+    ]
+  },
+  "env": {
+    "required": [
+      "FIGMA_TOKEN"
+    ],
+    "optional": []
+  },
+  "related": [
+    "architecture-diagrams"
+  ],
+  "install": {
+    "pip": "python3 -m pip install -r requirements.txt"
+  },
+  "tags": [
+    "figma",
+    "figjam",
+    "diagrams",
+    "design",
+    "api"
+  ],
+  "permissions": {"network": ["api.figma.com"], "commands": [], "files": "named-paths", "notes": "Reads FIGMA_TOKEN from the environment to call the Figma REST API."},
+  "model": {
+    "tier": "standard",
+    "rationale": "API calls + spec generation. Bounded transformation."
+  }
+}

skilldrop_cli/data/packs/solution-architect/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).

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/requirements.txt

@@ -0,0 +1,3 @@
+# Pinned, not ranged: an open range lets a future release install itself unreviewed.
+# requests 2.34.2 requires Python >= 3.10.
+requests==2.34.2

skilldrop_cli/data/packs/solution-architect/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()

skilldrop_cli/data/packs/solution-architect/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:]))

skilldrop_cli/data/packs/solution-architect/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:]))

skilldrop_cli/data/packs/solution-architect/skills/figma-diagrams/scripts/list_comments.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""List comments on a Figma file.
+
+Usage:
+    python list_comments.py <FILE_KEY_OR_URL>
+"""
+
+from __future__ import annotations
+
+import sys
+
+from _figma_client import extract_file_key, get
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 1:
+        sys.stderr.write("usage: list_comments.py <FILE_KEY_OR_URL>\n")
+        return 2
+    file_key = extract_file_key(argv[0])
+    data = get(f"/v1/files/{file_key}/comments")
+    comments = data.get("comments", [])
+    if not comments:
+        print("(no comments)")
+        return 0
+    for c in comments:
+        author = c.get("user", {}).get("handle", "<unknown>")
+        ts = c.get("created_at", "")
+        msg = c.get("message", "").strip().replace("\n", " ")
+        resolved = " [resolved]" if c.get("resolved_at") else ""
+        print(f"- {ts}  @{author}{resolved}: {msg}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))