AI and agents

Koala is built for coding agents too: an MCP server that finds, reads and installs components, every docs page as markdown, an llms.txt index, and a skill that teaches an agent Koala's rules. How to use each.

What there is#

WhatWhereWhat it is for
MCP servernpx -y koalaui-cli mcpLets the agent search the catalog, read a component's docs and install it into your project, as tools it calls itself.
Markdown pagesAny docs URL plus .md, like /docs/components/button.mdOne page as clean markdown: its prose, tables and every code sample, without the demo markup.
Copy pageThe top right of every docs pageCopies the page as markdown, opens the markdown, or starts a ChatGPT or Claude chat that reads it.
llms.txt/llms.txtThe index: conventions, install and CLI commands, what is free and what is Pro, and every page with its summary.
llms-full.txt/llms-full.txtEvery docs page (guides, foundations, components) in one file.
The skillnpx koalaui-cli@latest skillThe house rules, tokens, themes and CLI in one SKILL.md, plus a reference per component, written into your project.

MCP server#

The Koala CLI runs as an MCP server over stdio. Register it once and the agent gets three tools it calls on its own while it builds UI:

ToolWhat it does
search_components(query, kind?)Searches components, sections and page examples. Returns each match's name, kind, tier (free or Pro) and a one-line description.
get_component(name)Returns the item's docs as markdown, its API, usage and examples, plus its files and dependencies.
add_component(names)Installs the items like add, running init first in a project with no Koala setup, and returns the files it wrote.
# Claude Codeclaude mcp add koalaui -- npx -y koalaui-cli mcp# Codexcodex mcp add koalaui -- npx -y koalaui-cli mcp# Cursor: writes .cursor/mcp.jsonnpx koalaui-cli@latest mcp init --client cursor# VS Code (Copilot agent mode): writes .vscode/mcp.jsonnpx koalaui-cli@latest mcp init --client vscode

mcp init merges into an existing file and keeps the other servers in it. The server installs into the workspace your editor opens it in. Pro items use the license activated on the machine (npx koalaui-cli@latest login <key>); without one, get_component says the item is Pro and add_component returns the paywall message, so the agent tells you instead of rebuilding it.

Claude Code#

Install the skill in your project. Claude Code loads project skills from .claude/skills/, and the skill’s description tells it to follow Koala’s rules whenever you ask for UI. Start a new session after installing it.

npx koalaui-cli@latest skill

Commit .claude/skills/koala-ui/ so everyone on the project works from the same rules, and run the command again after you update Koala. For a page the skill does not cover, a foundation or a section family, give Claude its markdown URL: “Read https://www.koalaui.com/docs/foundations/theming.md and add a theme switch to the header.”

Cursor, Codex and other agents#

Install the skill the same way, then point the agent at it. Cursor reads project rules from .cursor/rules/; this writes one:

mkdir -p .cursor/rulescat > .cursor/rules/koala-ui.mdc <<'EOF'---description: Building UI with Koala UIglobs: ["**/*.tsx"]alwaysApply: false---Before writing UI, read .claude/skills/koala-ui/SKILL.md and follow it.Component docs are in .claude/skills/koala-ui/references/<name>.md.EOF

Agents that read AGENTS.md, Codex and Cursor among them, take the same instruction from there; this appends it:

cat >> AGENTS.md <<'EOF'## UIThis project uses Koala UI. Before writing UI, read .claude/skills/koala-ui/SKILL.md and follow it.Component docs are in .claude/skills/koala-ui/references/<name>.md.EOF

To keep the skill somewhere else, pass --dir: npx koalaui-cli@latest skill --dir docs/koala-skill, and point the rule there.

ChatGPT, Claude and other chats#

On any docs page, open the Copy page menu at the top right. Copy page puts the page on your clipboard as markdown to paste into a chat; Open in ChatGPT and Open in Claude start a chat that reads the page for you. For a broader question, hand the assistant llms.txt, the index, or llms-full.txt, everything at once.

Migrating a project#

The skill also carries the migration guide. In a project with its own components, CSS or UI kit, ask the agent to migrate it to Koala: it audits the project, writes a plan for you to approve, then moves one surface at a time. See Migrating a custom project.

What an agent can install#

An agent runs the same CLI you do. Free items need nothing: the foundation components, the lib helpers and the tokens install anywhere with npx koalaui-cli@latest add <name>. The other components, sections, page examples and templates are Pro and install with your license once you have run npx koalaui-cli@latest login <key> on the machine, and an agent working there uses that seat. Without a license, add stops with a paywall message, and the skill tells the agent to report it rather than rebuild the item.

Pro source is never in the open markdown. A section family’s page names its Pro variants and stops there; no .md page, llms file or public skill reference carries the code of a Pro section, page or template. With a license active on the machine, npx koalaui-cli@latest skill also writes a reference for every Pro component, examples included, so the agent can plan with one before it installs it.

FAQ#

It is rendered from the same page, at build time: the prose, tables and code samples are the page's own. Interactive demos are left out, and every demo's code sample stays.