@pedroab0/skills 1.1.0 → 1.3.0

package/bin/cli.js

@@ -72,9 +72,37 @@ ${style.bold('Examples:')}
 }
 
 // -----------------------------------------------------------------------------
-// Skill Discovery
+// Frontmatter & Skill Discovery
 // -----------------------------------------------------------------------------
 
+function parseFrontmatterField(content, field) {
+  const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return '';
+  const lines = fm[1].split(/\r?\n/);
+  const line = lines.find((l) => l.startsWith(`${field}:`));
+  if (!line) return '';
+  const raw = line.slice(field.length + 1).trim();
+  if (raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/''/g, "'");
+  }
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    try {
+      return JSON.parse(raw);
+    } catch (_) {
+      return raw.slice(1, -1);
+    }
+  }
+  return raw;
+}
+
+function rewriteRelativeLinksForCursor(body, skill) {
+  return body.replace(/\]\((?!https?:|#|\/)([^)\s#]+\.md)(#[^)]*)?\)/g, (m, rel, hash = '') => {
+    return fs.existsSync(path.join(skill.path, rel))
+      ? `](../skills/${skill.name}/${rel}${hash || ''})`
+      : m;
+  });
+}
+
 function getAvailableSkills() {
   const skills = [];
   try {
@@ -87,10 +115,7 @@ function getAvailableSkills() {
           let description = '';
           try {
             const content = fs.readFileSync(skillMdPath, 'utf8');
-            const match = content.match(/description:\s*['"]?([^'"\n\r]+)['"]?/);
-            if (match) {
-              description = match[1].trim();
-            }
+            description = parseFrontmatterField(content, 'description');
           } catch (_) {}
           skills.push({
             name: entry.name,
@@ -506,12 +531,32 @@ function checkFigmaToken(options = {}) {
 // Skill Installation Logic
 // -----------------------------------------------------------------------------
 
+const EXCLUDED_SKILL_DIRS = new Set(['demo', 'demos', '.specs', 'node_modules', '.git']);
+
+function shouldCopySkillEntry(rootSkillPath) {
+  return (srcPath) => {
+    const rel = path.relative(rootSkillPath, srcPath);
+    if (!rel) return true;
+    const parts = rel.split(/[\\/]/);
+    const base = parts[parts.length - 1];
+    if (base === '.DS_Store' || base === 'Thumbs.db' || /^test_.*\.js$/i.test(base)) {
+      return false;
+    }
+    for (let i = 0; i < parts.length; i++) {
+      if (EXCLUDED_SKILL_DIRS.has(parts[i])) return false;
+      if (parts[i] === 'figma-plugin' && parts[i + 1] === 'assets') return false;
+    }
+    return true;
+  };
+}
+
 function installSkill(skill, destDir, useSymlink = false, isCursor = false) {
   if (!fs.existsSync(destDir)) {
     fs.mkdirSync(destDir, { recursive: true });
   }
 
   const targetPath = path.join(destDir, skill.name);
+  const copyFilter = shouldCopySkillEntry(skill.path);
 
   if (isCursor) {
     const cursorSkillsDir = path.join(path.dirname(destDir), 'skills', skill.name);
@@ -520,14 +565,17 @@ function installSkill(skill, destDir, useSymlink = false, isCursor = false) {
     if (fs.existsSync(cursorSkillsDir)) {
       fs.rmSync(cursorSkillsDir, { recursive: true, force: true });
     }
-    fs.cpSync(skill.path, cursorSkillsDir, { recursive: true });
+    fs.cpSync(skill.path, cursorSkillsDir, { recursive: true, filter: copyFilter });
 
     const rawSkillMd = fs.readFileSync(path.join(skill.path, 'SKILL.md'), 'utf8');
-    const skillBody = rawSkillMd.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, '');
+    const skillBody = rewriteRelativeLinksForCursor(
+      rawSkillMd.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, ''),
+      skill,
+    );
     const ruleFile = path.join(destDir, `${skill.name}.mdc`);
     const ruleContent = `---
-description: ${skill.description}
-globs: *
+description: ${JSON.stringify(skill.description)}
+alwaysApply: false
 ---
 
 ${skillBody}`;
@@ -545,11 +593,11 @@ ${skillBody}`;
       fs.symlinkSync(skill.path, targetPath, symlinkType);
       return { targetPath, isSymlink: true };
     } catch (e) {
-      fs.cpSync(skill.path, targetPath, { recursive: true });
+      fs.cpSync(skill.path, targetPath, { recursive: true, filter: copyFilter });
       return { targetPath, isSymlink: false };
     }
   } else {
-    fs.cpSync(skill.path, targetPath, { recursive: true });
+    fs.cpSync(skill.path, targetPath, { recursive: true, filter: copyFilter });
     const scriptsDir = path.join(targetPath, 'scripts');
     if (fs.existsSync(scriptsDir)) {
       try {
@@ -860,6 +908,8 @@ if (require.main === module) {
 
 module.exports = {
   selectPrompt,
+  parseFrontmatterField,
+  rewriteRelativeLinksForCursor,
   getAvailableSkills,
   getAgentConfigs,
   checkFigmaToken,

package/figma-extractor/README.md

@@ -129,6 +129,7 @@ node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --tokens --spec tokens
 | `--spec <name>` | | **Atomic SDD mode**: Saves `./.specs/<name>.json` (add `-i` to also download preview PNG). |
 | `--image`, `--download-image` | `-i` | Download and save rendered preview image from Figma (Tier 1 call; optional). |
 | `--image-path <path>` | `-o <path>` | Custom destination path for saved preview image (e.g., `./.specs/card.png`). |
+| `--force`, `--fresh` | `-f` | Ignore existing local spec/preview and re-fetch freshly from Figma. |
 | `--tokens`, `--variables` | | Export only the file's design token dictionary (colors, spacing, radii). |
 | `--shallow-instances` | | Collapse internal layers of component instances into clean props. |
 | `--include-tokens` | | Bundle complete design tokens dictionary alongside the node tree. |
@@ -137,7 +138,7 @@ node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --tokens --spec tokens
 | `--raw` | | Return full unpruned Figma API response without filtering. |
 | `--depth <number>` | | Limit node tree traversal depth (e.g., `--depth 2` for top-level layout only). |
 | `--scale <1\|2\|3\|4>` | | Multiplier for rendered image resolution (default: `2`). |
-| `--format <png\|svg\|jpg>` | | Image format for downloaded preview (default: `png`). |
+| `--format <png\|svg\|jpg\|pdf>` | | Image format for downloaded preview (default: `png`). |
 | `--no-variables` | | Skip querying local variables to speed up extraction. |
 | `--help` | `-h` | Display command usage and available flags. |
 

package/figma-extractor/REFERENCE.md

@@ -0,0 +1,111 @@
+# Figma Extractor Reference
+
+## Contents
+
+- Token setup
+- Corporate proxy and SSL
+- CLI flags
+- Output spec schema
+- Rate-limit gate internals
+
+## Token setup
+
+A Figma Personal Access Token (or OAuth token) is required. The user creates one in **Figma Settings → Personal Access Tokens**. The script reads `FIGMA_ACCESS_TOKEN` (or `FIGMA_TOKEN`) from the environment, from `.env` / `.env.local` in the working directory, from `~/.env`, and from shell profiles.
+
+| Platform | Command for the user |
+| :--- | :--- |
+| macOS / Linux | `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` in `~/.zshrc` or `~/.bashrc` |
+| Windows (PowerShell) | `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")` |
+| Any (workspace) | `FIGMA_ACCESS_TOKEN=figd_your_token_here` in `.env` |
+
+## Corporate proxy and SSL
+
+Behind a corporate proxy with self-signed certificates, the script fails with `FIGMA_SSL_CERTIFICATE_ERROR`. The user can disable certificate verification for Figma requests:
+
+```env
+FIGMA_IGNORE_SSL=true
+```
+
+## CLI flags
+
+```bash
+node "<skill-dir>/scripts/fetch_figma.js" <FigmaURL> [options]
+node "<skill-dir>/scripts/fetch_figma.js" <fileKey> [nodeId] [options]
+```
+
+| Flag | Shorthand | Description |
+| :--- | :--- | :--- |
+| `--spec <name>` | | Save `./.specs/<name>.json` (and `<name>.png` with `-i`). Reuses an existing spec with 0 API calls. |
+| `--image`, `--download-image` | `-i` | Download the rendered preview image (+1 Tier 1 call). |
+| `--image-path <path>`, `--output <path>` | `-o <path>` | Destination path for the preview image (implies `--image`). |
+| `--force`, `--fresh` | `-f` | Ignore the existing local spec/preview and re-fetch from Figma. |
+| `--tokens`, `--variables` | | Output only the design token dictionary (colors, spacing, radii). |
+| `--shallow-instances` | | Collapse internal layers of component instances into props. |
+| `--include-tokens` | | Include the full design token dictionary alongside the node tree. |
+| `--include-ids` | | Keep internal Figma node IDs on each node. |
+| `--pretty` | | Pretty-print JSON with 2-space indentation (default is compact). |
+| `--raw` | | Return the full, unpruned Figma API response. Large; avoid unless debugging. |
+| `--depth <number>` | | Limit node tree traversal depth (e.g. `--depth 2` for an overview). |
+| `--scale <1\|2\|3\|4>` | | Preview render scale (default: `2`). |
+| `--format <png\|svg\|jpg\|pdf>` | | Preview image format (default: `png`). |
+| `--no-variables` | | Skip querying `/variables/local`. |
+| `--help` | `-h` | Show the help message. |
+
+## Output spec schema
+
+Each node keeps only properties that differ from Figma defaults. Hidden layers are dropped. Pure vector groups collapse into a single `VECTOR` node with `isSvg: true`.
+
+| Field | Meaning |
+| :--- | :--- |
+| `name`, `type` | Layer name and node type (`FRAME`, `INSTANCE`, `TEXT`, `VECTOR`, ...). |
+| `bounds` | `{ width, height }` render dimensions. |
+| `layoutMode`, `layoutWrap`, `primaryAxisAlignItems`, `counterAxisAlignItems` | Auto-layout direction and alignment. |
+| `layoutGrow`, `layoutAlign`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | Child sizing constraints. |
+| `padding` / `paddingToken`, `itemSpacing` / `itemSpacingToken` | Spacing values and bound tokens. |
+| `cornerRadius` / `cornerRadiusToken`, `cornerRadii` | Uniform or per-corner radius. |
+| `fills`, `strokes`, `effects`, `opacity` | Paints (hex `color` + optional `token`), borders, shadows/blurs. |
+| `characters`, `typography` | Text content and `fontFamily`, `fontSize`, `fontWeight`, `lineHeightPx`, `letterSpacing`, `textAlignHorizontal`, `textAlignVertical`. |
+| `component`, `props` | Master component `name`/`variant` and normalized instance props. |
+| `children` | Child nodes. |
+| `image` | Present when `-i` was used: preview `path`, or `error`. |
+
+### Resolved design tokens
+
+When a layer is bound to Figma variables, the semantic token name is attached next to the computed fallback value:
+
+```json
+{
+  "name": "Card Container",
+  "type": "FRAME",
+  "layoutMode": "VERTICAL",
+  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
+  "paddingToken": "spacing/md",
+  "itemSpacing": 12,
+  "itemSpacingToken": "spacing/sm",
+  "cornerRadius": 8,
+  "cornerRadiusToken": "radii/lg",
+  "fills": [{ "type": "SOLID", "color": "#1877F2", "token": "colors/brand/primary" }]
+}
+```
+
+### Normalized component instances
+
+Figma property hashes (`Label#12:3`) become clean props linked to the master component:
+
+```json
+{
+  "name": "Submit Button",
+  "type": "INSTANCE",
+  "component": { "name": "Button", "variant": "Variant=Primary, Size=Large" },
+  "props": { "variant": "Primary", "size": "Large", "hasIcon": true, "label": "Confirm Order" },
+  "bounds": { "width": 140, "height": 44 }
+}
+```
+
+## Rate-limit gate internals
+
+The script protects the file quota automatically. No agent action is needed beyond the Zero-Hammer rules in `SKILL.md`.
+
+- **Sliding window**: at most 5 requests per minute per file key (Figma throttles at roughly 10/min).
+- **Pacing**: at least 2.5 s between consecutive requests.
+- **Circuit breaker**: after an HTTP 429, the lockout end time is stored in `~/.figma_ratelimit.json`. Later calls to that file key fail immediately with `FIGMA_CIRCUIT_BREAKER_ACTIVE` and send no network traffic, so the lockout is not extended.

package/figma-extractor/SKILL.md

@@ -1,201 +1,77 @@
 ---
 name: figma-extractor
-description: 'Extract compact JSON node hierarchies, design tokens, component instance props, and automated preview images from Figma using the Figma REST API. Trigger this skill during the planning or specification phase whenever a Figma link is provided or when the user asks to inspect, extract, or sync design specifications and tokens from Figma into .specs/. This skill strictly produces specification artifacts and does not modify application code.'
+description: 'Extracts Figma frames and components into compact JSON spec files (.specs/*.json) with resolved design tokens, normalized component instance props, and optional preview images, using the Figma REST API. Use when the user shares a figma.com link and wants to inspect, extract, document, or plan a design before implementation, or asks to sync Figma variables and design tokens. Produces specification artifacts only and never edits application code. For immediate one-shot code generation from a Figma link, use figma-to-code instead.'
 ---
 
-# Figma Extractor Skill (SDD Spec Ingest)
+# Figma Extractor (SDD Spec Ingest)
 
-Extract design node metadata, component hierarchies, design tokens/variables, and rendered preview images directly from Figma via the Figma REST API into structured specification artifacts (`.specs/`).
+Writes Figma designs to `.specs/<name>.json` (and optionally `.specs/<name>.png`) so a later implementation step can build from a fixed specification. A **spec** is the pruned Figma node tree with resolved tokens and component props.
 
-This skill serves as the **Specification Ingestion Layer** in a **Spec-Driven Development (SDD)** workflow. It is **Design-System Aware**, high-performance, token-efficient, and has zero external dependencies.
+Requires Node.js >= 16.7. The scripts have zero dependencies (no `npm install`).
 
----
-
-## Operational Boundary: Spec Ingestion Only
-
-* **Specification Artifacts Only**: This skill strictly outputs machine-readable design specifications (`.specs/<name>.json`) and visual references (`.specs/<name>.png`).
-* **Zero Application Code Changes**: Do **NOT** create, edit, or modify application source code (`.tsx`, `.vue`, `.html`, `.css`, etc.) while executing this skill.
-* **Hand-off to Implementation**: Once specifications are generated in `./.specs/`, present a summary of the extracted tokens, components, and layout bounds. The implementation phase is handled separately by the developer or a downstream builder skill (such as `figma-node-builder`).
-
----
-
-## Strict Guardrails: No Browser Scraping / Automation
-
-> [!CAUTION]
-> **NEVER use browser tools (Playwright, Puppeteer, Chrome DevTools, `browser_navigate`, `read_browser_page`) on Figma URLs.**
->
-> 1. **Figma Canvas is WebGL/Wasm**: Figma renders design canvas elements inside an HTML5 `<canvas>` via WebAssembly. There are NO inspectable HTML DOM elements for frames, layers, texts, or styles. Browser automation cannot extract Figma nodes or properties.
-> 2. **Never search for local browser binaries**: Do not search OS application directories (e.g., `/Applications`, `Program Files`, `/usr/bin`) or run browser automation scripts.
-> 3. **API Errors Are Final**: If `fetch_figma.js` returns an API error (e.g., 401 Unauthorized, 403 Forbidden, or 429 Rate Limited), **report the error directly to the user**. Guide them to check their `FIGMA_ACCESS_TOKEN`, permissions, or wait out rate limits. Do NOT attempt browser scraping fallbacks.
-
----
+## Boundaries
 
-## Built-in Rate-Limit Gate & Circuit Breaker
+- Output only `.specs/` artifacts. **Never create or edit application code** (`.tsx`, `.vue`, `.html`, `.css`, ...) while using this skill.
+- **Never open Figma URLs with browser tools** (Playwright, Puppeteer, Chrome DevTools). The Figma canvas is WebGL, so there is no DOM to read. Do not search for local browser binaries.
+- **API errors are final**: report them to the user. Never fall back to scraping.
 
-To protect your Figma file quota and prevent lockout penalties, `fetch_figma.js` enforces an automatic safety gate:
-* **Max 5 requests per minute** per file key (sliding window limit).
-* **2.5s inter-request pacing** between consecutive requests.
-* **Persistent Circuit Breaker**: If Figma returns HTTP 429, the script records the lockout time locally in `.figma_ratelimit.json` inside the user's home directory. All future calls to that file key are **immediately blocked with zero network traffic**, preventing Figma from extending the lockout penalty.
+## Workflow
 
-### Agent Behavioral Rules (Zero-Hammer Protocol)
-1. **Single-Shot Execution**: Run `fetch_figma.js` **once** per target frame or component.
-2. **Never Retry on Failure**: If `fetch_figma.js` returns an error, **DO NOT retry in a loop**. Report the error directly to the user.
-3. **Handling `FIGMA_CIRCUIT_BREAKER_ACTIVE`**: If the circuit breaker trips, inform the user that the file key is on cooldown, and suggest duplicating the file in Figma Drafts (Right-click $\rightarrow$ **Duplicate**) to get a fresh URL.
+Copy this checklist and track your progress:
 
----
-
-## Prerequisites
-
-A Figma Access Token (Personal Access Token or OAuth Token) is required.
-
-Configure it using either:
-1. **Environment Variable**:
-   - **macOS / Linux**: `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` (or `FIGMA_TOKEN`)
-   - **Windows (PowerShell)**: `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")` or `$env:FIGMA_ACCESS_TOKEN="figd_your_token_here"` in `$PROFILE`
-2. **Workspace `.env` File**:
-   ```env
-   FIGMA_ACCESS_TOKEN=figd_your_token_here
-   ```
-
-### Corporate Proxy & SSL Certificates
-If you are behind a corporate proxy or firewall with self-signed SSL certificates, enable SSL verification bypass:
-```env
-FIGMA_IGNORE_SSL=true
+```
+Extraction Progress:
+- [ ] 1. Run the extraction (once)
+- [ ] 2. Verify the result
+- [ ] 3. Hand off a summary
 ```
 
----
-
-## Tier 1 Quota Conservation: AST-Only by Default
-
-> [!IMPORTANT]
-> **Figma Starter plans enforce a strict limit of 20 Tier 1 requests/month.**
-> Both `GET /v1/files/:key/nodes` and `GET /v1/images/:key` count as Tier 1 endpoints.
->
-> 1. **Default to AST-only extraction**: Running `--spec <name>` without `-i` consumes **only 1 Tier 1 call**. The JSON AST contains 100% of layout rules (flexbox, padding, gap), dimensions, hex colors, corner radii, and text content needed for code generation.
-> 2. **DO NOT pass `-i` / `--image` by default**: Only add `-i` if the user explicitly requests downloading a visual preview screenshot.
-> 3. **Reuse existing specs**: If `.specs/<name>.json` exists, reuse it with **0 API calls**.
-
----
-
-## Agent Execution Instructions
-
-To extract a Figma frame or component as a specification artifact, run `fetch_figma.js` from this skill's `scripts/` directory:
+**1. Run the extraction** (1 Tier 1 API call):
 
 ```bash
-# Recommended: Atomic extraction (writes ./.specs/<name>.json - 1 Tier 1 call)
 node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" --spec <name>
-
-# Optional: With companion preview image (writes .json and .png - 2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" --spec <name> -i
 ```
 
-**Resolving `<skill-dir>` (Agent-Agnostic)**:
-Substitute `<skill-dir>` with the directory where this skill is installed — **never guess another agent's folder** (always keep double quotes around the script path for Windows/macOS/Linux compatibility):
-- **Standard Skills (`SKILL.md`)**: `<skill-dir>` is the exact parent directory of this `SKILL.md` file.
-- **Cursor Rule (`.cursor/rules/figma-extractor.mdc`)**: `<skill-dir>` is the sibling `.cursor/skills/figma-extractor` directory (replace `rules/figma-extractor.mdc` with `skills/figma-extractor`).
+If `.specs/<name>.json` already exists, the script reuses it with 0 API calls. Pass `--force` only when the user explicitly asks to refresh the spec.
 
----
+**2. Verify the result**
 
-## Usage & Command Formats
+- Success: stdout shows `✔ Saved Figma specification` or `✔ Reusing local Figma specification`.
+- Failure: stderr contains a JSON error payload. Follow [Errors](#errors). Do not retry.
 
-### 1. Atomic Spec Extraction (Recommended SDD Workflow)
+**3. Hand off**: report the spec path and size, the root frame, the main component instances, and the design tokens found. Implementation is handled separately by the developer or by the `figma-node-builder` skill.
 
-Extract node metadata directly into `./.specs/`:
+## Common variants
 
-```bash
-# Atomic AST extraction (1 Tier 1 call - recommended)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card
+| Need | Command suffix |
+| :--- | :--- |
+| Preview PNG (only if the user asks; +1 Tier 1 call) | `--spec <name> -i` |
+| Design tokens dictionary only | `--tokens --spec tokens` |
+| Collapse instance internals into props | `--spec <name> --shallow-instances` |
+| Top-level overview of a large frame | `--spec <name> --depth 2` |
 
-# Optional: With rendered preview image (2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card -i
+All CLI flags, the output spec schema, token setup per OS, and proxy options: see [REFERENCE.md](REFERENCE.md) (located at `<skill-dir>/REFERENCE.md`).
 
-# Shallow instances mode (collapses internal component layers into clean props)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card --shallow-instances
-```
+## Resolving `<skill-dir>`
 
-### 2. Design Tokens Dictionary Mode
+Substitute `<skill-dir>` with the directory where this skill is installed. Never guess another agent's folder, and keep the double quotes around the script path (Windows/macOS/Linux):
 
-```bash
-# Export only the file's design token dictionary (colors, spacing, radii) into ./.specs/tokens.json
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name" --tokens --spec tokens
-```
-
-### 3. CLI Flags Reference
-
-| Flag | Shorthand | Description |
-| :--- | :--- | :--- |
-| `--spec <name>` | | **Atomic SDD mode**: Saves `./.specs/<name>.json` (add `-i` to also download preview PNG). |
-| `--image`, `--download-image` | `-i` | Download and save rendered preview image from Figma (Tier 1 call; optional). |
-| `--image-path <path>` | `-o <path>` | Destination path for saved preview image (e.g. `./.specs/preview.png`). |
-| `--tokens`, `--variables` | | Output only the design token dictionary (colors, spacing, radii). |
-| `--shallow-instances` | | Collapse internal sub-layers of component instances into clean props. |
-| `--pretty` | | Pretty-print JSON with 2-space indentation (default is compact single-line JSON). |
-| `--include-tokens` | | Include full design tokens dictionary alongside node AST. |
-| `--include-ids` | | Retain internal Figma node IDs on each node in the tree. |
-| `--raw` | | Return full, unpruned raw Figma API AST. |
-| `--depth <number>` | | Limit node tree traversal depth (e.g. `--depth 2` for top-level overview). |
-| `--scale <1\|2\|3\|4>` | | Render resolution multiplier for preview images (default: `2`). |
-| `--format <png\|svg\|jpg>` | | Rendered image file format (default: `png`). |
-| `--no-variables` | | Skip querying `/variables/local`. |
-| `--help` | `-h` | Show help message. |
-
----
+- **Standard skills (`SKILL.md`)**: the parent directory of this `SKILL.md` file.
+- **Cursor rule (`.cursor/rules/figma-extractor.mdc`)**: the sibling `.cursor/skills/figma-extractor` directory.
 
-## Output Spec Structure
-
-### 1. Resolved Design Tokens
-When a layer uses Figma variables (design tokens), the extractor attaches semantic token names alongside computed fallback values:
-
-```json
-{
-  "name": "Card Container",
-  "type": "FRAME",
-  "layoutMode": "VERTICAL",
-  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
-  "paddingToken": "spacing/md",
-  "itemSpacing": 12,
-  "itemSpacingToken": "spacing/sm",
-  "cornerRadius": 8,
-  "cornerRadiusToken": "radii/lg",
-  "fills": [
-    {
-      "type": "SOLID",
-      "color": "#1877F2",
-      "token": "colors/brand/primary"
-    }
-  ]
-}
-```
+## Quota rules (Zero-Hammer Protocol)
 
-### 2. Normalized Component Instances & Props
-When an `INSTANCE` node is present, internal property hashes are converted into clean JavaScript props and linked to the master component name:
-
-```json
-{
-  "name": "Submit Button",
-  "type": "INSTANCE",
-  "component": {
-    "name": "Button",
-    "variant": "Variant=Primary, Size=Large"
-  },
-  "props": {
-    "variant": "Primary",
-    "size": "Large",
-    "hasIcon": true,
-    "label": "Confirm Order"
-  },
-  "bounds": { "width": 140, "height": 44 }
-}
-```
+The script enforces a local rate gate and a persistent circuit breaker, but the agent must also follow these rules:
 
----
+1. Run `fetch_figma.js` **once** per target frame or component. **Never retry in a loop.**
+2. **Do not pass `-i`** unless the user explicitly requests a preview image. The JSON spec already contains layout, dimensions, colors, radii, typography, and text.
+3. Figma Starter plans and View seats have very small monthly Tier 1 quotas, so every call matters. Prefer reusing existing specs.
 
-## Error Handling & Troubleshooting
+## Errors
 
-- **Token Expired / Missing (`FIGMA_TOKEN_EXPIRED_OR_INVALID` / `isTokenExpiredOrInvalid`)**:
-  - Alert the user that their Figma access token is missing, invalid, or expired.
-  - Instruct the user to create a token in **Figma Settings → Personal Access Tokens** and configure `FIGMA_ACCESS_TOKEN` in their environment or workspace `.env` file.
-- **Node Not Found**:
-  - Alert the user that the node ID could not be found in the specified file.
-- **Rate Limited (`FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE`)**:
-  - Figma REST API has per-minute and monthly rate limits on Starter plans. If quota is exhausted or circuit breaker trips, inform the user they can export the specification directly via the companion **Figma Node JSON Extractor** desktop plugin (available on [Figma Community](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor)) into `./.specs/<name>.json`.
+| Error code | Action |
+| :--- | :--- |
+| `FIGMA_ACCESS_TOKEN is not set` / `FIGMA_TOKEN_EXPIRED_OR_INVALID` | Tell the user the token is missing, invalid, or expired. They create one in **Figma Settings → Personal Access Tokens** and set `FIGMA_ACCESS_TOKEN` (setup per OS in REFERENCE.md). |
+| Node not found | Report that the `node-id` does not exist in the file. |
+| `FIGMA_SSL_CERTIFICATE_ERROR` | Corporate proxy or self-signed certificate: suggest `FIGMA_IGNORE_SSL=true` in `.env`. |
+| `FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE` | Report the cooldown. Suggest duplicating the file in Figma Drafts (Right-click → **Duplicate**) for a fresh URL, or exporting the selection with the companion [Figma Node JSON Extractor](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor) plugin into `.specs/<name>.json`. |