Guide

Agent skill

The skill installed with every pack: the token contract and the working rules, refreshed by every update, so later sessions build without the prompt.

What gets installed

Every all-<skin> pack and every update writes .claude/skills/control-ui/SKILL.md into the repository. It is installed source like the components: control-ui:update refreshes it, so hand-edits there do not survive — and repository-specific rules belong in your own instruction files instead.

It carries what a later session needs to build with the library and nothing that would go stale silently:

The ground rules — the data-skin scope, the recipe stylesheets that are never edited or reordered, the three skin files the update never touches.

The prop convention — variant, tone, size, iconOnly, and render instead of asChild, plus what a call site migrated from another library keeps and sheds.

The theme workflow — the artifact format, how an app consumes it, and the contrast the components actually paint.

The full token contract — every themable custom property, marked shared or per-mode.

What you should see now

A session that starts cold in this repository installs a component, themes it, and updates it without being handed the setup prompt again.

The commands it reaches for

The skill is the reading; these three scripts are the doing. The setup prompt leaves all three in package.json, so the agent runs them by name.

Command	What it does	When
`control-ui:diff`	Previews per-file what an update would rewrite	Before every update
`control-ui:update`	Overwrites installed source, then repairs the CSS entry	On a clean tree
`control-ui:doctor`	Read-only audit of imports, theme order, `@theme` conflicts, `data-skin`	After any install, update, or migration

Beyond the repository, the machine surfaces stay open: the catalog at /r/agent-index.json, one manifest per item, and llms.txt indexing the documentation. Machine docs has the endpoints.

Install it on its own

A lean install skips the skill, since it only rides the complete packs. The skills CLI adds it alone — one markdown file, no components, no npm dependencies, nothing written outside .claude/skills/control-ui/:

npx skills add https://control-ui.dev

It resolves through discovery — /.well-known/agent-skills/index.json names the skill and the digest of the file it serves, so the CLI verifies what it downloads.

It stays updatable — the install records the source in skills-lock.json, and npx skills update refreshes it against the site.

It is not Claude Code-only — -a targets any agent the CLI supports, -g installs once for every repository instead of into this one.

Inside a repository that already runs control-ui:update, prefer the shadcn manifest at /r/control-ui-skill.json instead: the skill then refreshes on the same command as the components rather than on its own.