Skip to main content
This page covers everything you need to go from zero to your first generated spec.
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.

Setup instructions

Install your AI agent, connect Figma, and configure your template library.

Create your first spec

Prompt format, available skills, and tips for better output.

​
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 — no local build required. The Component Markdown install guide covers it in detail.
  3. Figma MCP: the bridge that lets the create-* skills render annotation frames back into your Figma file (either Figma Console MCP or native Figma MCP)
  4. Template library: the Figma file containing the documentation templates those render skills clone from
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.
You only need to complete this setup once. After that, you can generate specs anytime by opening the project in your agent host.

​
1. Set up your agent host

Cursor is an AI code editor. All uSpec skills run inside Cursor’s chat.
1

Download Cursor

Go to cursor.com and download the app for your platform.
2

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.
3

Install uSpec

In the project’s terminal, run:
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.
4

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.
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.
Verify skills are available by typing @create-voice or @create-component-md in Cursor’s chat. Either should autocomplete to the skill file.
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.
npx uspec-skills install --platform claude-code
npx uspec-skills install --platform codex

​
2. Set up Figma MCP

uSpec supports two Figma MCP providers. Choose one based on your setup:
MCP providers update their setup instructions frequently. The configuration examples below are a starting point — always check the provider’s documentation for the latest installation steps and options:
The Figma Console MCP (by Southleft) connects your agent to Figma Desktop via a Desktop Bridge plugin, giving it access to component data, variables, styles, and screenshots.

​
Get a Figma personal access token

1

Go to the Figma API settings

Open figma.com/developers/api#access-tokens
2

Create a token

Click “Get personal access token”, enter a description like Figma Console MCP, and copy the token. It starts with figd_.
Copy the token immediately. You won’t be able to see it again after closing the dialog.

​
Configure the MCP in your agent

Add the Figma Console MCP to your Cursor MCP configuration:
{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}
Add this to your Cursor MCP settings (global or project-level .cursor/mcp.json).
This uses the NPX setup, which gives you all 59+ tools including design creation and variable management. Setup instructions may change between releases — for the latest configuration options, alternative installation methods, and troubleshooting, see the Figma Console MCP documentation.

​
Connect to Figma Desktop

The Desktop Bridge plugin provides real-time access to your Figma file data. It comes bundled with the Figma Console MCP.
1

Install the Desktop Bridge plugin

The Desktop Bridge plugin is included in the figma-console-mcp npm package. After running npx figma-console-mcp@latest, find the plugin at node_modules/figma-console-mcp/figma-desktop-bridge/manifest.json. In Figma Desktop, go to Plugins → Development → Import plugin from manifest… and select this file.
2

Run the plugin

Open the Desktop Bridge plugin in your Figma file. It auto-connects via WebSocket. No special launch flags needed.
3

Verify the connection

In your agent, type: “Check Figma status”The agent should confirm an active connection.
When the connection is active, your agent can read Figma file data, take screenshots, and access variables and styles.
Test your MCP connection before proceeding. Run a simple command in your agent to confirm Figma access is working. If the MCP isn’t connected, firstrun will fail when it tries to read your template library.
Open the Desktop Bridge plugin in Figma, then ask your agent: “Check Figma status”. You should see an active connection. If it doesn’t connect, see the Figma Console MCP documentation for setup verification.

​
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.
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.

​
Get the template file

uSpec renders documentation using Figma component templates. You need to add the templates to your Figma organization before running firstrun.
Uber designers can skip this — the internal template library is already configured. When firstrun asks for a library link, type “skip”.
1

Open the Community file

Go to the uSpec Template on Figma Community.
2

Duplicate to your drafts

Click Open in Figma to add a copy to your drafts.
3

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.
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.

​
Run the firstrun skill

1

Confirm your Figma MCP is connected

If using Figma Console MCP: Open the Desktop Bridge plugin in Figma Desktop for your template library file. If using Figma MCP (Native): Ensure the MCP server is running and your access token is configured.
2

Run firstrun

In Cursor’s chat, type:
@firstrun
3

Answer the library prompt

The agent asks one question:Library link — Paste the link to your Figma template library (Uber designers can type “skip”).Your Figma MCP and platform were already configured by npx uspec-skills init, so the agent reads them from uspecs.config.json instead of asking again.
4

Wait for confirmation

The agent extracts component keys from your templates and merges them into uspecs.config.json automatically.
When you see “Setup complete! You are now ready to use uSpec”, your environment and template library are configured.

​
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 (see the Component Markdown install guide)
  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 is connected (Desktop Bridge plugin for Console MCP, or native MCP server running)
  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. 
@create-component-md baseJsonPath=~/Downloads/text-field-_base.json
This writes ./components/text-field.md. That file is the input for every render skill below.
See the Component Markdown guide for the full plugin install, usage, and cost walkthrough.

​
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.
Prompt format showing skill name, component .md path, and additional context
@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.

​
Available skills

The skills split into two groups based on their place in the pipeline. Stage 1 — produces the .md (your source of truth):
SkillWhat it generates
create-component-mdSingle self-contained .md covering API, structure, color tokens, and screen-reader behavior. Takes a _base.json from the uSpec Extract Figma plugin. Full guide →
Stage 2 — render a section of the .md into Figma:
SkillWhat it renders
create-anatomyNumbered markers on a component with an attribute table
create-propertyVariant axis and boolean toggle exhibits with instance previews
create-voiceScreen reader specs for VoiceOver, TalkBack, and ARIA
create-colorColor token annotations for all elements and states
create-apiProperty tables with values, defaults, and examples
create-structureDimensional specs for spacing, padding, and sizing
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.
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.

​
What happens when you run a skill

Each stage runs a different pipeline.
1

Preflight

The orchestrator validates _base.json against the plugin schema and stages it into .uspec-cache/{componentSlug}/.
2

API dictionary

extract-api runs first and writes api-dictionary.json. The dictionary keeps the three downstream specialists aligned on property names and states.
3

Parallel fan-out

extract-structure, extract-color, and extract-voice run as three parallel subagents in a single batch.
4

Reconciliation

The orchestrator compares specialist outputs for typed disagreements and re-dispatches the owning specialist when needed.
5

Render

The renderer fills a single Markdown template with the reconciled data and writes components/{componentSlug}.md under your working directory.
If a new .md appears under ./components/ in your working directory, your setup is working correctly.

​
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. For Console MCP, run the Desktop Bridge plugin in Figma. For native MCP, ensure the server is running. Verify the connection in your agent before starting. If the agent can’t reach Figma, the render will fail.
  • Run one agent per Figma file at a time. The MCP supports multiple connections, but all agents share one active page and file context. 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.
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.

​
Setup issues

Run npx uspec-skills doctor from your project root. It reports any missing skills, missing references, or broken links.
  • 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.
Figma Console MCP:
  • Confirm Figma Desktop is running (not the web version)
  • Close and reopen the Desktop Bridge plugin in Figma
  • Make sure only one instance of Figma Desktop is running
  • Check that your Figma access token is configured correctly in your agent’s MCP settings
Figma MCP (Native):
  • Confirm the MCP server is running (check your terminal or agent MCP panel)
  • Verify your FIGMA_API_KEY is set correctly in your MCP configuration
  • Test with a simple command like “List pages in my file” with a Figma link
For issues with skills or Figma connection, see the Troubleshooting guide.