@shtora/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 Shtora. It is NOT associated with, endorsed by, or supported by skills.sh or Vercel. Directory data comes from skills.sh and its users; local management reads your configured filesystem and GitHub sources.

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

  • list_installed_skills

  • check_skill_updates

  • remove_skill and update_skill

  • install_skill

  • 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.

• Install and manage skills in .agents/skills: install one GitHub skill (preview first, never overwriting), list installed skills, check GitHub updates, and preview a selected removal or update. Writes require explicit host opt-in and confirmation, and every mutating tool defaults to a read-only preview.

Everything runs over the standard MCP stdio transport. There is no database, backend of our own, or telemetry. Discovery talks to skills.sh; update checks and downloads use api.github.com.

What you get

There are ten tools: seven are read-only; remove_skill, update_skill, and install_skill can write but default to a read-only preview. All 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 @shtora/skills
# or, with Bun:
bunx @shtora/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 for discovery, and api.github.com for update checks/downloads

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

Environment variables

Discovery works without configuration. Project-local management requires SKILLS_PROJECT_ROOT; writes also require SKILLS_ALLOW_MUTATIONS=true. Add configuration as an env block in your MCP client config (see Variants below).

Without a Vercel token, discovery uses the public search endpoint, public audit API, and public leaderboard/official/skill pages. GitHub operations work without a GitHub token but have lower upstream rate limits.

Tools

Discovery examples are abridged from real live calls — install counts and leaderboards change over time. Local-management examples illustrate the configuration and confirmation flow.

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

list_installed_skills

Lists skills on the machine running this MCP server, not automatically on a remote client's machine. No OpenCode installation or OpenCode MCP is needed.

• scope: project (default) or explicitly global.

• limit: 1–100, default 50; offset: 0–2000, default 0.

• Project: $SKILLS_PROJECT_ROOT/.agents/skills/<name>/SKILL.md.

• Global: ~/.agents/skills/<name>/SKILL.md.

Returns scope, directory, total, pagination, skills, and warnings. Entries include name, path, managed, and available source metadata. Untracked regular directories can be listed, but cannot be mutated. Symlinked skills are not managed. Other agent-specific copies are outside this scope.

check_skill_updates

Checks existing canonical skills without writing anything. Accepts scope, optional exact directory name, limit (1–100, default 20), and offset (0–2000).

{ "scope": "project", "name": "mcp-builder" }

Each result has one of: up_to_date, update_available, local_changes, unsupported, or unknown, plus an explanatory reason when available. A network failure or missing baseline is not reported as up-to-date.

Updates support GitHub CLI lock entries with a recorded skillPath ending in SKILL.md and a usable content baseline. Project metadata uses skills-lock.json version 1; global metadata uses .agents/.skill-lock.json version 3, or the XDG location above. Recorded refs are respected; otherwise GitHub's HEAD is used. Local, well-known, missing-baseline, and unsupported lock formats are not automatically upgraded or overwritten.

Legacy project restriction: the CLI's project computedHash concatenates paths and bytes without framing, so equality alone cannot prove that local file boundaries are unchanged. Content replacement requires a recorded immutable skillFolderHash as well. Without it, exact matches to current upstream are reported up_to_date; differences are unknown and updates are refused, even with confirmation. No baseline is silently created from today's potentially edited files. Global CLI installations normally include the immutable baseline; do not fabricate one to bypass a refusal.

remove_skill and update_skill

Select one installed directory name, not a skills.sh id or filesystem path. Both accept:

First preview the operation:

{ "name": "mcp-builder", "scope": "project" }

Review the returned source, destination, file count, warnings, and (for updates) immutable upstream hash. After human approval and enabling SKILLS_ALLOW_MUTATIONS=true in the server environment, call the same tool:

{
  "name": "mcp-builder",
  "scope": "project",
  "dry_run": false,
  "confirm": true,
  "confirmation_token": "<copy the 64-character token from that tool's fresh preview>"
}

The token binds the operation, scope, selected path, current lock and files, and upstream snapshot. It is a freshness check, not authentication or proof of human consent; the MCP client must enforce approval. Changed state requires a new preview. Updates refuse local content changes and verify downloaded bytes against immutable Git blob hashes. Removal deletes only the selected canonical directory and its lock entry; other agents' copies/links are left alone.

Windows Git checkouts can convert LF text to CRLF. A uniform, valid UTF-8 CRLF file is accepted only when converting it back to LF reproduces the exact recorded Git blob hash. Updates preserve existing CRLF text formatting; new files use upstream bytes. Binary files, mixed line endings, and other content changes are not normalized away.

