Skills Finder

---
name: skills-finder
description: Find Agent Skills on skills.sh and adopt only the ones that pass a security audit. Use when the user wants to discover, search for, evaluate, or install a third-party skill ("find a skill for X", "is this skill safe to install", "search skills.sh", "what skill should I use for Y"). Always runs the skills.sh security audit before recommending or installing anything, and refuses to adopt skills that fail the audit.
---

# Skills Finder

Discover skills on [skills.sh](https://skills.sh) and **gate every candidate
through a security audit before adopting it**. The user's rule is firm: only
adopt skills with no security problems. Never install a skill that has not
cleared the audit.

## Workflow

```
1. DISCOVER   npx skills find "<query>"          → candidate list
2. GATE       scripts/audit.py <candidate>...     → ADOPT / REVIEW / REJECT
3. DECIDE     adopt only ADOPT (or REVIEW after explicit user OK)
4. INSTALL    npx skills add <owner/repo@skill>   → only for approved skills
```

## Step 1 — Discover (no token needed)

Use the `skills` CLI; it handles auth internally, so no Vercel token is required:

```bash
npx -y skills@latest find "<query>"            # e.g. "pdf", "postgres backup"
npx -y skills@latest find "<query>" --owner <github-owner>   # scope to an owner
```

Output lines look like `owner/repo@skill   <N> installs` plus a
`https://skills.sh/owner/repo/skill` URL. Higher installs ≠ safer — still gate.

Other CLI verbs: `npx skills list` (installed), `npx skills add <owner/repo@skill>`
(install), `npx skills use <owner/repo@skill>` (one-off prompt, no install).

## Step 2 — Security gate (MANDATORY, no token needed)

Run every candidate through the audit script. The audit endpoint is public, so
this always works:

```bash
python3 scripts/audit.py <candidate> [<candidate> ...]   # human-readable
python3 scripts/audit.py <candidate> --json              # machine-readable
```

A `<candidate>` is any of: `owner/repo@skill`, `owner/repo/skill`,
`github/owner/repo@skill`, or a full `https://skills.sh/...` URL — paste the
identifier or URL straight from `find` output.

The script queries all providers (Gen Agent Trust Hub, Socket, Snyk, Runlayer,
ZeroLeaks) and prints one verdict per skill. Process exit code = the worst
verdict across all inputs.

## Step 3 — Decide (the policy)

| Verdict | Exit | Meaning | Action |
|---|---|---|---|
| **ADOPT** | 0 | Every provider `pass`; no risk above `NONE`/`SAFE` | Safe to install |
| **REVIEW** | 10 | No `fail`, but a `warn` or `LOW`/`MEDIUM` risk | Do **not** auto-install — show the user the flagged provider + summary and ask before proceeding |
| **REJECT** | 20 | A provider returned `fail`, or risk is `HIGH`/`CRITICAL` | **Refuse.** Do not install. Report which provider failed and why |
| **UNVERIFIED** | 30 | No audits exist yet (`404`) | Treat as not-yet-safe. Do not auto-install; offer to inspect the source first |

Rules:
- **Default to safety.** Only ADOPT installs without asking. REJECT and
  UNVERIFIED are never installed. REVIEW requires explicit user consent and you
  must surface the specific risk (provider, riskLevel, summary).
- When recommending from a list, prefer ADOPT skills. If only REVIEW/REJECT
  skills exist, say so plainly rather than installing a borderline one.
- Always tell the user the verdict and the deciding provider(s) — don't hide a
  warn/fail behind a recommendation.

## Step 4 — Install approved skills

```bash
npx -y skills@latest add <owner/repo@skill>          # project scope
npx -y skills@latest add <owner/repo@skill> --global # user scope
```

To inspect source before trusting a borderline (REVIEW/UNVERIFIED) skill without
installing, use `npx skills use <owner/repo@skill>` or read the files via the
detail endpoint (see references/api-reference.md — needs a Vercel token).

## API details

For raw endpoints, response fields, identifier mapping, and how to obtain a
Vercel OIDC token for the token-gated discovery endpoints, read
**references/api-reference.md**. The everyday flow above needs no token.