Base UI Skills

[ggomarighetti]

Feature request

Summary

Based on the release of skills.sh, add/publish a skills.md file to explicitly document correct Base UI usage patterns—specifically how to handle slots, the render prop, and component composition—to mainly prevent confusion with other headless libraries.

In my experience using AI to build with Base UI, the models constantly mix up APIs. Because both Base UI and Radix UI operate in the "headless" space, the AI frequently hallucinates Radix patterns (like asChild or specific data attributes) into my Base UI code.

Examples in other libraries

The people of remotion made his own official skills file:
https://skills.sh/remotion-dev/skills/remotion-best-practices
https://github.com/remotion-dev/skills

Motivation

LLMs view "Headless UI" as a generic concept. When I ask an AI to write Base UI code, it often defaults to the training data weights of Radix UI (which is currently more prevalent in older training sets).

[linear]

BAS-377

[mj12albert]

When I ask an AI to write Base UI code, it often defaults to the training data weights of Radix UI

We do have an llms.txt and also md versions of the docs (example) for LLMS, have you tried explicitly providing them to your AI/tools? @ggomarighetti

[atomiks]

If I recall correctly, AGENTS.md was found to be more effective than skills because it forcefully injects the notice/knowledge on every request, whereas skills are progressively disclosed (or need to be manually referenced via /skill) and are not as likely to be discovered.

Adding something like this to AGENTS.md probably mostly solves this with latest models which are smart enough to realize they can't rely on their training data:

This project uses Base UI. Its documentation can be found at https://base-ui.com/llms.txt.
Base UI components do not have the same API as Radix UI; this includes props, data attributes, or components.
There is no asChild prop on any component; instead, the render prop is used. Read Base UI's composition guide for details on how to use render: https://base-ui.com/react/handbook/composition.md.
Always consult the Base UI llms.txt doc before building components with Base UI to ensure the correct patterns are being used.

I also think if you already have a large established presence of Base UI components in your codebase, they'll also pick up on that and reference existing patterns (they do when working on this repo at least).

[ggomarighetti]

When I ask an AI to write Base UI code, it often defaults to the training data weights of Radix UI

We do have an llms.txt and also md versions of the docs (example) for LLMS, have you tried explicitly providing them to your AI/tools? @ggomarighetti

Yes! I have been using .md files to pass them as context to LLMs, but I have only used the one in /utils/use-render.md while writing a custom skill for my components.

My opinion is not that there is nothing that meets this need, but rather that I saw it as an opportunity to standardize those .md files in a skill that can be installed, in the same way that I install the library in a new or existing project, and already have all that context, without having to write my skills by hand or reference it manually when the opportunity arises.

@mj12albert

If I recall correctly, AGENTS.md was found to be more effective than skills because it forcefully injects the notice/knowledge on every request, whereas skills are progressively disclosed (or need to be manually referenced via /skill) and are not as likely to be discovered.

Adding something like this to AGENTS.md probably mostly solves this with latest models which are smart enough to realize they can't rely on their training data:

This project uses Base UI. Its documentation can be found at https://base-ui.com/llms.txt.
Base UI components do not have the same API as Radix UI; this includes props, data attributes, or components.
There is no asChild prop on any component; instead, the render prop is used. Read Base UI's composition guide for details on how to use render: https://base-ui.com/react/handbook/composition.md.
Always consult the Base UI llms.txt doc before building components with Base UI to ensure the correct patterns are being used.

I also think if you already have a large established presence of Base UI components in your codebase, they'll also pick up on that and reference existing patterns (they do when working on this repo at least).

I have been using Google Antigravity in its high/thinking variant (I don't know if this is the best case for a demonstration) together with the shadcn/ui components, and I have noticed the asChild error or similar errors repeatedly, even after insisting that it is not the correct API and referencing it. That was more or less what motivated me to open the issue/feature request.

@atomiks

[atomiks]

Google Antigravity in its high/thinking variant

@ggomarighetti what model is this? Try using gpt-5.3-codex-high

[ggomarighetti]

Google Antigravity in its high/thinking variant

@ggomarighetti what model is this? Try using gpt-5.3-codex-high

@atomiks Gemini 3 Pro (High)

[atomiks]

The results you'll get here is model-dependent and Gemini 3 isn't very good (at coding/instructions, I tried it once in November and then never again)

I would recommend using the latest models from OpenAI or Anthropic instead (particularly GPT-5.3 or 5.2 Codex, or Opus 4.5 or 4.6) as they are much better than anything that came before them

[ggomarighetti]

The results you'll get here is model-dependent and Gemini 3 isn't very good (at coding/instructions, I tried it once in November and then never again)

I would recommend using the latest models from OpenAI or Anthropic instead (particularly GPT-5.3 or 5.2 Codex, or Opus 4.5 or 4.6) as they are much better than anything that came before them

Migrated and working, with the model change and the reference to the llm endpoint in the documentation, it now understands perfectly!

Thank you!

[LukasTy]

Closing this issue then.
If the position regarding the Skills ever changes, we can revisit it.