# Using with AI agents

FUNSTACK UI's API differs from other headless libraries: action props instead of `onChange`, `render` instead of `asChild`, transitions you do not start yourself. An agent that guesses from other libraries gets these wrong. Give it the documentation instead.

## Install the agent skill

An [agent skill](https://agentskills.io) is a Markdown file that an agent loads when a task needs it. `@funstack/ui` ships one, named `funstack-ui-knowledge`, and an installer that copies it into your project. Run it in your project's root, with `@funstack/ui` installed:

```bash
npx -p @funstack/ui@alpha funstack-ui-skill-installer
# or
pnpm dlx --package @funstack/ui@alpha funstack-ui-skill-installer
# or
yarn dlx -p @funstack/ui@alpha funstack-ui-skill-installer
```

The installer asks which agent you use (Claude Code, Codex, GitHub Copilot, Cursor and others, or a custom path) and copies the skill into that agent's skills directory, for example `.claude/skills/funstack-ui-knowledge/`. In a script or CI, where there is no terminal to ask in, it reads the target directory from `SKILL_INSTALL_PATH` instead:

```bash
SKILL_INSTALL_PATH=./.claude/skills npx -p @funstack/ui@alpha funstack-ui-skill-installer
```

In an interactive terminal the variable is ignored and the prompt appears; add `< /dev/null` to the command to use the variable there.

The skill is short, so the agent can load it whole. It contains:

- The mental model: action props, optimistic and pending state, Suspense, transitions.
- The mistakes agents make most often, such as writing `onValueChange` or wrapping actions in `startTransition`.
- A one-line index of every component, with its import path and parts.
- A pointer to the full documentation bundled in the package (below).

Re-run the installer after upgrading `@funstack/ui` to update the skill. Commit the copied files if your team shares the agent setup.

## Docs in the package

The npm package contains this whole site as Markdown, matching the installed version. The skill points the agent at its index:

```bash
node_modules/@funstack/ui/dist/docs/index.md
```

You can also point an agent at this file directly, without the skill. Because it comes from the installed package, it does not drift from the code the agent is writing against.

## Docs on the web

The same Markdown is published on this site:

| URL | Contents |
| - | - |
| `https://ui.funstack.work/llms.txt` | An index of every page with a one-line description, in the [llms.txt](https://llmstxt.org) format. |
| `https://ui.funstack.work/llms-full.txt` | Every page in one file, in sidebar order. |
| Any page URL plus `.md` | That page as Markdown, for example `https://ui.funstack.work/components/dialog.md`. |

> **Which version?**
>
> The site documents the latest release. If your project pins an older alpha, prefer the docs in `node_modules`.