MCP server

The skillmds npm package ships two binaries: skillmd, the CLI, and skillmds, an MCP server that gives agents direct access to the registry. Use it when you want an agent to search, install, and lint skills without shelling out to the CLI.

Requirements

Node 18 or later. The server talks over stdio only. It does not listen on a port or accept HTTP connections.

Run it

The command takes no arguments:

npx -y skillmds

This matters because the same package also exposes the skillmd CLI, and any argument passed to skillmds routes to the CLI instead of starting the server. If you run skillmds bare in an interactive terminal, you get the CLI menu, because there's a human at the keyboard instead of a client piping stdin. MCP clients connect by spawning the process and writing to its stdin, which starts the server correctly. Don't add flags or a subcommand to the MCP launch command.

Claude Code setup

Add the server with one command:

claude mcp add skillmd -- npx -y skillmds

Generic client config

For any MCP client that reads a JSON config file, add an entry under mcpServers:

{
  "mcpServers": {
    "skillmds": {
      "command": "npx",
      "args": ["-y", "skillmds"]
    }
  }
}

The server identifies itself as skillmd during the MCP handshake.

Auth

Auth is optional. Every tool works unauthenticated against the public registry except skillmd_list_saved, which needs a signed-in user. Set SKILLMD_TOKEN as an environment variable on the server process to pass a bearer token:

SKILLMD_TOKEN=your-token npx -y skillmds

Without a token, skillmd_list_saved returns a notice telling you to sign in, not an error.

To point the server at a different API base, for example a staging environment or a self-hosted registry, set SKILLMD_API:

SKILLMD_API=https://staging.example.com npx -y skillmds

It defaults to https://api.skillmd.com.

Tools

skillmd_search

Search the registry by name, description, or task. This is the entry point for most agent workflows: describe what you need, get back candidates.

skillmd_get

Fetch one skill's full record: the SKILL.md body, provenance, license, and any security flags.

skillmd_install

Write a skill's SKILL.md to local disk. It runs a lint and validation pass first and refuses to write if that pass fails with errors, so a broken skill never lands on disk silently. The slug is validated to block path traversal.

For a pack, this tool writes only the pack's SKILL.md and suggests running npx skillmd add <slug> for the rest of the pack's files.

This tool writes to whatever machine is running the server. If your MCP client connects to a remote or hosted server, the file lands on that server's disk, not on your laptop. Check where dest resolves before relying on the output.

skillmd_trending

Leaderboard of top skills.

skillmd_recommend

Similar-skill and trending recommendations anchored on a skill you already know.

skillmd_list_saved

List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set on the server process. Without it, the tool returns a notice explaining that, rather than failing.

skillmd_lint

Validate a SKILL.md and get back a score, diagnostics, and any security flags. Pass either raw content or a slug to fetch from the registry first.

Example call using slug:

{
  "slug": "anthropic/pdf"
}