--- title: Agent Skills description: Install the free ReUI Agent Skills to teach your AI coding agent the install workflow, the real component APIs, and ReUI's quality bar - so it ships correct UI on the first try. --- The **ReUI Agent Skills** are a packaged set of instructions your AI coding agent reads while it works. They turn a generic agent into one that knows how to find, install, and correctly wire ReUI - searching the registry first, reading the real component API before writing props, reusing the installed code instead of redesigning it, and passing ReUI's quality checks. They are the second half of **ReUI for Agents**, and like the [MCP server](/docs/mcp) they are **free**. The MCP gives the agent live, scored registry search and inline component APIs; the Agent Skills tell it how to use them well. Install both for the best result. ## Install the Agent Skills The only prerequisite is the free `@reui` registry entry in your `components.json` (no license key needed; the skill items are public): ```json { "registries": { "@reui": "https://reui.io/r/{style}/{name}.json" } } ``` See [Registry](/docs/registry) for the full registry setup. Then run one command per agent; the CLI writes the skill into that agent's conventional skills folder. Claude Code Codex Cursor OpenCode VS Code (Copilot) ```bash npx shadcn@latest add @reui/skills-claude ``` Installs to `.claude/skills/reui/`. ```bash npx shadcn@latest add @reui/skills-codex ``` Installs to `.codex/skills/reui/`. ```bash npx shadcn@latest add @reui/skills-cursor ``` Installs to `.cursor/skills/reui/`. ```bash npx shadcn@latest add @reui/skills-opencode ``` Installs to `.opencode/skills/reui/`. ```bash npx shadcn@latest add @reui/skills-vscode ``` Installs to `.github/skills/reui/` (VS Code Copilot discovers native skills here). For any other agent, copy the skill files into your agent's instructions folder manually, or use the generic `AGENTS.md` convention and reference the skill files from there. ## How your agent uses them The skill is **context-activated**: your agent reads its description and applies it automatically whenever you ask for ReUI work or premium blocks, data grids, kanban boards, dashboards, or full pages. The skill adds **no tools of its own**; its job is to make your agent **invoke the right [MCP tools](#invocable-tools) at the right moments**. It **layers on top of the shadcn skill**: generic rules (spacing, `cn()`, semantic colors, forms) come from shadcn; everything ReUI-specific comes from these skills. **Two ways in, one workflow.** ReUI works both passively and on demand. With this skill installed, just ask in plain language ("build a billing dashboard with ReUI") and it activates. Or invoke the explicit slash [commands](/docs/mcp#commands) the MCP exposes - `/mcp__reui__build`, `add`, `fix`, `improve` - for a one-shot entry point. Both run the **identical loop** below; the commands are the invocable surface, the skill is the always-on companion. The core loop the skill drives: 1. **Find** - call the MCP `search` with your intent; get a ranked, scored shortlist. 2. **Install** - run the returned `shadcn@latest add @reui/` non-interactively; the CLI resolves dependencies, aliases, and the base/style variant. 3. **Read the API** - call `get_component` for the **inline API** (no web fetch) and `get_examples(name)` to copy a real worked example. 4. **Adapt (reuse-first)** - wire real data, fix icon imports, align tokens. Adapt the installed code; never redesign or hand-roll what ReUI ships. ## What the Agent Skills teach | Capability | What the agent gains | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Registry-first instinct** | Search ReUI before writing generic markup; pick the best-scored block, component, or example. | | **Real component APIs** | A compact contract for all **17 components** (required props, composition shape, the one common gotcha) plus the rule to read each `get_component` inline API before wiring props. No guessed props. | | **Page planning** | Plan full pages with `compose_page`: ordered sections, each with the best ReUI block for the intent, instead of inventing a layout block by block. | | **Anti-hallucination checks** | Run `validate_usage` on planned component names and props before writing code, so only documented APIs make it into the output. | | **Token-savvy MCP use** | The "inline API first, web page last" rule, batch `get_component` calls, and search hints - the agent gets the right answer in the fewest calls. | | **Reuse-first adaptation** | Replace demo data with typed real data, keep the installed composition intact, do not restyle what ReUI already provides. | | **Quality gates** | ReUI's post-install checks: security (no `dangerouslySetInnerHTML`, safe external links, no secrets), accessibility (labels, real anchors), and scroll mechanics. Mirrors the MCP `get_audit_checklist`. | | **Portable icons + tokens** | Swap demo icon imports to your configured `iconLibrary`, discover hover-animated Motion icon variants with `search_icons`, and use ReUI's extended semantic tokens instead of raw colors. | ## What's inside The installed skill is 11 plain markdown files your agent reads - no runtime, no code execution. Its `allowed-tools` are scoped to the shadcn CLI (`npx`/`pnpm dlx`/`bunx ... shadcn@latest`), nothing else. | File | Purpose | | --------------------- | -------------------------------------------------------------------------------------- | | `SKILL.md` | The spine: the core loop and when to reach for ReUI vs plain shadcn. | | `tools.md` | The full MCP spec: the golden path, all 19 tools, token-efficiency and quality rules. | | `rules/registry.md` | The four registry types, the `@reui` registry, base/radix, free vs premium. | | `rules/cli.md` | Registry and license setup plus the non-interactive shadcn install flags. | | `rules/workflow.md` | The find, install, read-API, adapt loop in detail. | | `rules/components.md` | The 17 components with first-try contracts (data-grid gets the full contract). | | `rules/adapting.md` | Reuse-first: real data, no AI slop, what to change vs leave alone. | | `rules/craft.md` | The exceptional-UI bar: point of view, hierarchy, density, states, responsive, motion. | | `rules/quality.md` | Security, accessibility, and scroll gates (the done gate). | | `rules/styling.md` | ReUI extended tokens, theme adaptation, density. | | `rules/icons.md` | Portable icons, swapping imports, Motion Icons. | ## Invocable tools The Agent Skills add no tools themselves - they teach your agent **when and how to invoke the 19 tools the [ReUI MCP server](/docs/mcp) exposes**. Connect the MCP server first ([setup](/docs/mcp#connect-the-reui-mcp-server)); once it is connected, the skill drives these: **Discovery** - `search(query, type?, component?, category?, features?, free?, limit?)` - the entry point. Ranked matches across components, examples, blocks, and icons, each with its install command, docs and preview links, a `whyMatch`, a relative 0-100 `score`, and `termCoverage`. **Read one item** - `get_component(name | names[])` - the **inline API** (props + usage, as markdown) so the agent wires a component without a web fetch. Accepts up to 20 names in one call to read all of a block's components at once. - `get_examples(component)` - the free `c-*` examples built on a component; install one and copy its real composition. - `get_example(name)`, `get_block(name)`, `get_icon(name)` - full metadata for one item; icons include `animated` and `installAnimated` when a Motion variant exists. **Browse the catalog** - `list_components()`, `list_block_groups()`, `list_block_categories()`, `list_example_categories()`, `list_icon_categories()` - the catalog, with counts to narrow a `search`. **Page planning** - `compose_page(intent, sections?)` - ordered sections with the best block per section, and honest `unavailableSections` for gaps. **Icons** - `search_icons(concepts[], animated?, limitPerConcept?)` - the best icons for up to 24 concepts in one call; `animated: true` returns only hover-animated Motion variants. **Quality** - `validate_usage(components?, items?)` - validates planned component names and props against the documented APIs before code is written. - `get_audit_checklist(component?)` - the ReUI post-install quality checks the skill enforces. **Freshness and feedback** - `whats_new(since?, limit?)` - registry changes per build, newest first. - `report_issue(item, type, description)` - report a bug or gap on a registry item to the ReUI team. **Install and context** - `get_install_command(item, packageManager?)` - the exact, validated shadcn CLI command for your package manager. - `get_project_context()` - the `components.json` registry and license wiring. See the [MCP Server](/docs/mcp#mcp-tools) page for the full per-tool reference and how to connect the server. ## Update Re-run the install command for your agent to pull the latest Agent Skills. To remove them, delete the installed `reui` skill folder (for example `.claude/skills/reui/`). ## Related Guides - [MCP Server](/docs/mcp) - [License Setup](/docs/license-setup) - [Get Started](/docs/get-started) - [Registry](/docs/registry)