Skip to main content
Having trouble creating a spec? Find solutions below based on where the issue occurs.
uSpec specs are generated by an LLM. Always review the output for accuracy. The agent can misinterpret component structure, assign incorrect token names, or produce incomplete specs. Treat generated specs as a strong first draft that needs a human review pass before shipping.
Symptom: You type a prompt but the skill doesn’t run.First, run npx uspec-skills doctor from your project root. It reports missing skills, missing references, or broken links and tells you exactly what to fix.
  • Use the direct reference format: @create-voice instead of typing keywords
  • Confirm your project folder is open in Cursor (the same folder where you ran npx uspec-skills init)
  • Verify .cursor/skills/ contains the skill folders. If empty, run npx uspec-skills install --platform cursor
  • Restart Cursor if skills don’t autocomplete
Symptom: The generated spec is missing information or has incorrect values.Solutions:
  • Make sure you’re using a high-context model — 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 skill instructions and produce incomplete specs.
  • Start a new agent session for each prompt to give the model full context capacity
  • Add more context to your prompt: describe all states, variants, and behaviors
  • Specify states explicitly (e.g., “enabled, hovered, pressed, disabled”)
  • Include a screenshot for complex components
  • Mention any non-obvious interactions or behaviors
Symptom: The agent stops generating before finishing, or the output is truncated or malformed.Solutions:
  • Switch to a higher-context model — uSpec skills are token-intensive
  • Start a new agent session instead of continuing in an existing conversation — accumulated history reduces available context
  • If the issue persists, try running the skill again in a fresh session with a simpler prompt first
Symptom: Typing @create- doesn’t show skill suggestions.Solutions:
  • Confirm your project folder is open in Cursor (the folder where you ran npx uspec-skills init)
  • Verify .cursor/skills/ contains the skill folders. If empty, run npx uspec-skills install --platform cursor to repair the install
  • Restart Cursor after running npx uspec-skills init or npx uspec-skills install

​
Improving output quality

If the agent’s output is incomplete or doesn’t match your expectations, the issue is usually missing context rather than a technical problem.

​
Output is incomplete or missing states

A render skill can only document what the .md records or what you describe. If states, variants, or behaviors are missing, they were usually not captured when you generated the .md. Fix it at the source:
  • Add context when generating the .md: list all states (enabled, hovered, pressed, disabled, selected, loading) in the plugin’s design-intent field or your create-component-md prompt, then regenerate
  • Describe behavioral modes: fill vs. hug width, truncation rules, multi-select behavior
  • Mention invisible constraints: tap target minimums, aspect ratios, focus order preferences

​
Output seems generic or empty

If the output has the right structure but lacks detail:
  • Check the .md is complete: open the component .md and confirm the relevant section is populated. If it’s thin, regenerate it with create-component-md and more context
  • Check your MCP connection (render skills only): ask your agent to verify the Figma connection (e.g., “Check Figma status” for Console MCP, or “List pages in my file” with a link for native MCP). If the connection is down, the agent can’t render the frame
  • Verify the render destination: make sure any destination node-id points to where you want the annotation, not a parent frame

​
Re-prompting strategies

When the first output isn’t quite right:
  1. Identify what’s missing: Is it a state? A variant? A specific part?
  2. Decide where it belongs: if the .md is missing it, regenerate the .md; if only the render is off, re-run the render skill
  3. Be specific: instead of “include all states,” say “include enabled, disabled, and loading states”
If the output has the right structure but rendering fails, the issue is likely a connection problem, not a prompt problem. Check your MCP connection first.

​
Component structure matters

uSpec reads your component tree programmatically. The cleaner your Figma components are structured, the more accurate the output. A well-organized component gives the agent the information it needs to produce correct specs on the first run.

Do

  • Use auto-layout for all layout containers
  • Name every layer descriptively (“Leading icon”, “Primary label”, “Helper text”)
  • Use component sets with clear variant axis naming
  • Bind colors and dimensions to design tokens and variables
  • Keep your layer hierarchy flat and purposeful

Don't

  • Leave default names like “Frame 427”, “Group 12”, or “Rectangle 89”
  • Use absolute positioning where auto-layout would work
  • Nest elements deeply without purpose (wrapper frames inside wrapper frames)
  • Mix unrelated elements in a single unnamed frame
  • Use flattened vectors for elements that should be component instances
Think of it this way: if another designer can’t understand your component by reading the layer panel alone, the agent will struggle too. Layer names become table labels, auto-layout informs spacing specs, and token bindings drive color annotations.
uSpec is an actively developed open-source project. We’re improving the skills, adding new spec types, and refining output quality continuously. If you encounter an issue or have an idea for improvement, open an issue on GitHub — contributions and feedback are welcome.

​
Still stuck?

Get help

Open an issue on GitHub for questions or bug reports.

Check setup

Review the setup steps to make sure everything is configured correctly.