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 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:

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:

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

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.