Fighting AI Training Bias with Agent Skills

A coding agent can't one-shot a library its training data barely saw. Ask one for a dashboard in an under-represented library and you get one of two failures: it quietly reaches for the incumbent it has seen a million times, or it stays loyal and invents props that don't exist. bestax's answer is to make the real, current API machine-legible so one shot is enough, and this post is everything that ships today.

This is post six of the catch-up series (tracker). The v5 recap closed out the release backlog; this one explains where the AI effort has been going. The title says training bias. That's my word for it, not the repo's, and I already argued the case at length in July: what's over-represented gets recommended, recommendations compound into monoculture, and nobody compares two options anymore. I'm not re-arguing it here. This is the build log.

Start with the staleness math. Avatar and Badge shipped July 10. Dot-notation sub-components landed across every parent component on July 20. What does a model trained in the spring know about a component that shipped July 10? Nothing, and that's the good case: even a model that has met bestax has met a bestax that no longer exists. Under-represented and stale, at the same time. The bestax homepage has an AI-Ready section, "Bring Bestax to your AI tools," with three cards: LLM-ready docs, Agent skills, and an MCP server marked coming soon. This post is those three cards in order, with receipts.

Machine-Readable Docs

Every page of the bestax docs ships in a form a model can read whole. The site build regenerates three artifacts on every deploy:

• llms.txt, a curated index of the docs, small enough to pin in your project rules
• llms-full.txt, the entire documentation as one file
• a Markdown twin of every page: append .md to any docs URL, like bestax.io/docs/api/elements/button.md, when you want one component in a small context

The LLMs guide pitches the big one with a line I didn't have to write for this post: "Feed it everything. For a one-shot load of the whole library." The docs already speak this vocabulary, because the artifact exists for exactly this reason: a single context load standing in for what training never contained. And because the artifacts regenerate on every build, they can't drift behind the deployed site. There's no stale window between what the docs say and what the model reads.

Agent Skills

Docs give an agent knowledge; skills give it technique. That distinction took me a while to respect. With llms-full.txt in context an agent knows every prop of every component, and it will still open a layout task with four clarifying questions, or validate a form the way its favorite form library does. Knowing the API and knowing the house way to use it are different things.

A skill is a folder with a SKILL.md of instructions the agent always loads, plus deeper references it reads on demand. bestax ships seven:

• bestax-layout-scaffold: scaffold a complete, responsive page, from app shells and marketing pages to auth screens and card-grid catalogs
• bestax-form: Field and Control composition, the whole input set, and the validate-it-yourself pattern
• bestax-theming: brand colors, tokens, and dark mode through --bulma-* variables
• bestax-custom-component: build beyond stock Bulma without leaving the bestax style
• bestax-icons: Icon and IconText across the five supported icon libraries
• bestax-optimize: measure the built CSS, then shrink it with the cheapest lever that fits
• bestax-migrate: move an app off react-bulma-components with the codemod, then resolve every TODO it leaves

My favorite sentence in any of them is a behavioral rule in the layout skill: "Select an archetype from the request and build it in one shot." The same rule forbids asking layout questions. That's the thesis of this post with a lint rule attached. And yeah, skills really are cartridges: snap one in and the agent knows moves it didn't know a minute ago.

Two Ways to Install

Channel one is the skills CLI:

npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold

The same command takes any of the seven names, or drop the --skill flag to pick from a list.

Channel two is the scaffolder. pnpm create bestax@latest offers to preinstall the skill bundle into the new app's .claude/skills/, and while it's in there it writes two more files: a .claude/launch.json so an agent's browser preview can boot the dev server by name, and a CLAUDE.md recording the choices the scaffolder just made (CSS flavor, class prefix, icon library). The agent never has to rediscover the setup it was born into.

Don't Reinvent: The Component Catalog

The most expensive agent failure isn't a wrong prop; it's a rebuilt component. A wrong prop fails loud, in the console or the type checker. A hand-rolled tooltip works, looks almost right, ships, and is quietly yours to maintain forever.

So the custom-component skill leads with a generated catalog whose header states its job: every documented component, "so you don't reinvent one that already exists." All 87 components fit in 149 lines, names and one-line purposes only, each linked to its full API page. It's lean on purpose, cheap to hold in context, with the full prop tables one fetch away.

The part I care about most is the guard behind it. The catalog is generated from the API docs, and CI fails if any exported component lacks an API page. A component the catalog can't see is a component an agent will rebuild, so completeness isn't a habit here. It's a build gate. The list the agent reads is guaranteed complete on every commit.

I've watched an agent lovingly hand-roll a tooltip while Tooltip sat one import away, shipped and tested and documented. Small heartbreak, nobody's fault: to a model with a stale snapshot, some of these 87 components simply don't exist. The catalog is how they exist again. Here's the kind of thing that's already in the box:

<Block>
  <Tooltip label="Shipped, tested, one import away">
    <Badge dot color="success" overlap="circle">
      <Avatar name="Ada Lovelace" />
    </Badge>
  </Tooltip>
</Block>

A Tooltip, a Badge, and an Avatar, composed instead of hand-rolled.

Meeting Agents in node_modules

Some agents never fetch a URL; they read what's on disk. Since 5.8.0, the published npm tarball carries three pointer files at the package root, llms.txt, AGENTS.md, and CLAUDE.md, named for the filenames agent tooling probes first, "so agents exploring node_modules land on these resources by filename," as the package README puts it. They're pointers, not documentation: each is a short signpost back to the site artifacts above, which stay the single source of truth, so nothing in the tarball goes stale between releases. Network context, project context, and now the filesystem itself. The LLMs guide lists exactly what ships.

What's Next: The MCP Server

The third AI-Ready card says coming soon, and it means it. A first-party MCP server is planned: a Model Context Protocol endpoint an agent can query for component props, variants, and live examples while it builds. It isn't shipped, the homepage card deliberately has no link, and this post won't describe software that doesn't exist. When it ships, it gets its own post.

The nearer sequel is already specced: how the AI loop that maintains this repo keeps those seven skills honest, filed as #380. The tracker has the rest of the plan.

Point Your Agent at It

Pick whichever entrypoint matches your setup:

• In an existing app: paste https://bestax.io/llms.txt into your project rules, or point the agent at the LLMs guide.
• For the technique, not just the API: npx skills add any of the seven skills.
• Starting fresh: run pnpm create bestax@latest and say yes when it offers the skills.

And if bestax makes your agent sharper, a star on the repo is the whole marketing budget.

You don't fight training bias by arguing with the weights. You hand the agent the current docs, and you let one shot be enough.