VocalFuse is a Fuse Intelligence product.

SKILLS.SH API

Skills.sh API: the 2026 Developer Guide — Endpoints, OIDC Auth, and the npm Comparison

skills.sh — Vercel's registry and leaderboard for the open Agent Skills standard — shipped a public REST API on June 5, 2026 (Vercel changelog, Andrew Qu). Five documented /api/v1/ endpoints cover the catalog: a paginated leaderboard with all-time / trending / hot views, fuzzy + semantic search, the curated first-party set, per-skill detail with the full file tree, and the security-audit endpoint with normalized verdicts from five partners. Auth is a Vercel OIDC token — no static key to leak — rate-limited to 600 requests/minute per team and project. This page is the endpoint reference, the auth walkthrough, the npm mental model (what matches, what skills don't do yet: no version pinning, no lockfile by default), and where the API fits next to the marketplace routes that actually pay skill creators.

Jump to the endpoint table Security: the audit endpoint in context

The five endpoints, in one table

Every endpoint is GET, served under https://skills.sh/api/v1/, and returns JSON. The id field returned by every listing and search call — stable format {source}/{slug} — is the key that builds detail and audit paths. Responses carry Cache-Control: leaderboard and search cache 30–60 seconds, detail and curated 5 minutes — poll at those intervals or get 429s.

Endpoint Returns Key parameters
GET /api/v1/skills Paginated leaderboard: id, slug, source, installs, installUrl, page URL view = all-time (default) / trending / hot; page 0-indexed; per_page 1–500 (default 100). Hot view adds installsYesterday + change vs same hour yesterday.
GET /api/v1/skills/search Search results + the query echo + searchType + count + durationMs q required, min 2 chars; limit 1–200 (default 50); optional owner to scope to one GitHub owner across all their repos. Single-word queries use fuzzy matching, multi-word semantic search — the response's searchType tells you which ran.
GET /api/v1/skills/curated The official curated set: per-owner groups with totalInstalls + featured skill, same dataset as skills.sh/official None. "The makers teaching you how to use their product" — first-party skills from the vendors of the technology the skill teaches. Each owner's skills array uses the same V1Skill shape as every other endpoint.
GET /api/v1/skills/{source}/{skill} One skill's install count, content hash, and the full file tree with file contents — SKILL.md and every bundled file Path format by source type: GitHub /api/v1/skills/vercel-labs/skills/find-skills; well-known /api/v1/skills/mintlify.com/mintlify. Build paths from the listing's id.
GET /api/v1/skills/audit/{source}/{skill} Security audit array from all available partners: Gen Agent Trust Hub, Socket, Snyk, Runlayer, ZeroLeaks Each entry: provider, status (pass / warn / fail), summary, auditedAt, riskLevel NONE–CRITICAL, Agent Trust Hub categories. Returns 404 until a partner has audited the skill — audits generate automatically after a skill's first install, with a minutes-scale delay.

Duplicate handling: the skill object carries an isDuplicate flag "present and true if this skill is a detected fork/copy of another" — omitted when false. Filter on it when you build leaderboards or aggregators, or your counts will double-count forks.

Authentication: Vercel OIDC, no static key

All endpoints require auth, and there is no dashboard signup: if your app runs on Vercel, you authenticate with the project's OIDC token. Vercel mints a short-lived JWT per request, scoped to your team and project, verified against oidc.vercel.com — no long-lived secret to leak or rotate (Vercel changelog, June 5 2026). Read process.env.VERCEL_OIDC_TOKEN fresh per request — do not cache the string — or use getVercelOidcToken() from @vercel/oidc. The raw header form for parity with other Vercel services is x-vercel-oidc-token.

The docs also carry a static-key path: older doc snapshots list API keys issued on request (email skills-api@vercel.com) with an sk_live_... Authorization Bearer header. GitHub issues #1053 and #1369 in vercel-labs/skills show developers requesting keys after getting 401 authentication_required, with the documented channel being email — and issue #1369 was closed as completed, so the key path works. If you are not on Vercel, request a key by email and pass it the same way: Authorization: Bearer header.

What Vercel records: every authenticated request is logged with owner_id (team), project_id, and environment (production / preview / development) extracted from the verified token — the raw token is never stored. Every response returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; when you trip the limit you get a 429 with a Retry-After header. Respect the documented cache windows (30–60s list/search, 5 min detail/curated) and 600/min is far more than a sync job needs.

