@hallaxius/skills

An unofficial Model Context Protocol (MCP) server that exposes skills.sh — The Agent Skills Directory — as tools for AI agents and coding assistants.

Not affiliated. This is an independent community project maintained by Hallaxius. It is NOT associated with, endorsed by, or supported by skills.sh or Vercel. All data served by this server belongs to skills.sh and its users, and is fetched live from the public site.

Table of contents

• Overview

• What you get

• Quick start

• Requirements

• Environment variables

• Tools

  • search_skills

  • get_top_skills

  • get_skill

  • get_skill_audits

  • get_official_skills

  • Validation caps quick reference

• MCP client configuration

• How it works

  • Data sources

  • Skill id format

  • Caching

  • Rate limiting

  • Security and privacy

  • Error handling

• Troubleshooting

• Limitations

• Legal notes

• License

Related MCP server: skillet

Overview

This server lets any MCP-capable client query skills.sh directly:

• Discover skills by keyword, by owner, or through the official leaderboards (all-time, trending, hot).

• Inspect a skill: full description, install count, topics, related skills, ready-to-use install command.

• Vet a skill before installing it: aggregated security audits from Socket, Snyk, Gen Agent Trust Hub, Runlayer and ZeroLeaks.

• Browse the official/curated directory of trusted owners (Vercel, Anthropic, Microsoft, Google, Supabase, Cloudflare, ...).

• Install what you find with the official npx skills CLI — every result includes the exact command to run.

Everything runs over the standard MCP stdio transport. There is no database, no backend of our own, and no telemetry: the server talks only to skills.sh.

What you get

All five tools are read-only, return a single pretty-printed JSON text block, and report failures as MCP tool errors with a stable [CODE] message prefix.

Quick start

Run the published package directly — nothing to install:

npx -y @hallaxius/skills
# or, with Bun:
bunx @hallaxius/skills

The server starts on stdio and waits for an MCP client. Point your client's MCP config at the command above (see MCP client configuration), then ask your agent things like "find a skill for React performance auditing on skills.sh".

Requirements

• Node.js 18 or newer (for npx), or Bun

• An MCP-capable client (Claude Desktop, Claude Code, Cursor, OpenCode, ...)

• Internet access to skills.sh

That's all — the server has no other dependencies or services.

Environment variables

All optional — the server is fully functional with none of them set. Add them as an env block in your MCP client config (see Variants below).

Without a token the server still works fully: it uses the public search endpoint that the official npx skills CLI itself uses, the public audit API, and the same leaderboard/official/skill pages you see in the browser.

Tools

Examples below are abridged from real live calls — install counts and leaderboards change over time.

search_skills

Search skills.sh for skills matching a query.

Arguments

Example call

{
  "query": "react",
  "limit": 3
}

Example response (public mode, abridged — the response is a JSON array)

[
  {
    "id": "vercel-labs/json-render/react",
    "source": "vercel-labs/json-render",
    "skillId": "react",
    "name": "react",
    "installs": 11446,
    "installCommand": "npx skills add https://github.com/vercel-labs/json-render --skill react"
  },
  {
    "id": "lobehub/lobehub/react",
    "source": "lobehub/lobehub",
    "skillId": "react",
    "name": "react",
    "installs": 5516,
    "installCommand": "npx skills add https://github.com/lobehub/lobehub --skill react"
  }
]

Response fields

Notes:

• Without a token: fuzzy search via the public endpoint (the same one the official CLI uses), no descriptions in results (the endpoint does not return them).

• With VERCEL_OIDC_TOKEN: searches go through the documented v1 API, which adds semantic multi-word ranking and the v1-only fields above. If the token is rejected (expired), the server logs a warning to stderr and transparently falls back to the public endpoint.

get_top_skills

Read a skills.sh leaderboard. Each leaderboard page embeds up to 600 entries; use offset to page through them.

Arguments

Example call

