find-skills

What this skill does

# Find Skills

Find the right agent skill for a task by searching **every major registry at once** and presenting each board on its own native metric — instead of trusting a single site's leaderboard.

## When to use this skill

- The user asks "how do I do X" and X is a common task that likely has a published skill
- "find a skill for X" / "is there a skill for X" / "what should I install for X"
- The user wants to extend agent capabilities (testing, design, deployment, a specific model/API, a domain workflow)
- You're about to build something from scratch that a battle-tested skill might already cover

## Why multi-source matters

Each registry shows only its own slice, with different signals:

| Registry | Search | Signals it exposes | Blind spot |
| --- | --- | --- | --- |
| **skills.sh** | `GET /api/search?q=` | lifetime installs, source repo | no stars, no summary, install count lags ~2.5h |
| **clawhub.ai** | `/api/search` + `/api/skill?slug=` | summary, installs, stars, versions | smaller corpus than skills.sh |
| **GitHub** | `gh search repos --topic {claude-skills,agent-skills,claude-code-skills}` | repo stars, description, maintenance | repo-level, not skill-level; only topic-tagged repos |

A skill can rank #1 on one site with 50 installs while a 1,300-install equivalent sits unranked on another. Searching only one registry gives a biased answer. This skill queries all three **in parallel**, ranks each board by its own native metric, flags skills that appear on both registries (matched on the *normalized* name, both directions — so `face-swap` ↔ `faceswap` line up), and shows the top of every board so you see the whole ecosystem — not one site's leaderboard.

## How to run it

Run the bundled aggregator with the user's need as the query:

```bash
bash scripts/find.sh "<what the user needs>"
```

Examples:

```bash
bash scripts/find.sh "react performance"
bash scripts/find.sh "pdf form filling" --limit 8
bash scripts/find.sh "video generation" --scan 5
bash scripts/find.sh "deploy to vercel" --no-scan --json
```

Flags:

- `--limit N` — results per source (default 10; non-numeric falls back to 10)
- `--scan K` — security-scan the top K installable candidates on each registry (default 2, max 5)
- `--no-scan` — skip the security scan (faster; the scan adds a few seconds because it fetches each candidate's real SKILL.md)
- `--json` — emit machine-readable JSON instead of the formatted report
- `-h` / `--help` — print usage and exit

The script needs `curl` and `jq`. It uses `gh` for the GitHub section and for fetching skills.sh skill bodies, and `unzip` for clawhub skill bodies during the scan — all optional and degraded gracefully if absent. No API keys are required.

### Run adjacent-term queries — one search is not enough

The registries index by a skill's **name**, not its meaning. A single query will miss great skills filed under a sibling term. **For any non-trivial need, run 2–3 searches across the adjacent vocabulary before you conclude**, then pool the results.

This is not optional polish — it routinely changes the answer. Example: searching `"ui ux design"` tops out around 19k installs, but `"frontend design"` surfaces `anthropics/skills/frontend-design` at **443k installs** — the single best skill for the same need, completely invisible to the first query.

Pick adjacent terms by domain, e.g.:

- UI/UX → `frontend design`, `design system`, `web design`, `tailwind shadcn`, `dashboard ui`
- testing → `e2e`, `playwright`, `unit tests`, `test automation`
- deploy → `deployment`, `ci cd`, `docker`, `vercel`/`kubernetes`
- docs → `documentation`, `readme`, `api docs`, `changelog`

Treat the union of these runs as your candidate pool, then apply the rubric below to the whole pool — not to one query's results.

## How to read the output

**Design principle: no invented "quality score."** There is no composite number you have to trust. Each board is ranked by *that board's own native popularity metric*, and the only computed value shown is `match %` — the share of the user's query words that appear in a skill's name/summary. That's a transparent relevance hint, not a verdict.

The report, top-down:

- **Banner + telemetry** — the query, a **source health line** (`skills.sh ✓ 5·1.2s   clawhub ✓ 0·2.7s   github ✓ 8·1.1s`) showing which boards responded / hit count / latency, and how many skills are installed locally. A `✗ failed` / `– skipped` source means partial results — say so.
- **▶ TOP OF EACH BOARD** — the #1 entry on *each* board by that board's native metric (skills.sh installs / clawhub installs·stars / GitHub match%·stars). **This is keyword + popularity, NOT a vetted pick** — it's a starting point, and it can be wrong (a 100%-keyword-match repo may be off-topic once you read it). Always confirm by reading before you forward it. If a board has no match it says so.
- **✓ ALREADY ON YOUR MACHINE** — appears only when a result is already installed. A *positive* nudge: tell the user they already own a good skill and needn't install anything. (Heuristic: matches the result name against folder names under `~/.agents/skills` / `~/.claude/skills`; a skill installed under a renamed folder can be missed.)
- **📦 skills.sh** — ranked by **installs**. 1-click installable. Each row shows its source repo (so same-named skills from different repos are distinguishable). `(also on clawhub)` marks a normalized-name match on the other registry. Top `K` carry a risk badge.
- **🪝 clawhub** — ranked by **installs · stars**. 1-click installable. `(also on skills.sh)` marks the reverse cross-post. Top `K` carry a risk badge.
- **🐙 github** — repos across the `claude-skills` / `agent-skills` / `claude-code-skills` topics (merged, de-duped), ranked by **match% then stars**, so a high-star but off-topic repo (e.g. a 14k-star tool that merely mentions "UI") sinks below a 100%-match repo. Only topic-tagged repos appear — untagged skill repos are invisible here. Not 1-click installs — review before use.
- **📚 curated lists** — human-vetted awesome-lists for a final sanity check.

## How to choose the right skill (decision rubric)

The script gathers evidence; **you make the call.** Don't dump the table and ask the user to decide — that's not helpful. Form a clear, defensible recommendation. The professional move is to be opinionated *and* show your reasoning grounded in real signals.

**Step 1 — Read before you judge.** Never recommend from metadata alone. Open the actual SKILL.md / README of the top 2–3 candidates (the script already fetches bodies for the scanned ones; for GitHub repos fetch the README). Ask: *does it actually do the user's specific task, or just share keywords?* A 10k-install skill that's off-topic loses to a 200-install one that nails it.

**Step 2 — Weigh the signals, in this order:**
1. **Fit** — does the skill's documented behaviour match the real need? (read the trigger/scope, not just `match %`). This dominates everything else.
2. **Popularity as social proof** — among genuinely-fitting skills, higher installs/stars means more people validated it. Use the board-native numbers.
3. **Depth & maintenance** — does the body cover the user's specific sub-need? Is there a recent version, real examples, a clear scope? Thin or abandoned skills lose.
4. **Safety** — a `⛔ RISKY` scan result disqualifies unless the user accepts the risk knowingly; `⚠ caution` needs a heads-up.
5. **Cross-posting** — present on both registries is a mild positive (independently published/maintained).

**Step 3 — Break ties** by preferring the one you actually read and can vouch for, with the narrowest clear scope and fewest surprising dependencies.

**Step 4 — Deliver a verdict, not a menu:**
- One **primary recommendation** with a one-sentence *why* citing concrete signals ("12k installs, and its SKILL.md covers form-filling specifically, which is your case").
- 1–2 **alternatives framed by need** ("pick this instead if you want X").
- If the best option is