> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uspec.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Set up your AI agent, the uSpec Extract plugin, and Figma, then run the pipeline: generate a Component Markdown spec and render it into Figma

This page covers everything you need to go from zero to your first generated spec.

<Info>
  Every spec flows through one pipeline: the **uSpec Extract** plugin captures your component, `create-component-md` turns that capture into a `.md` spec, and the `create-*` skills render that `.md` into Figma. The full plugin install and `create-component-md` walkthrough lives on the [Component Markdown page](/specs/component-md).
</Info>

<Warning>
  **Before you start:** Make sure your agent has an active Figma MCP connection if you plan to run `firstrun` or render specs into Figma. Install and configure Figma MCP by following its current setup instructions. uSpec records your MCP choice, but it does not install or configure the connection for you.
</Warning>

<CardGroup cols={2}>
  <Card title="Setup instructions" icon="download" href="#setup-instructions">
    Install your AI agent, connect Figma, and configure your template library.
  </Card>

  <Card title="Create your first spec" icon="rocket" href="#create-your-first-spec">
    Prompt format, available skills, and tips for better output.
  </Card>
</CardGroup>

***

## Setup instructions

uSpec runs one pipeline end to end: extract a component, generate its `.md` spec, then render that spec into Figma. To run the full pipeline you need four pieces, all set up once:

