# Agent skill (/ui/docs/react/skill)

The [rules](/ui/docs/react/agents) keep an agent from breaking Appica UI. The skill teaches
it to use the library well: which of the 75+ components fits a request, the parts each one
really exports, how to theme without forking a component, and how to check its own work.

It is an [Agent Skill](https://agentskills.io): a folder of instructions that your agent
loads only when a task needs it, so it costs nothing in the sessions that don't. Claude
Code, Cursor, Codex, GitHub Copilot, Gemini CLI and most other coding agents read the
format.

## Install [#install]

Run this in your project root:

```bash
npx skills add appica-dev/appica-ui --skill appica-ui-react
```

The skill is named after the package it covers, `@appica/ui-react`. The
[`skills`](https://skills.sh) CLI finds the agents you use and puts it where each one looks
for it: `.claude/skills/` for Claude Code, `.agents/skills/` for Cursor, Codex, GitHub
Copilot, Gemini CLI and most others. Commit the folder, and everyone who works on the
project gets it.

| Flag             | What it does                                                            |
| ---------------- | ----------------------------------------------------------------------- |
| `-a claude-code` | Installs for 1 agent instead of asking. Repeat the flag for more.       |
| `-g`             | Installs for your user, across projects, instead of into this project.  |
| `--copy`         | Copies the files into each agent's folder instead of linking them.      |
| `-y`             | Skips the prompts and takes the defaults.                               |

> **Note - What the CLI needs, and what it sends:**
>
> The CLI runs on Node.js 22.20 or later. It counts installs anonymously, which is how a skill gets listed on
> [skills.sh](https://skills.sh). Set `DISABLE_TELEMETRY=1` to opt out.

### Without the CLI [#without-the-cli]

A skill is just files. Copy the
[`skills/appica-ui-react`](https://github.com/appica-dev/appica-ui/tree/main/skills/appica-ui-react)
folder from the repository into `.claude/skills/appica-ui-react` for Claude Code, or
`.agents/skills/appica-ui-react` for the others. Keep the folder name: it has to match the
skill's name.

## What's inside [#whats-inside]

| File                                                 | What it holds                                                                                              |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `SKILL.md`                                           | The workflow, the [rules](/ui/docs/react/agents), and the mistakes that type-check and are still wrong.     |
| `references/components.md`                           | Every entry point with its exports, grouped by job, and which one to use for a "modal" or a "dropdown".     |
| `references/setup.md`                                | Installation per framework, and what to look at when components render unstyled.                           |
| `references/tokens.md`, `theming.md`                 | The role tokens, brand colors, fonts and dark mode.                                                         |
| `references/composition.md`, `forms.md`              | `render`, popups and portals, Server Components, and forms with server errors.                              |
| `references/accessibility-and-rtl.md`                | Accessible names, reduced motion and right-to-left.                                                         |
| `scripts/check.mjs`                                  | A read-only check of your setup and of the files the agent changed.                                         |

The agent reads `SKILL.md` when the skill triggers, and opens a reference only when the
task calls for it. Component pages are not bundled: the agent fetches the 1 page it needs
as markdown, the same way it does from [`llms.txt`](https://appica.dev/ui/react/llms.txt).

## Use it [#use-it]

There is nothing to call. Describe the interface you want and the agent loads the skill on
its own, even when you never name Appica UI or a component:

> Add a filter drawer to the products page, with a price range and a brand checklist.

To be explicit, name it: "use the appica-ui-react skill". In Claude Code you can also type
`/appica-ui-react` followed by the task.

With the skill loaded, an agent works in this order:

1. Runs the check script, so a broken setup is fixed before it writes a component.
2. Looks the component up in the catalog, where a "filter drawer" is `drawer` and a
   "dropdown" is `select`, `combobox`, `autocomplete` or `dropdown-menu`.
3. Reads that component's page, or its types in `node_modules`, instead of guessing props.
4. Writes the code, then runs the check on the files it changed and fixes what it reports.

## The check script [#the-check-script]

The script is plain Node.js with no dependencies, and it never writes a file. You can run
it yourself:

```bash
# The setup
node .claude/skills/appica-ui-react/scripts/check.mjs

# The setup, and the usage in the files or folders you name
node .claude/skills/appica-ui-react/scripts/check.mjs src/app/settings
```

**Setup.** React 19, Tailwind CSS v4, the stylesheet import, and whether the `@source` path
resolves to the installed library from the stylesheet it's written in. When it doesn't, the
script prints the line to write:

```text
Setup
  ok     @appica/ui-react 1.5.0
  ok     react 19.3.1
  ok     tailwindcss 4.3.5
  error  No stylesheet imports Appica UI, so its components render unstyled.
         Add to src/styles/app.css, after the tailwindcss import:
           @import '@appica/ui-react/styles.css';
           @source '../../node_modules/@appica/ui-react/dist';
```

**Usage.** In the files you name, it reports:

- An import that doesn't exist in your installed version, with the one that does:
  `@appica/ui-react/sheet` is `drawer`, and `CardContent` is not a part of `Card`.
- Hue utilities (`bg-gray-100`) and color literals (`bg-[#fafafa]`) where a role token belongs.
- A link rendered through `Button`, and a `className` on the element passed to `render`.
- A form whose buttons can't submit it, because none has `type="submit"`.
- With `--rtl`, physical utilities such as `pl-4` and `text-left` that won't mirror.

It exits with 1 when it finds an error, so it also works in CI or a pre-commit hook.

## Rules or skill? [#rules-or-skill]

Use both. They do different jobs:

|               | [Rules](/ui/docs/react/agents)           | Skill                                              |
| ------------- | ---------------------------------------- | -------------------------------------------------- |
| Lives in      | Your `AGENTS.md` or `CLAUDE.md`          | `.claude/skills/` or `.agents/skills/`             |
| Loaded        | Every session                            | Only when a task involves the interface            |
| Size          | About 25 lines                           | A workflow, 7 references and a script              |
| Good for      | Never writing `bg-gray-100`              | Picking the component, composing and theming it    |

The skill carries a copy of the rules, so it works on its own. The copy that ships in your
`node_modules` describes the version you have installed, and the skill tells the agent to
trust that one when the 2 differ.

## Keep it current [#keep-it-current]

```bash
npx skills update appica-ui-react
```

Each release of the skill describes 1 release of the library. When the 2 drift apart, the
check script says so and lists the difference: the components your installed version
doesn't have yet, or the ones the skill doesn't know yet. Update the skill after you
upgrade Appica UI.

To remove it, run `npx skills remove appica-ui-react`.
