agentleFS
DhodrajDhodraj/ui-skills/.claude/skills/ui-find/SKILL.md

ui-find

Skill2 starsChanged yesterdayMITView on GitHub

Find a component that already exists instead of writing a new one. Use when the user describes a UI need in words (\"a workflow timeline with running, failed and retrying states and expandable logs\"), asks what component to use, asks for alternatives to one, or asks whether something is already in the project. Searches the project first, then 500+ shadcn-spec registries, reads the candidates' real code and dependencies, ranks them against the project's stack and licence needs, and returns exact names and links.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the project's components.json too: its registries field names the registries this project has already accepted.

    line 45
  2. Very specific:

    Read the output for what it is.

    line 64
  3. Distinctive:

    Do not rank from a name and a one-line description.

    line 114
  4. Distinctive:

    Look at the live preview on the source's own page as well.

    line 131

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Component find

A described component is not a component to invent. Most of what gets described already exists, with its states, its keyboard handling and its edge cases worked out by someone who shipped it.

1. Turn the words into requirements

Split the request before searching. Example request: "a modern workflow execution timeline with running, failed, retrying and completed states, expandable logs, and links to job details."

KindFrom that request
What it isA vertical list of ordered events with per-event detail
States it must carryrunning, failed, retrying, completed, and the empty list
Behaviourexpand and collapse a row, keyboard reachable, a link out of each row
Data shapean ordered array with status, timestamps, a log body, a job id
Densitythe real case: how many steps does a long run have?
Visualmatches the product's existing list and status conventions

Name the component category in the words other people use for it. The request's words are often not the catalogue's. A "workflow execution timeline" is catalogued as a timeline, a stepper, an activity feed or a log viewer. Search all the plausible names. https://component.gallery settles what a component is usually called and what it usually does.

2. Search the project first

A second copy of a component the product already has is a defect, not a choice.

rg -l --glob '!node_modules' -i 'timeline|stepper|activity' --glob '*.tsx' --glob '*.jsx' --glob '*.vue'

Where the repository has a graft index, graft ask "where are list and status components defined" is faster and cheaper than grepping.

Read the project's components.json too: its registries field names the registries this project has already accepted.

3. Search the registries

node ../ui-design/scripts/find-components.js \
  timeline stepper activity --limit 20

Options that matter:

  • --curated-only searches only the read-and-licensed sources in sources.json;
  • --registries <n> widens the long tail;
  • --type any includes blocks, hooks and whole pages, not only registry:ui;
  • --json returns a machine-readable result.

Read the output for what it is. The script fetches the public registry directory at https://ui.shadcn.com/r/registries.json, which held 508 registries on 2026-10-27, each with a health status and an item count. It then fetches each candidate registry's own catalogue. It scores items by where the search terms appear: name first, then title, then description. It caches for a day under ${XDG_CACHE_HOME:-~/.cache}/product-experience.

The score is a text match, not a judgement. It says a candidate is worth reading. It says nothing about whether the component is any good, and the directory's own ranking.score tracks availability and catalogue size, so a registry of 12,000 icons outranks a carefully built set of 40 components. Never present either number to the user as quality.

Other routes, when the script's coverage is not enough:

  • pnpm dlx shadcn@latest search @namespace --query <term> asks one registry directly, and reaches a registry that filters server-side.
  • The shadcn MCP server (pnpm dlx shadcn@latest mcp init --client claude) exposes the same registries to natural-language requests. Use it when it is already configured; it is not needed for the script to work.
  • Registries with their own MCP server, such as claude mcp add --transport http arc https://uiarc.dev/api/mcp. An added server is an installed dependency: ask before adding one.
  • https://21st.dev/community/libraries indexes 167 libraries by name, which helps when the user names a library rather than a component. Its free plan allows two copies a day and its MCP retrieval starts at a paid plan, so search the free directory first.
  • https://www.shadcn-labs.com is a hub, not a registry: its own /registry.json and /r/registry.json both return 404. What it is good for is the surfaces the main directory does not cover, each a separate site with its own registry. Reach for one when the component is not a web page component at all:

    NeedSite
    Terminal interfacetermcn.dev
    Emailemailcn.run
    PDFpdfcn.dev
    Open Graph imageogimagecn.com
    Videoframecn.dev, snapcn.dev
    Shader and WebGPUshadercn.run
    Rich text editoreditorcn.vercel.app
    MCP and chat app interfacemcpcn.dev
    Diagram in MDXmdxcn.dev

    Confirm the install command on the site itself. These were read as a directory listing, not installed.

4. Read the candidates

Do not rank from a name and a one-line description. For each serious candidate, read the real thing:

pnpm dlx shadcn@latest view @namespace/name     # the files, deps and code
curl -s "https://<registry>/r/<name>.json" | jq '.dependencies, .files[0].content' | head -60

What to look for in the code:

  • the states it actually implements;
  • whether status is carried by colour alone;
  • keyboard and focus handling;
  • whether it owns its own data fetching;
  • how much of the project's stack it assumes;
  • how many new dependencies it drags in.

Look at the live preview on the source's own page as well. A screenshot shows the dense case and the failure state that a description omits.

5. Rank by suitability

In this order. An earlier row beats a later one; a component that fails one of the first three is out whatever it looks like.

#WhatHow to judge it
1Does it do the jobEvery state and behaviour from step 1, or a clear seam to add the missing one
2Licence and costRead at the source, in the repository's own LICENSE file. GitHub's sidebar label is a guess: it reports both DavidHDev/react-bits and DavidHDev/canvas-ui as NOASSERTION, and both are in fact MIT + Commons Clause, which permits use inside a product but forbids redistributing the components "alone, in a bundle, or as a ported version". That rules them out of a template or a starter kit you ship, and it is invisible from the label. An AGPL default, a paid tier or an unstated licence needs the user's decision before it ships
3Stack fitSame framework, styling system and component base. A Base UI component inside a Radix product is a second system
4Design-system fitMeasure it against the project's DESIGN.md, where one exists: does it take the colour, type, radius and spacing tokens, or does it hard-code its own? A component that carries its own palette and radii spreads drift through every screen it lands on
5AccessibilityKeyboard operable, named controls, status never by colour alone, focus visible
6Responsive behaviourCheck at 375px, not only on the desktop preview
7Customer usabilityDoes it suit the real density and the real labels, or only the demo's six tidy rows
8Source qualityReadable code, a maintained repository, a stated version. Record the last push date where it is old
9Install costNew dependencies, peer versions, a build step, a font, a licence key
10MaintenanceCode copied into the project is code the project now owns. Prefer fewer, larger, well-built pieces

Then recommend one, with two to four lines on why. Name the runner-up, and what would make it the better choice. Where nothing fits, say what each candidate lacked and propose building it. Compose it from primitives the project already has wherever that is possible.

6. Install, integrate, verify

pnpm dlx shadcn@latest add @namespace/name --dry-run   # see what it writes
pnpm dlx shadcn@latest add @namespace/name

Installing a component writes files into the project and may add dependencies: confirm with the user before the first install from a source the project has not used before.

Then map it onto the project's tokens, render it with the real data and the dense case, and walk it with ui-review. A component that was never rendered in this product has not been evaluated.

Report

  • The requirement, as split in step 1.
  • What the project already had.
  • The candidates read, with exact names and links: the source page, the registry item url, and the install command.
  • The ranking, and the one recommended, with its licence as read.
  • Which links were verified by fetching them, and which are inferred.
  • What remains unverified: a preview not opened, a licence page not read, a licence not stated anywhere.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.