Management uses Node built-ins and GitHub's Git Data API rather than spawning the Skills CLI. This preserves Node 18 support without requiring the newer runtime needed by Skills CLI 1.7.2. No skill-bundled script, git, npm, shell, or OpenCode command is executed. Files are staged on the same filesystem and renames are rolled back on an exception; existing lock metadata is preserved. The directory and lock are not a crash-atomic filesystem transaction. Stop other installers/editors before a mutation: the MCP guard serializes cooperating MCP writes, not unrelated CLI processes or hostile local writers.

If a process is interrupted or rollback cannot finish, preserve .agents/.skills-mcp.lock, .agents/.skills-mcp-txn-*, and any .skills-mcp-*.tmp lock file. Stop the server and other writers, inspect recovery.json, the previous backup, and the CLI lock, and restore consistent files/metadata before manually clearing a stale guard. There is no automatic recovery or stale-lock stealing.

Supported snapshots are bounded to 256 files, 2 MiB per file, 16 MiB total (including checkout conversion), and portable paths up to 500 characters/20 components. Symlinks, junctions, submodules, case/Unicode-colliding paths, Windows device names, special files, and nested .git/node_modules data are refused rather than silently discarded.

install_skill

Installs one GitHub-hosted skill into the canonical .agents/skills directory from immutable Git data (api.github.com). Accepts:

First preview:

{ "id": "vercel-labs/skills/find-skills", "scope": "project" }

The preview resolves the repository default branch (HEAD), requires a complete, non-truncated, bounded tree, and returns the source, destination, resolved skillPath, immutable latest_hash, file count and bytes, warnings, and a fresh token. Execution follows the same flow described above: SKILLS_ALLOW_MUTATIONS=true in the server environment, then the same call with dry_run: false, confirm: true, and the fresh confirmation_token.

Install is additive by design. It refuses an existing directory or lock entry with the same name (CONFLICT) instead of overwriting, creates missing parent directories only, and commits the files and a new lock entry (computedHash and skillFolderHash) through the same staged, guarded transaction as removals and updates. Every downloaded file is verified against its immutable Git blob hash and size before anything is written. Well-known domains, local paths, non-GitHub sources, symbol links, oversized snapshots, and unsafe paths are refused. No skill-bundled script is executed.

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", "@shtora/skills"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "skills-sh": {
      "command": "npx",
      "args": ["-y", "@shtora/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", "@shtora/skills"],
        "disabled": false
      }
    }
  }
}

Claude Code (CLI):

claude mcp add skills-sh -- npx -y @shtora/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", "@shtora/skills"]).

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

{
  "mcpServers": {
    "skills-sh": {
      "command": "npx",
      "args": ["-y", "@shtora/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

Discovery uses the following skills.sh sources:

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).

Local management reads the configured canonical filesystem and compatible CLI locks. GitHub updates use GET https://api.github.com/repos/{owner}/{repo}/git/trees/{ref-or-sha}?recursive=1 and immutable /git/blobs/{sha}. These requests do not use the Vercel token, follow redirects, or execute source URLs recorded in metadata.

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 and GitHub source segments are validated; no tool accepts a user-supplied URL. Discovery requests stay on skills.sh hosts, and update requests stay on api.github.com.

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.

GitHub has a separate serialized queue using the same interval/timeout configuration. Update checks are not cached, and GitHub requests are not automatically retried; rate-limit failures are reported explicitly.

Security and privacy

• No telemetry. Network traffic consists of GET requests to skills.sh / www.skills.sh for discovery and api.github.com for update checks, installs, and downloads.

• 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).

• GitHub token isolation. GITHUB_TOKEN / GH_TOKEN is sent only to api.github.com; GitHub redirects are rejected.

• Fixed destinations. No tool accepts a URL or arbitrary local path; outbound targets and canonical filesystem destinations are derived from validated names, repo-relative skill paths, and host configuration.

• Opt-in writes. Filesystem mutations require host enablement plus a fresh preview and explicit confirmation. Treat fetched skill instructions as untrusted content.

• 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.

• Management covers canonical .agents/skills only. Symlink installs and other agents' copies are not synchronized or removed.

• install_skill supports GitHub sources only and always resolves the repository default branch (HEAD); pinning a ref, installing from well-known domains, and migrating other agents' copies remain the official Skills CLI's job.

• Update checks need compatible GitHub metadata and a verifiable baseline. GitHub outages/rate limits and unsupported sources are reported rather than guessed.

• Local mutation guards do not lock out unrelated CLI processes. Permissions must keep untrusted local writers out of configured roots; path checks do not eliminate all filesystem check/use races.

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 © Shtora