skills.sh vs npm: what maps, what doesn't (yet)

The "npm for skills" framing is real — Rauch launched it that way January 20, 2026 — but it maps cleanly only on the install side. Here is the honest table:

Concept npm skills.sh / skills CLI
Manifest package.json .skills.json records installed skills (name, remote, version: latest)
Lockfile package-lock.json — exact resolved versions, committed skills-lock.json with content hashes — but only via the experimental commands; plain npx skills add fetches from main with no version constraint. A skill that worked yesterday can behave differently today after an upstream push.
Install npm install / npm ci npx skills add / npx skills experimental_install (replays the lockfile)
Install target node_modules/ Agent directories: .claude/skills/, .agents/skills/, ~<agent>/skills/ — symlink (default; git pull updates) or --copy
Registry npmjs.com GitHub itself is the registry — skills.sh is the telemetry leaderboard + search + audits layer on top
Publish npm publish (account, review-free but versioned) Push SKILL.md to a public GitHub repo — no account, no submission flow; discovery is telemetry. skills.sh.json groups a multi-skill repo; the blob-cache powers the site while the CLI reads git directly.
Security npm audit, provenance attestation, SBOM tooling — a decade of tooling Five-partner audit endpoint + Socket continuous scanning; but Trail of Bits demonstrated bypasses (docx payloads, .pyc bytecode) in under an hour each — treat audit-pass as evidence, not clearance.
Versioning semver ranges, dist-tags, lockfile-pinned No semver — skills are git-versioned text. Pin the commit hash yourself and read the diff before updating.
Update npm update npx skills update — powered by skills-lock.json content hashes
Uninstall npm uninstall npx skills remove — with the documented footgun: remove leaves the lockfile entry intact, so a later experimental_install resurrects it; delete the entry from .skills.json and skills-lock.json too.

The versioning gap is the ecosystem's biggest honest caveat: skills are git-versioned text, the CLI's own lockfile is experimental, and npx skills add fetches from main with no pin by default. Pin the commit hash, read diffs, and treat lockfile reproducibility as something you assemble yourself for now.

Ecosystem by the numbers

Jan 20, 2026

Launch day: Rauch's "npm for AI skills" announcement; top skill hit 20,000 installs within 6 hours; Stripe shipped a skill same day; 110,000+ installs across 17 agents in the first four days.

4M installs

BuzzRAG's Skills Night coverage: 4M cumulative installs across 75,000 unique skills — up from 62,000 the prior week (the numbers move at launch-week speed). Earlier 2026 independent research tallied ~669,670 listed skills.

70+ agents

The CLI README claims 70+ compatible agents; the directory telemetry tracks 20+. Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini CLI, Zed, Cline, Roo, Goose, Amp, Antigravity.

600 req/min

API rate limit per (team, project), enforced per Vercel OIDC token, with standard X-RateLimit headers + Retry-After on 429.

What to build on the API (and where monetization actually lives)

The API unlocks the obvious sync jobs — internal leaderboards, install-count trend tracking, security-queue automation (audit-endpoint polling with warn/fail triage), skill-inventory dashboards. It does not unlock payments: skills.sh is free distribution with no payouts — the directory aggregates telemetry, it does not run checkout. Creators monetize skills on marketplaces with published revenue shares — the VibeFuse marketplace pays a flat 80% via Stripe Connect on widgets, skills, and styling packs with creator-set pricing and live previews before purchase.

The portable asset is unchanged either way: the SKILL.md standard — YAML frontmatter (name, description, optional allowed-tools) plus Markdown instructions — loads in Claude Code, Codex CLI, and the 70+ agents the CLI targets. Inside VibeFuse, the first ever free widget-based AI harness, the same SKILL.md standard loads locally on your Windows machine: local/offline processing, code never uploads, works in any app — and the same skills you install via npx skills add work in the VibeFuse skills directory because the format is the same.

Read next

The security layer

What the five partner scanners cover and miss, the 2026 attack ledger, and the 7-layer install checklist on AI skill supply chain, plus the pre-install audit guide are Claude skills safe.

Registry landscape

Leaderboards vs curated repos vs aggregator scrapers compared in the agent skills directory guide, and where the Claude skills marketplace surfaces sit in 2026.

Where creators earn

skills.sh is free distribution — monetization needs payment rails: sell AI skills, real creator earnings on how much skill creators earn, and the open-source AI marketplace landscape.

Skills.sh API FAQ

Does skills.sh have an API?

