extract-api

# Extract API Data

Interpretation-only companion to `create-api`. This skill **does not extract data from Figma**. It reads `{cachePath}/{componentSlug}-_base.json` (produced by the uSpec Extract Figma plugin), applies the same reasoning layer as `create-api`, and writes the normalized `ApiOverviewData` JSON to disk for the `create-component-md` orchestrator to consume.

**Quality contract:** every reasoning step (context gathering from `_base.json`, override promotion pass, audit) mirrors `create-api/SKILL.md`. Any improvement to API-extraction quality must be made in both places.

**Batch-mode contract.** This skill MUST NOT call `AskQuestion`, prompt for confirmation, or pause for user input. On ambiguous evidence, emit the best-effort structured output (with `_deltaExtractions[]` logged if a delta fired). On missing evidence that cannot be resolved, abort with a single-line diagnostic pointing at the missing `_base.json` field. No mid-interpretation clarifications.

## Invocation Contract

The orchestrator calls this skill with these inputs (already resolved — do NOT re-parse URLs or re-read `uspecs.config.json`):

- `componentSlug` — filename-safe slug
- `cachePath` — cache directory, typically `.uspec-cache/{componentSlug}/`
- `optionalContext` — free-form string from the user (may be `"none"`)
- `mcpProvider` — `figma-console` or `figma-mcp` (only needed if a Step 3-delta escape hatch fires AND a live Figma link was provided to the orchestrator)
- `deltaAvailable` — boolean. When the orchestrator received **only** a `baseJsonPath` (no `figmaLink`), this is `false` and the Step 3-delta escape hatch must not fire; log the gap in `data._deltaExtractions[]` with `unavailable: "no-figma-link"` and continue with best-effort output.

`fileKey` and `nodeId` are **not** pass-through parameters. Read them from `{cachePath}/{componentSlug}-_base.json._meta.fileKey` and `_meta.nodeId` at the start of Step 1 — `_base.json` is the single source of truth for them.

**Output:**

- Writes `{cachePath}/{componentSlug}-api.json` containing the full `ApiOverviewData` object.
- Writes `{cachePath}/{componentSlug}-api-dictionary.json` — a canonical vocabulary projected from the api.json, consumed by the downstream `extract-structure`, `extract-color`, and `extract-voice` specialists. See Step 7.5 and the **ApiDictionary artifact** section in [api/agent-api-instruction.md]({{ref:api/agent-api-instruction.md}}).
- Returns a single-line summary to the orchestrator: `"API extracted: N properties, M sub-components, K examples → {path} (+ dictionary at {dictionaryPath})"`.
- Never creates or mutates Figma nodes (not even during the delta escape hatch — delta is read-only).

## MCP Adapter

This skill typically makes **zero** MCP calls — it reads `_base.json` from disk. The adapter table below applies only to the optional Step 3-delta escape hatch.

| Operation | `figma-console` | `figma-mcp` |
|-----------|-----------------|-------------|
| Execute Plugin JS (delta only) | `figma_execute` with `code` | `use_figma` with `fileKey`, `code`, `description` |

For `figma-mcp` delta scripts, always include the page-focus preamble immediately after `getNodeByIdAsync`:

```javascript
let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);
```

## Workflow

```
Task Progress:
- [ ] Step 1: Read instruction file
- [ ] Step 2: Load _base.json and optionalContext
- [ ] Step 3: Build working evidence set (from _base.json fields only)
- [ ] Step 3-delta: OPTIONAL — read-only Figma call if a fact is genuinely missing
- [ ] Step 4: Identify properties and sub-components (Override Promotion Pass)
- [ ] Step 5: Generate ApiOverviewData object
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache
- [ ] Step 7.5: Project `ApiDictionary` from the finalized data and write `{slug}-api-dictionary.json`
- [ ] Step 8: Return one-line summary
```

### Step 1: Read Instructions

Read [api/agent-api-instruction.md]({{ref:api/agent-api-instruction.md}}). This is the **same** instruction file used by `create-api` — it defines the `ApiOverviewData` schema, property classification rules, naming conventions, and audit checklists.

#### Rendering-only sections to skip

The shared instruction file describes both extraction and Figma rendering. This skill only performs interpretation — ignore guidance in the sections below. The data schema and audit checklists still apply.

- **Any phrase like "passed directly into Figma template placeholders — no JSON output is needed"** — inverted for this skill: we **do** output JSON to disk. Keep the schema; discard the "no JSON" framing.
- **§Configuration Examples — prose about how `nestedOverrides`, `textOverrides`, and `slotInsertions` are applied via `setProperties()` or inserted into SLOT nodes** — describes the rendering path. The fields themselves are part of `ApiOverviewData` and must still be populated.
- **§Common Mistakes — bullets describing rendering-path failures** (e.g., "preview will show an empty slot", "SKILL.md script handles the replacement automatically") — cautions for the rendering skill, not interpretation. Data-level mistakes in the same section still apply.

Note: Fields that look like rendering config but are part of the output schema (e.g., `slotInsertions`, `textOverrides`, `nestedOverrides`, `variantProperties`) must still be populated.

### Step 2: Load `_base.json`

Read `{cachePath}/{componentSlug}-_base.json` with the `Read` tool. If the file is missing, or if any of the sections listed in Step 3 below are `null` / missing, abort with a clear diagnostic asking the user to re-run the uSpec Extract plugin.

The file schema is defined in [figma-plugin/docs/base-json-schema.md]({{repo:figma-plugin/docs/base-json-schema.md}}). Familiarize yourself with the top-level keys:

- `component` — component name + is-set flag
- `variantAxes` — `[{ name, options, defaultValu