{
  "view": "hot",
  "limit": 3
}

Example response (abridged)

{
  "view": "hot",
  "offset": 0,
  "count": 3,
  "totalAvailable": 600,
  "skills": [
    {
      "id": "uizze.sh/ui-taste",
      "source": "uizze.sh",
      "skillId": "ui-taste",
      "name": "ui-taste",
      "installs": 762,
      "installsYesterday": 222,
      "change": 540
    }
  ]
}

Response fields

get_skill

Full details for a single skill.

Arguments

Example call

{
  "id": "vercel-labs/skills/find-skills"
}

Example response (abridged from a live call)

{
  "id": "vercel-labs/skills/find-skills",
  "source": "vercel-labs/skills",
  "slug": "find-skills",
  "name": "find-skills",
  "description": "Helps users discover and install agent skills when they ask questions like \"how do I do X\", \"find a skill for X\" ...",
  "owner": "vercel-labs",
  "installs": 3539262,
  "url": "https://www.skills.sh/vercel-labs/skills/find-skills",
  "installCommand": "npx skills add https://github.com/vercel-labs/skills --skill find-skills",
  "topics": ["agents"],
  "related": [
    {
      "id": "anthropics/skills/frontend-design",
      "name": "frontend-design",
      "description": "..."
    }
  ]
}

Response fields

Calling include_files: true without a token returns [INVALID_INPUT] with instructions on how to enable it (metadata above is still available without a token).

get_skill_audits

Security audits recorded for a skill. Audits are produced by third parties after a skill's first install; a skill that was never installed/audited returns NOT_FOUND with a message explaining that.

Arguments

Example call

{
  "id": "vercel-labs/skills/find-skills"
}

Example response (abridged from a live call — 5 providers were returned)

{
  "id": "vercel-labs/skills/find-skills",
  "source": "vercel-labs/skills",
  "slug": "find-skills",
  "audits": [
    {
      "provider": "Gen Agent Trust Hub",
      "slug": "agent-trust-hub",
      "status": "pass",
      "summary": "This skill facilitates the discovery and installation of agent extensions using a dedicated command-line interface ...",
      "auditedAt": "2026-09-15T08:00:05.922Z",
      "riskLevel": "SAFE",
      "categories": ["..."]
    }
  ]
}

Response fields

This tool works without any token (the audit endpoint is public).

get_official_skills

Official/curated skills grouped by owner — the same dataset as the skills.sh /official page. The real list currently has roughly 100 owners.

Arguments

Example call

{
  "limit": 2
}

Example response (shape, abridged)

{
  "count": 2,
  "owners": [
    {
      "owner": "aave",
      "totalInstalls": 10,
      "featuredRepo": "aave/skills",
      "featuredSkill": "deleverage",
      "repos": [
        {
          "repo": "aave/skills",
          "totalInstalls": 10,
          "skills": [
            { "name": "deleverage", "installs": 2 }
          ]
        }
      ]
    }
  ]
}

Response fields

Validation caps quick reference

Violations are rejected before any network activity and surface as tool errors whose text starts with Input validation error.

MCP client configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "skills-sh": {
      "command": "npx",
      "args": ["-y", "@hallaxius/skills"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "skills-sh": {
      "command": "npx",
      "args": ["-y", "@hallaxius/skills"]
    }
  }
}

OpenCode (opencode.json in the project, or ~/.config/opencode/opencode.json globally):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "skills-sh": {
        "type": "local",
        "command": ["npx", "-y", "@hallaxius/skills"],
        "disabled": false
      }
    }
  }
}

Claude Code (CLI):

claude mcp add skills-sh -- npx -y @hallaxius/skills

Any other MCP client that supports local stdio servers: use the standard mcpServers shape from the Claude Desktop example above.

Variants

• Prefer Bun? Replace npx -y with bunx (["bunx", "@hallaxius/skills"]).

• Need the token or tuning knobs? Add an env block to the server entry, for example:

