Using SkillMD over MCP

Most people install a skill by browsing the registry, reading a SKILL.md, and running a CLI command by hand. That works fine when a human is in the loop. It breaks down the moment you want an agent to decide, mid-task, that it needs a skill it doesn’t have yet. For that, the agent needs a way to query the registry and pull files onto disk itself, without a person relaying commands.

That’s what the MCP server in the skillmds package is for. It puts the registry behind a small set of tools an MCP client can call directly: search, fetch a record, lint content, install a skill. No REST client to write, no scraping the website.

What the MCP server actually is

skillmds ships two things: a CLI and an MCP server, bundled in the same package. The one you get depends on how you invoke it.

Run it with any argument and you get the CLI: npx skillmd add some-skill, npx skillmd lint, and so on. Run it with no arguments at all and it starts the MCP server instead, speaking stdio transport:

npx -y skillmds

That’s the whole install step. No global install, no separate binary, no port to open. The process reads MCP requests from stdin and writes responses to stdout, which is exactly the shape every MCP client expects when it spawns a local server.

If you’re on Claude Code, there’s a one-liner that registers this for you:

claude mcp add skillmd -- npx -y skillmds

That adds an entry to Claude Code’s MCP config pointing at the same command. Nothing to author by hand.

Wiring it into a generic MCP client

Not every client has a quick-add command, so most of the time you’re editing an MCP config file directly. The shape is the same everywhere: a name, a command, and the arguments that make the process start the server instead of the CLI.

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

Drop that block into whatever config your client reads (Claude Desktop’s config file, a project-level .mcp.json, or your own agent harness’s server list) and restart the client so it picks up the new server. Because the args are empty of subcommands, the process always comes up in MCP mode.

Optional auth

By default the server talks to the public registry with no credentials. Two environment variables change that:

• SKILLMD_TOKEN sets a bearer token, sent on requests that need it.
• SKILLMD_API overrides the API base URL, useful if you’re pointing at a private or self-hosted registry instead of the public one.

Set them the same way you’d set any environment variable for a spawned process, either in the client’s server config (some clients support an env block per server) or in the shell that launches the client.

The tools it exposes

Once the server is running, the client sees a fixed set of tools. Each one maps to something you’d otherwise do through the CLI or the website.

skillmd_search

Takes a query string and optional filters, returns matching skills. This is how an agent finds candidates without knowing exact slugs ahead of time.

skillmd_get

Takes a slug and returns the full record for that skill: metadata, description, tags, and the content an agent would need to decide whether to install it.

skillmd_install

Takes a slug and an optional destination, which defaults to ~/.claude/skills. Before writing anything it lints the skill and refuses to install if linting fails, and it validates the slug so a malformed or malicious value can’t escape the destination directory via path traversal. For a pack (a bundle of multiple skills under one slug), it writes only the top-level SKILL.md and suggests running npx skillmd add <slug> to pull the rest.

One detail worth being explicit about: this tool writes files on whatever machine is running the MCP server. If you’re running the server locally, that’s your machine. If you’ve set up a remote MCP deployment, the files land on that remote host, not on the client’s machine. Worth checking before you assume a skill just appeared in your local skills folder.

skillmd_trending

Returns skills that are seeing above-average install or view activity, useful for an agent that’s browsing rather than searching for something specific.

skillmd_recommend

Returns suggested skills, for agents that want a starting point instead of a keyword search.

skillmd_list_saved

Returns skills saved to an account. Requires a token, so this only works if SKILLMD_TOKEN is set.

skillmd_lint

Runs the same lint checks the registry applies before publishing, against either raw content or a slug already in the registry. Handy for checking a skill you’re drafting before it ever touches the install path.

An agent-native workflow

The point of exposing these as MCP tools instead of a CLI is that an agent can chain them without any shell-parsing or a human relaying output back and forth. A typical sequence looks like this:

1. The agent hits a task it doesn’t have a skill for and calls skillmd_search with a query describing what it needs.
2. It picks a candidate from the results and calls skillmd_get on the slug to read the full record, deciding from the description and content whether it actually fits.
3. Satisfied, it calls skillmd_install with that slug. The server lints the skill server-side, writes SKILL.md (and the rest, for a single skill) to ~/.claude/skills, and returns the result.
4. The agent picks the newly installed skill up on its next turn, same as if a person had run the install command themselves.

No copy-pasting file contents into a prompt, no separate terminal, no round trip through a human to fetch and place files. The agent’s own tool calls are the whole path from “I need X” to “X is on disk and loaded.”

That’s the actual value of putting the registry behind MCP: it turns skill discovery and installation into something an agent can do as part of its own reasoning loop, using the same protocol it already uses for every other tool call.