Yes - a public REST API shipped June 5, 2026 (Vercel changelog). Five documented GET endpoints under https://skills.sh/api/v1/: /skills (paginated leaderboard with all-time, trending, and hot views), /skills/search (fuzzy + semantic), /skills/curated (the official first-party set), /skills/{source}/{skill} (detail with install count, content hash, and the full file tree), and /skills/audit/{source}/{skill} (security audits from five partners). Responses are JSON; leaderboard and search cache 30-60 seconds, detail and curated 5 minutes.

How do I authenticate against the skills.sh API?

With a Vercel OIDC token: if your app runs on Vercel, read process.env.VERCEL_OIDC_TOKEN fresh per request (or getVercelOidcToken() from @vercel/oidc) and pass it as an Authorization: Bearer header. Vercel mints a short-lived JWT per request scoped to your team and project, verified against oidc.vercel.com - no static secret to leak or rotate. The raw header form x-vercel-oidc-token also works. Not on Vercel: the docs list API keys issued on request (email skills-api@vercel.com) passed the same way as Bearer headers; GitHub issues #1053 and #1369 in vercel-labs/skills document the key-request flow, and #1369 was closed as completed.

What is the skills.sh API rate limit?

600 requests per minute, enforced per (team, project) on authenticated requests. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceed it and you get 429 with a Retry-After header. Errors are uniform JSON ({error, message}): 400 invalid parameters, 401 missing/invalid/expired token, 404 skill not found, 429 rate limit, 503 temporarily unavailable.

How do I check a skill's security audit via the API?

GET /api/v1/skills/audit/{source}/{skill} (build the path from any listing's id field). It returns an array of partner audits - Gen Agent Trust Hub, Socket, Snyk, Runlayer, ZeroLeaks - each with a normalized status (pass / warn / fail), a riskLevel NONE through CRITICAL, a one-line summary, an auditedAt timestamp, and Agent Trust Hub categories. The endpoint returns 404 until a partner has audited the skill; audits generate automatically after a skill's first install, with a minutes-scale delay. Treat a pass as evidence, not clearance - Trail of Bits demonstrated bypasses of all three skills.sh-integrated scanners in 2026.

Is skills.sh really npm for skills?

On distribution, yes: one-command install (npx skills add owner/repo) into 70+ agents, GitHub as the registry, a telemetry leaderboard, and free publishing by pushing SKILL.md to a public repo - no account, no review. On package management, not yet: no semver, no default lockfile (the skills-lock.json commands are experimental), and plain npx skills add fetches from main with no version constraint. npm has a decade of lockfile, provenance, and audit tooling; the skills ecosystem launched January 20, 2026 and is a year into building the same rigor.

What is the skills CLI command set?

npx skills add owner/repo (install, --skill to pick specific skills, --agent to target agents, --copy instead of symlinks, --global for user scope), npx skills find (search the directory), npx skills list, npx skills update, npx skills remove, and npx skills init (scaffold a SKILL.md). Symlink installs update with a git pull; remove leaves the skills-lock.json entry behind unless you also delete it from .skills.json and the lockfile, so a later experimental_install can resurrect the skill.

Can I make money from skills I publish to skills.sh?

Not through skills.sh itself - it is free distribution with no payouts; the directory aggregates install telemetry and does not run checkout. Monetization requires a marketplace with payment rails and a published revenue share: the VibeFuse marketplace pays a flat 80% on widgets, skills, and styling packs via Stripe Connect with creator-set pricing and live previews before purchase. The same SKILL.md standard loads in both, so publish to skills.sh for reach and sell where creators get paid - the two are complementary, not competing.

How do I install skills programmatically without scraping?

Two supported routes. Pull metadata, search results, and full file trees from the /api/v1/ endpoints (600 req/min, cache-aware) and write them wherever you need them - the detail endpoint returns the complete file tree with contents, so a sync job never needs to scrape pages. Or drive the CLI itself: npx skills add --list to enumerate a repo's skills and --all/--skill for scripted installs, with skills-lock.json content hashes powering reproducible experimental_install replays. Legacy /api/search and /api/download paths still respond but the documented surface is /api/v1/.

Ship skills where creators get paid

VibeFuse runs the same SKILL.md standard locally on Windows — the free widget-based AI harness — and the open marketplace pays widget, skill, and styling-pack creators an 80% revenue share via Stripe Connect.

Download VibeFuse free Browse the marketplace

Explore VibeFuse & harness guides