{
  "mcpServers": {
    "skills-sh": {
      "command": "npx",
      "args": ["-y", "@hallaxius/skills"],
      "env": {
        "VERCEL_OIDC_TOKEN": "your-token-here",
        "SKILLS_MIN_INTERVAL_MS": "500"
      }
    }
  }
}

Avoid pasting the token into the file when the client supports environment substitution (OpenCode: "VERCEL_OIDC_TOKEN": "{env:VERCEL_OIDC_TOKEN}").

How it works

Data sources

The server uses only sources that skills.sh itself sanctions for programmatic use:

1. Public search API — GET https://skills.sh/api/search (unauthenticated). The same endpoint used by the official npx skills CLI (skills find).

2. Documented v1 API — https://skills.sh/api/v1/* per skills.sh/docs/api. Search and skill files require VERCEL_OIDC_TOKEN (Bearer auth); the audit endpoint works unauthenticated. With a token configured, search_skills upgrades to v1 search (fuzzy/semantic).

3. Public site pages — /, /trending, /hot, /official, and skill pages, read from their embedded structured data (never visual scraping of markup).

Which tool uses what:

A token therefore only unlocks two things: semantic search and file contents.

Skill id format

Every id is {source}/{slug}:

Ids are strictly validated and request URLs are assembled only from validated segments — the server never accepts a user-supplied URL, so every outbound request stays on skills.sh.

Caching

Results are cached in memory:

Rate limiting

Requests to skills.sh are deliberately paced:

• Serialized with a minimum gap (default 500 ms), so concurrent calls don't burst the site.

• Timeout per request (default 10 s) with up to 2 automatic retries on transient failures.

• 429 responses are honored via Retry-After; if the limit persists you get [RATE_LIMITED] — just wait a moment and retry.

The first call after idle time takes around half a second; cached repeats need no request.

Security and privacy

• No telemetry. No analytics, no phone-home, no third-party endpoints. The only network traffic is GET requests to skills.sh / www.skills.sh.

• Token handling. VERCEL_OIDC_TOKEN is sent only as a Bearer header to the skills.sh v1 API, never logged, and never sent anywhere else. Expiry degrades gracefully (search falls back to the public endpoint).

• No SSRF. No tool accepts a URL; all request targets are assembled from validated id segments on fixed skills.sh hosts.

• Protocol hygiene. stdout carries only MCP JSON-RPC; every log line goes to stderr.

Error handling

Tool failures are returned as MCP tool errors (isError: true) with a stable [CODE] message prefix:

Example error result:

{
  "content": [
    {
      "type": "text",
      "text": "[NOT_FOUND] no security audits recorded for \"vercel-labs/skills/find-skills\" yet — audits are generated automatically after a skill's first install"
    }
  ],
  "isError": true
}

Troubleshooting

Limitations

• The public search endpoint is undocumented (it is the one the official CLI uses); if skills.sh changes it, no-token search may report UPSTREAM_CHANGED until the package is updated.

• Without a token: search is fuzzy only (no semantic multi-word ranking), search results carry no descriptions, and get_skill cannot return file contents.

• Leaderboard pagination is capped at what pages embed (offset 0–290).

• weeklyInstalls values are passed through as-is from the site.

• Data freshness follows the Caching TTLs; install counts change continuously on skills.sh itself.

Legal notes

• This project respects robots.txt: only generally-allowed pages (/, /trending, /hot, /official, skill and owner pages) are retrieved.

• skills.sh's terms of use describe a public API that is rate-limited per IP and state: "Reasonable use, including caching results on your own infrastructure, is encouraged and not restricted." This server is built exactly around that contract — rate limiting, caching, an identifiable user agent, and no scraping behind authentication or anti-bot mechanisms.

• This project is unofficial and not affiliated with skills.sh or Vercel. If the operators object to any aspect of it, the right move is to take it down.

License

MIT © Hallaxius