Guide
Components
Showpiece UI for AI coding agents
01 · What it is
Components is a Claude Code skill, not a component library. It carries no bundled UI code of its own, only a decision flow (SKILL.md) and a registry of 39 showpiece effects and 12 plain fallbacks (components.json), pointing at five real component libraries. Ask for an effect in plain English and the agent matches it against that registry, fetches the real component live from its source, and adapts it to your project’s brand tokens before it lands in your codebase.
02 · How it works
- 01
Match the request
SKILL.md reads the request and checks it against components.json. Each registry entry records an effect, its source library, the exact fetch command, and its license, so matching is a lookup against real, licensed entries rather than a guess.
- 02
Fetch it live
At build time the skill runs the library’s real shadcn registry command, `npx shadcn@latest add "<registry-url>"`, for Aceternity, Magic UI, Cult UI, and ReactBits. 21st.dev is the exception: its registry now requires an account, so those entries pull from the author’s own open mirror (kokonutui.com) or fall back to WebFetch/Playwright against the public component page.
- 03
Adapt to brand
The fetched component gets rewired onto your color tokens, checked in dark mode and at mobile widths, and wrapped for prefers-reduced-motion, following the checklist in references/adaptation.md.
- 04
Optional polish handoff
If impeccable or frontend-design is installed, final visual polish is handed to it. Neither is required: components degrades gracefully and ships its own adapted output either way.
03 · Install & usage
CLI installer (recommended)
npx components-skill@latest add # .claude/skills/components, this project
npx components-skill@latest add --agent all # Claude Code + Codex + Cursor + Gemini
npx components-skill@latest add --global # ~/.claude/skills/components
npx components-skill@latest update # refresh, keeping any local editsManual copy (fallback, no update path)
mkdir -p <your-project>/.claude/skills/components
cp -r SKILL.md components.json references \
<your-project>/.claude/skills/components/Then just ask: "add a macbook-scroll hero" or "put an interactive globe near the contact form." The skill matches the effect, runs the fetch, installs the dependencies, and adapts the result. A plain request like "just a normal contact form" resolves to a shadcn fallback instead of a showpiece.
04 · Supported tools
| Agent | Bundle | Notes |
|---|---|---|
| Claude Code | .claude/skills/components/ | Native. Auto-discovered from the description in SKILL.md. |
| Codex CLI | .codex/skills/components/ | Same SKILL.md format, project-scoped. |
| Cursor | .cursor/rules/components.mdc | Rule with frontmatter, payload alongside at .cursor/components/. |
| Gemini CLI | .gemini/extensions/components/ | gemini-extension.json plus a GEMINI.md generated from SKILL.md. |
One source packaged per harness by scripts/build-agent-dirs.sh.
05 · How it's different
vs. hand-copying from a docs site
A pasted component goes stale the moment its library updates, and copy-paste drops the upstream license and attribution. components fetches live at build time, so the code is current and its license travels with it.
vs. frontend-design alone
frontend-design designs well but has no opinion on where a specific piece of showpiece motion comes from. That kind of motion is slow and bug-prone to hand-write. components answers one question, which proven effect fits and how to make it on-brand, then optionally hands final polish back to a design skill.
06 · Changelog
v1.2.02026-08-30
CLI search command for offline registry lookup. PR-diff smoke testing in CI. First non-React port: a Vue variant of split-text, verified end-to-end. New layouts[] layer composing showpiece entries into full page/scene arrangements. Health-check hardening against rate-limit false positives.
v1.1.12026-07-31
License auto-detection fix on the LICENSE file. Closed CI validation gaps (fallback entries, library-name typos). PowerShell install commands added alongside bash.
v1.1.02026-07-20
Added ReactBits splash-cursor: an interactive WebGL fluid-simulation showpiece, zero npm deps, MIT.
v1.0.02026-07-16
All five source libraries curated. Registry grew from 18 to 38 showpiece entries, each with a verified fetch path, license, and exact dependency list.
07 · Links