1. **AI agent host**: the coding environment that runs uSpec skills (Cursor, Claude Code, or Codex)
2. **uSpec Extract plugin**: the Figma Community plugin that captures a component to `_base.json`, which `create-component-md` turns into the `.md` spec. Install it from the [Figma Community](https://www.figma.com/community/plugin/1635184425006534227/uspec-extract) — no local build required. The [Component Markdown install guide](/specs/component-md#what-you-need) covers it in detail.
3. **Figma MCP**: an active connection that lets the `create-*` skills render annotation frames back into your Figma file
4. **Template library**: the Figma file containing the documentation templates those render skills clone from

<Note>
  `create-component-md` only needs the agent host and the uSpec Extract plugin — it does not use the Figma MCP or `firstrun`. The MCP and template library are for the `create-*` render skills, which read the `.md` and draw annotations in Figma.
</Note>

<Note>
  You only need to complete this setup once. After that, you can generate specs anytime by opening the project in your agent host.
</Note>

### 1. Set up your agent host

<Tabs>
  <Tab title="Cursor">
    Cursor is an AI code editor. All uSpec skills run inside Cursor's chat.

    <Steps>
      <Step title="Download Cursor">
        Go to [cursor.com](https://cursor.com) and download the app for your platform.
      </Step>

      <Step title="Open your project in Cursor">
        uSpec installs into your existing project — you do not need to clone the uSpec repo. Open any folder where you want to use uSpec.
      </Step>

      <Step title="Install uSpec">
        In the project's terminal, run:

        ```bash theme={null}
        npx uspec-skills init
        ```

        Choose **Cursor** when prompted. The CLI installs all skills into `.cursor/skills/` and references into `./references/`, then writes `uspecs.config.json`.
      </Step>

      <Step title="Select the right model">
        uSpec skills are token-intensive and require a model with high context capacity. In Cursor's chat, select **OpenAI GPT 5.4 High** or **Opus 4.6 High** or above. OpenAI 5.4 High is more economical to use.

        <Warning>
          Lower-capacity models may truncate instructions mid-skill, producing incomplete or broken specs. **OpenAI GPT 5.4 High** or **Opus 4.6 High** is the minimum recommended model.
        </Warning>
      </Step>
    </Steps>

    <Check>
      Verify skills are available by typing `@create-voice` or `@create-component-md` in Cursor's chat. Either should autocomplete to the skill file.
    </Check>
  </Tab>

  <Tab title="Claude Code">
    Claude Code is Anthropic's terminal-based coding agent.

    <Steps>
      <Step title="Install Claude Code">
        Follow the [Claude Code installation guide](https://code.claude.com/docs/en/overview) to install the CLI.
      </Step>

      <Step title="Open your project">
        uSpec installs into your existing project. `cd` into any folder where you want to use uSpec.
      </Step>

      <Step title="Install uSpec">
        ```bash theme={null}
        npx uspec-skills init
        ```

        Choose **Claude Code CLI** when prompted. The CLI installs all skills into `.claude/skills/` and references into `./references/`, then writes `uspecs.config.json`.
      </Step>

      <Step title="Select the right model">
        Use **OpenAI GPT 5.4 High** or **Opus 4.6 High** or above. uSpec skills are token-intensive and require high context capacity. OpenAI 5.4 High is more economical to use.
      </Step>
    </Steps>

    <Check>
      Run `claude` in the project directory. Claude Code should discover the `firstrun` skill from `.claude/skills/firstrun/`.
    </Check>
  </Tab>

  <Tab title="Codex">
    Codex is OpenAI's coding agent.

    <Steps>
      <Step title="Install Codex">
        Follow the [Codex setup guide](https://developers.openai.com/codex/) to install the CLI.
      </Step>

      <Step title="Open your project">
        uSpec installs into your existing project. `cd` into any folder where you want to use uSpec.
      </Step>

      <Step title="Install uSpec">
        ```bash theme={null}
        npx uspec-skills init
        ```

        Choose **Codex CLI** when prompted. The CLI installs all skills into `.agents/skills/` and references into `./references/`, then writes `uspecs.config.json`.
      </Step>

      <Step title="Select the right model">
        Use **OpenAI GPT 5.4 High** or **Opus 4.6 High** or above. uSpec skills are token-intensive and may produce incomplete output with lower-capacity models. OpenAI 5.4 High is more economical to use.
      </Step>
    </Steps>

    <Check>
      Codex should discover the `firstrun` skill from `.agents/skills/firstrun/`. Type `$firstrun` to get started, or use `/skills` to browse what's available.
    </Check>
  </Tab>
</Tabs>

<Tip>
  **Using more than one agent host?** Run `npx uspec-skills install --platform <name>` for each additional host in the same project. The CLI installs into the host's directory without touching the others, so you can have `.cursor/skills/`, `.claude/skills/`, and `.agents/skills/` side by side.

  ```bash theme={null}
  npx uspec-skills install --platform claude-code
  npx uspec-skills install --platform codex
  ```
</Tip>

***

### 2. Set up Figma MCP

Figma MCP is an external prerequisite for `firstrun` and every skill that renders documentation into Figma. Install and configure it in your agent host before continuing. Because MCP setup changes independently of uSpec, follow the current instructions provided with your Figma MCP.

<Steps>
  <Step title="Install and configure Figma MCP">
    Complete the setup instructions for your agent host and Figma MCP.
  </Step>

  <Step title="Verify the connection">
    Open the Figma file you want to use, then ask your agent to confirm that it can access the file.
  </Step>
</Steps>

<Check>
  Continue when your agent confirms that the Figma MCP connection is active.
</Check>

***

### 3. Run firstrun

The `firstrun` skill configures your Figma template library. Platform selection and skill installation are handled by `npx uspec-skills init` (Step 1) — `firstrun` only handles the Figma side.

<Note>
  You only need to run `firstrun` once per project. It reads your platform and MCP choice from `uspecs.config.json` and uses them to extract template keys from your Figma library.
</Note>

#### Get the template file

uSpec renders documentation using Figma component templates. You need to add the templates to your Figma organization before running `firstrun`.

<Note>
  Uber designers use the built-in template library. When `firstrun` asks whether you are an Uber employee, answer **Yes**.
</Note>

<Steps>
  <Step title="Open the Community file">
    Go to the [uSpec Template](https://www.figma.com/community/file/1603925462078533207/uspec-template) on Figma Community.
  </Step>

  <Step title="Duplicate to your drafts">
    Click **Open in Figma** to add a copy to your drafts.
  </Step>

  <Step title="Publish as a library">
    Move the file to your team or organization project, then publish it as a library:

    1. Open the file in Figma
    2. Go to the **Assets** panel
    3. Click the book icon and select **Publish library**
    4. Confirm the publish

    This makes the templates available for uSpec to import.
  </Step>
</Steps>

<Tip>
  If you're working solo or testing, you can skip publishing and use the file directly. The `firstrun` skill will still work as long as you have the file open.
</Tip>

#### Run the firstrun skill

<Steps>
  <Step title="Confirm your Figma MCP is connected">
    Open your Figma template library file and make sure your agent can access it through Figma MCP.
  </Step>

  <Step title="Run firstrun">
    <Tabs>
      <Tab title="Cursor">
        In Cursor's chat, type:

        ```
        @firstrun
        ```
      </Tab>

      <Tab title="Claude Code">
        Invoke the skill directly or let Claude auto-discover it:

        ```
        /firstrun
        ```
      </Tab>

      <Tab title="Codex">
        Invoke the skill with `$` or let Codex match it from the description:

        ```
        $firstrun
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Answer the library prompt">
    When the agent asks whether you are an Uber employee:

    * Answer **Yes** to use the built-in Uber template library.
    * Answer **No**, then paste the link to your Figma template library.

    `npx uspec-skills init` recorded your Figma MCP choice and platform in `uspecs.config.json`, so the agent does not ask for them again.
  </Step>

  <Step title="Wait for confirmation">
    The agent extracts component keys from your templates and merges them into `uspecs.config.json` automatically.
  </Step>
</Steps>

<Check>
  When you see "Setup complete! You are now ready to use uSpec", your environment and template library are configured.
</Check>

***

## Create your first spec

The pipeline has two stages. Stage 1 produces the `.md` spec; stage 2 renders any section of it into Figma. Run them in order.

**Before stage 1 (generate the `.md`):**

1. Your agent host is open in the project where you ran `npx uspec-skills init` and skills are available
2. The **uSpec Extract** plugin is installed from the [Figma Community](https://www.figma.com/community/plugin/1635184425006534227/uspec-extract) (see the [Component Markdown install guide](/specs/component-md#what-you-need))
3. You have a `_base.json` file produced by running the plugin on a component

**Before stage 2 (render into Figma):**

1. You have a component `.md` from stage 1
2. Your Figma MCP connection is active
3. You've run `firstrun`. The template library is configured (`uspecs.config.json` has your template keys and MCP provider)

### Stage 1: generate the Component Markdown

Reference `create-component-md` and point it at the `_base.json` produced by the plugin. No Figma link is required — the plugin capture is the input.

<Tabs>
  <Tab title="Cursor">
    ```
    @create-component-md baseJsonPath=~/Downloads/text-field-_base.json
    ```
  </Tab>

  <Tab title="Claude Code">
    ```
    /create-component-md baseJsonPath=~/Downloads/text-field-_base.json
    ```
  </Tab>

  <Tab title="Codex">
    ```
    $create-component-md baseJsonPath=~/Downloads/text-field-_base.json
    ```
  </Tab>
</Tabs>

This writes `./components/text-field.md`. That file is the input for every render skill below.

<Tip>
  See the [Component Markdown guide](/specs/component-md) for the full plugin install, usage, and cost walkthrough.
</Tip>

### Stage 2: render a section into Figma

Reference a `create-*` skill, pass the component `.md`, and add anything the agent can't infer from the spec: which Figma node to render next to, or behavior and interaction details. The skill reads the `.md` — it does not re-extract from a Figma link.

<Frame>
  <img src="https://mintcdn.com/personal-49ab26fb/nHZK0nwAJ_L22G1A/images/example-skill.png?fit=max&auto=format&n=nHZK0nwAJ_L22G1A&q=85&s=edb0522a63cf15117562934a2110dd10" alt="Prompt format showing skill name, component .md path, and additional context" width="1326" height="203" data-path="images/example-skill.png" />
</Frame>

<Tabs>
  <Tab title="Cursor">
    ```
    @create-voice ./components/text-field.md

    Render next to the component at https://www.figma.com/design/abc123/Components?node-id=100:200
    Focus moves label, then field, then the clear button.
    ```
  </Tab>

  <Tab title="Claude Code">
    ```
    /create-voice ./components/text-field.md

    Render next to the component at https://www.figma.com/design/abc123/Components?node-id=100:200
    Focus moves label, then field, then the clear button.
    ```

    You can also skip the `/` and describe what you need. Claude auto-discovers the skill from its description.
  </Tab>

  <Tab title="Codex">
    ```
    $create-voice ./components/text-field.md

    Render next to the component at https://www.figma.com/design/abc123/Components?node-id=100:200
    Focus moves label, then field, then the clear button.
    ```

    Type `$` to mention a skill explicitly, or use `/skills` to browse what's available. Codex can also match skills implicitly from their description.
  </Tab>
</Tabs>

### Available skills

The skills split into two groups based on their place in the pipeline.

**Stage 1 — produces the `.md` (your source of truth):**

| Skill                 | What it generates                                                                                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create-component-md` | Single self-contained `.md` covering API, structure, color tokens, and screen-reader behavior. Takes a `_base.json` from the uSpec Extract Figma plugin. [Full guide →](/specs/component-md) |

**Stage 2 — render a section of the `.md` into Figma:**

| Skill              | What it renders                                                 |
| ------------------ | --------------------------------------------------------------- |
| `create-anatomy`   | Numbered markers on a component with an attribute table         |
| `create-property`  | Variant axis and boolean toggle exhibits with instance previews |
| `create-voice`     | Screen reader specs for VoiceOver, TalkBack, and ARIA           |
| `create-color`     | Color token annotations for all elements and states             |
| `create-api`       | Property tables with values, defaults, and examples             |
| `create-structure` | Dimensional specs for spacing, padding, and sizing              |

<Note>
  Each stage-2 skill takes the component `.md` from stage 1 as its required input and renders that section as Figma annotations. They do not re-extract from a Figma link.
</Note>

**Exception — `create-motion`:** renders an animation timeline and easing spec from an After Effects export. It is the one skill outside the Component Markdown pipeline. See the [Motion guide](/specs/motion).

### What happens when you run a skill

Each stage runs a different pipeline.

<Tabs>
  <Tab title="Stage 1: create-component-md">
    <Steps>
      <Step title="Preflight">
        The orchestrator validates `_base.json` against the plugin schema and stages it into `.uspec-cache/{componentSlug}/`.
      </Step>

      <Step title="API dictionary">
        `extract-api` runs first and writes `api-dictionary.json`. The dictionary keeps the three downstream specialists aligned on property names and states.
      </Step>

      <Step title="Parallel fan-out">
        `extract-structure`, `extract-color`, and `extract-voice` run as three parallel subagents in a single batch.
      </Step>

      <Step title="Reconciliation">
        The orchestrator compares specialist outputs for typed disagreements and re-dispatches the owning specialist when needed.
      </Step>

      <Step title="Render">
        The renderer fills a single Markdown template with the reconciled data and writes `components/{componentSlug}.md` under your working directory.
      </Step>
    </Steps>

    <Check>
      If a new `.md` appears under `./components/` in your working directory, your setup is working correctly.
    </Check>
  </Tab>

  <Tab title="Stage 2: create-* render skill">
    <Steps>
      <Step title="Read the .md">
        The skill parses the component `.md` you pass in for the section it owns (anatomy, API, color, structure, properties, or voice) plus the render-meta that ties each section to Figma nodes.
      </Step>

      <Step title="Template import">
        The agent imports the matching documentation template into your current Figma page.
      </Step>

      <Step title="Content population">
        Component name, guidelines, properties, and tables are filled in from the `.md` — no re-extraction from the live file.
      </Step>

      <Step title="Section cloning">
        Sections are cloned for each variant, state, or property recorded in the `.md`.
      </Step>

      <Step title="Validation">
        A screenshot is captured and verified. Issues are fixed automatically.
      </Step>
    </Steps>

    <Check>
      If a documentation frame appears in your Figma file, your setup is working correctly.
    </Check>
  </Tab>
</Tabs>

### Tips for better output

* **Be specific about states**: Mention all states (selected, disabled, expanded) when you generate the `.md` — either in the plugin's design-intent field or in your `create-component-md` prompt. The render skills can only show what the `.md` records.
* **Describe the parts**: For complex components, describe the interactive elements (e.g., *"This is a tooltip. The bell icon triggers it, and the bubble appears on hover and focus."*)

***

## Best practices

### Do (all skills)

* **Start a new agent session for every prompt.** Each skill consumes significant context. A fresh session ensures the model has full capacity and avoids degraded output.
* **Run on a high-capacity model.** Render skills work on OpenAI GPT 5.4 High or Opus 4.6 High. `create-component-md` uses parallel subagents and needs Opus 4.7 High or better.

### Do (stage 2 render skills)

* **Generate the `.md` first.** Every `create-*` render skill takes a component `.md` as its required input. Run `create-component-md` before reaching for any of them.
* **Confirm the MCP connection before running a skill.** Ask your agent to verify that it can access your Figma file. If the agent can't reach Figma, the render will fail.
* **Run one agent per Figma file at a time.** Concurrent writes can conflict and corrupt the output. Finish one render before starting the next.

### Don't (stage 2 render skills)

* **Interact with the Figma frame while a skill is running.** The agent writes to the frame in multiple steps. Clicking, selecting, or editing mid-generation can break node references and corrupt the output.
* **Run multiple agents on the same file simultaneously.** They override each other's page navigation and produce corrupted specs. If you need parallel generation, use separate Figma files.

### Don't (all skills)

* **Reuse a long chat session for multiple skills.** Accumulated history reduces available context and degrades output quality. Start fresh each time.

<Note>
  `create-component-md` does not write to Figma, so the Figma-interaction caveats above do not apply to stage 1. You can run multiple `create-component-md` skills in parallel against different components safely.
</Note>

***

## Setup issues

<AccordionGroup>
  <Accordion title="Skills not loading">
    Run `npx uspec-skills doctor` from your project root. It reports any missing skills, missing references, or broken links.

    <Tabs>
      <Tab title="Cursor">
        * Confirm the project folder is open in Cursor (not a parent directory)
        * Check that `.cursor/skills/` contains the skill folders. If empty, re-run `npx uspec-skills install --platform cursor`.
        * Restart Cursor after running `npx uspec-skills init` so it picks up the new skills.
      </Tab>

      <Tab title="Claude Code">
        * Confirm you're running `claude` from the project root where you ran `npx uspec-skills init`
        * Check that `.claude/skills/` contains the skill folders. If empty, re-run `npx uspec-skills install --platform claude-code`.
      </Tab>

      <Tab title="Codex">
        * Confirm you're in the project directory where you ran `npx uspec-skills init`
        * Check that `.agents/skills/` contains the skill folders. If empty, re-run `npx uspec-skills install --platform codex`.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Figma MCP not connecting">
    * Confirm Figma and your Figma MCP are running
    * Check the MCP connection and credentials in your agent host
    * Ask your agent to verify that it can access your Figma file
    * Follow the current troubleshooting instructions provided with your Figma MCP
  </Accordion>
</AccordionGroup>

<Note>
  For issues with skills or Figma connection, see the [Troubleshooting guide](/help/troubleshooting).
</Note>