21st-dev-components - SKILL.md Agent Skill

name: 21st-dev-components description: Use when the user wants to build a React site or app section from 21st.dev components, clone the structure of a reference site with 21st.dev building blocks, browse 21st.dev manually and return copied prompts/code, or says things like "build me a site like this", "use 21st.dev", "copy prompt", "component URL", "hero from 21st", or "match this landing page with ready-made components".

21st.dev Reference-to-Component Skill

This skill routes between two flows:

Auto mode: the user provides a reference site URL and wants the agent to inspect it, infer the required sections, choose matching 21st.dev components automatically, and integrate them.
Manual mode: the user wants guided collection. The agent lists the sections, tells the user what to fetch from 21st.dev, then integrates the returned handoff.

Use this skill only for React-family projects. If the repo is not React-based, explain that v1 of this skill is React-only and stop.

Bundled Resources

references/categories.md Use for section-to-category mapping and direct 21st.dev category URLs.
references/manual-handoff-template.md Use when the user is gathering components manually.
references/section-detection-rubric.md Use during Auto mode after crawling the reference site.
scripts/resolve-21st-component.mjs Resolve a 21st.dev component page into normalized metadata.
scripts/fetch-21st-source.mjs Fetch raw source from 21st CDN URLs.
scripts/build-manual-handoff-template.mjs Generate a manual handoff markdown file for the user.

Raw Code Resolution Standard

Do not derive 21st.dev CDN source URLs by string concatenation or by manually modifying the community page URL.

Always treat the user-facing 21st.dev component page as the source of truth, then resolve it into metadata before fetching code.

Required workflow

Start with the 21st.dev community component URL.
Run the resolver script on that page URL.
Read codeUrl and demoCodeUrl from the resolver output.
Fetch source from those returned URLs.
Only fall back to manual copy/paste if resolution succeeds but raw source cannot be fetched in the current environment.

Command

node scripts/resolve-21st-component.mjs --url "<21st-component-url>" --json

Why this rule exists

21st.dev community URLs do not always map cleanly to CDN paths. Mismatches can include:

author slug differences between page URL and CDN path
internal user IDs in CDN paths instead of public author names
timestamped filenames such as code.1748367465506.tsx
version query params such as ?v=1
demo paths that are not reliably predictable

Because of this, the correct standard is:

community page URL -> resolve metadata -> fetch codeUrl / demoCodeUrl

not:

community page URL -> manually transform into CDN URL

Manual fallback rule

If the resolver returns metadata but the environment cannot fetch the raw source files, ask the user for one of these:

pasted code from the 21st.dev Copy Code action
downloaded component source
permission to use an alternate environment that can fetch the returned CDN URLs

This resolution step is mandatory in both Auto mode and Manual mode whenever the environment allows it.

Mode Router

Use Auto mode when

The user gives a live reference site URL.
The user says "build me something like this", "clone this layout", or "crawl this site and rebuild it".
The user expects the agent to choose components automatically.

Use Manual mode when

The user says they will browse 21st.dev themselves.
The user pastes 21st.dev component URLs, copied prompts, code fences, or a markdown handoff file.
The user wants the agent to tell them exactly what sections to gather.

If Auto mode fails because the site is blocked, brittle, or the 21st lookup is weak, fall back to Manual mode immediately and generate the handoff template instead of dead-ending.

Auto Mode Workflow

Step 1: Crawl the reference site in a browser

Use the browser-first workflow from the webapp-testing skill. Do not rely only on raw HTML if the page is clearly client-rendered.

What to inspect:

header / navbar / announcement bars
hero block
feature grids or card rows
social proof / logos
testimonials
pricing
FAQ
forms / auth blocks
footer
app shell elements such as sidebar, table, tabs, or modals

Load references/section-detection-rubric.md if the page structure is not obvious.

Step 2: Build a page anatomy model

Write down the major sections in visual order. For each section, capture:

section name
rough structure
visual tone
obvious dependencies such as carousels, motion, video, maps, charts, or forms

Step 3: Map sections to 21st.dev categories

Load references/categories.md and map each detected section to one or more category slugs.

Rules:

Match structure first, style second.
Use one primary category and optional supporting categories.
Decorative elements like shaders, backgrounds, or borders are secondary, not the main section match.

Step 4: Discover and resolve candidate components

Search 21st.dev for each mapped category. Once you have likely component URLs:

Resolve each page:

node scripts/resolve-21st-component.mjs --url "<21st-component-url>" --json

Inspect:
- dependency count
- component/demo CDN URLs
- tags
- author
- registry dependency hints

Step 5: Choose the best match automatically

Default behavior is not to ask the user to choose.

Prefer:

closest structural match
lowest dependency burden
compatibility with the current repo
easier adaptation to the existing styling system

Step 6: Fetch source and integrate

Fetch component/demo source from the resolved codeUrl and demoCodeUrl values. Do not guess CDN paths manually.

Fetch component/demo source from CDN URLs:

node scripts/fetch-21st-source.mjs --url "<code-url>" --url "<demo-code-url>" --out-dir tmp/21st

Then integrate into the repo:

adapt file paths to the existing project structure
prefer the repo's current component locations
prefer existing Tailwind, TypeScript, and shadcn conventions when present
if shadcn conventions are absent, adapt rather than forcing /components/ui
if required dependencies or setup are missing, install/configure them first

Step 7: Report what was selected

When you finish, state:

which sections were detected
which 21st.dev components were selected
which dependencies were added
any sections that required partial custom adaptation

Manual Mode Workflow

Step 1: Break the page into sections

Identify the target sections from the user's request or reference URL:

header / navbar
hero
features
testimonials
pricing
footer
sidebar
CTA
forms
tables
auth
FAQ

Step 2: Tell the user what to collect

Use references/categories.md to give the exact 21st.dev category links.

Generate a checklist file when useful:

node scripts/build-manual-handoff-template.mjs --sections "header,hero,features,pricing,footer" --out 21st-handoff.md

Point the user at the template in references/manual-handoff-template.md if they want to paste directly in chat instead of using a file.

Step 3: Accept one combined handoff

The handoff can contain:

21st.dev URLs
copied prompt blocks
code fences
dependency lists
placement notes

Do not make the user re-explain the same page structure if the handoff already contains it.

Step 4: Parse and integrate

For each returned section:

resolve the component URL if present
read normalized metadata first, especially codeUrl, demoCodeUrl, and dependencies
fetch source from the resolved raw URLs when needed
merge copied prompt/code information with repo context
install dependencies
adapt imports, component paths, and utility functions to the current repo

Integration Rules

v1 supports React projects broadly.
Preserve the repo's existing file layout whenever possible.
If Tailwind or TypeScript is missing and the chosen component requires it, explain exactly what must be added before integration.
If the component assumes shadcn utilities like cn or @/lib/utils, either map them to the repo equivalent or add a minimal compatible helper.
If one section cannot be matched cleanly, integrate the rest and flag the unmatched section explicitly.

Failure Handling

Bad reference URL or blocked crawl: switch to Manual mode and generate a handoff template.
21st.dev page resolves but source URLs are missing: use the copied prompt path or ask for the component's copied prompt/code only for that section.
Resolver succeeds but the environment cannot fetch the raw CDN URLs: ask the user for pasted Copy Code output, downloaded source, or permission to use another environment for fetch.
Non-React target repo: explain the limitation and stop.

Output Defaults

Auto mode: inspect, choose, fetch, integrate, report.
Manual mode: generate checklist, ingest handoff, integrate, report.