Skill MCP

skill-mcp

An MCP server that serves a directory of Agent Skills. Point it at skills; it lists them, hands out their instructions and their bundled files, and runs only the scripts a skill declares.

It is a generic adapter, not a curated set: the skills are content it reads, and the same build serves whatever it is pointed at.

npx @chrischall/skill-mcp                       # serves the example skill bundled here

SKILLS_DIR=~/my-skills npx @chrischall/skill-mcp

The npm package is `@chrischall/skill-mcp` (unscoped skill-mcp is taken by someone else on npm). Everything else — the repo, the binary, the registry identity io.github.chrischall/skill-mcp — is unscoped.

What a skill is

A directory holding SKILL.md: YAML frontmatter (name, description, and optionally the mcp-host: block below) followed by instructions, plus whatever files those instructions refer to. Three layouts are found under each root:

<root>/SKILL.md              # the root IS one skill

/ /SKILL.md # a directory of skills /skills/ /SKILL.md

A skill is served under its DIRECTORY name, never under the name in its own frontmatter (a frontmatter name that disagrees is reported and otherwise ignored; where the root itself is the skill, the root directory names it). That is a security rule, not a tidiness one: the owner's grant names a skill, so a bundle that could choose its own name could claim its neighbour's and be handed the neighbour's granted script and granted variables. For the same reason, two directories that really do contribute one name — only possible across two roots — have both refused and reported, rather than one of them winning by scan order.

The tools

skill_file takes a paths[] batch, so the files a SKILL.md points at come back in one round trip: at most 8 paths per call, 1 MiB per entry and 4 MiB per call (summed from file sizes before a byte is read, so the answer never depends on the order the paths were listed in). One bad path fails only its own entry — the rest of the batch is still served. Read the caps as bounds on this server's own heap: they cap the allocation, not only the answer, because a hosted child has a hard 256 MiB data limit and a bundle may be larger than that.

Each skill is also registered as an MCP prompt (its body is the message) and each bundled file as a resource (skill:// / ), because a client that supports those surfaces presents a skill better than a tool call does. It is a second door, never the only one: when this server runs on mcp-host and a registration narrows enabledTools, prompts/list and resources/list come back empty and the handshake stops advertising those capabilities — so the tools carry the whole experience.

Discovery reports, it never goes quiet

Anything that keeps a directory from being served comes back in skill_list's problems, with the path and the reason: no SKILL.md, frontmatter that will not parse, a name two directories both claim (both refused), a declared script that is not in the bundle, a symlink leading out of the root or out of a skill, a filename the read tools could not address. One bad skill costs itself and never the listing, and there is no third outcome where something is dropped in silence — a symlinked skill directory is served when it stays inside the root (so skills/foo -> ../shared/foo works) and reported when it does not. It is served under its *target* directory's name — skills/foo -> ../bar is the skill bar, reported as a name-mismatch so a grant is written against the right name — and a directory reached twice (a link to a skill that is also listed directly) is one skill, not a duplicate.

Problem reasons

Each entry in problems is {path, reason, detail}. detail is prose for a person; reason is the stable value to switch on.

The set is additive. New reasons arrive without a major version bump (environ-unscrubbed is the most recent), so a client that switches on reason must treat a value it does not recognise as a generic problem and show its detail, never fail on it.

The execution fence

skill_run executes third-party code. Every rule below narrows which code runs and what it is handed; each has its own test.

• Only a script the skill DECLARES. Not "any file under scripts/", not "anything executable". An undeclared path is refused, saying it must be declared and listing the ones that are.
• Only inside that skill's own directory. The path is checked as a string first (plain segments; no leading /, no . or .., no backslash, no percent escape, no NUL) and then again after resolution: the real path, with symlinks followed, must still be inside the skill's real directory, and it must be a regular file. Both checks, because a string check alone misses a symlink planted inside the bundle and a resolved check alone accepts shapes that should never have been joined. The same discipline governs skill_file: a read out of a skill directory is another skill's bundle at best.
• An argv array, never a shell string. spawn with shell: false, no interpolation, no sh -c. Arguments are passed through verbatim.
• An interpreter from a closed set, named by the declaration — never inferred from the extension and never taken from the file's own shebang, since a file that can choose its own interpreter has already chosen its own program. v1 runs `node` and nothing else (see *What v1 cannot run*).
• Bounded, and the call always returns. A wall-clock timeout (60 s default, per-script override, hard 300 s ceiling), 1 MiB captured per stream with truncated: true rather than a silent cut, and one skill_run at a time. On timeout the process group is signalled, which reaches the script and any child that stayed in its group. It does not reach a grandchild that detached into a group of its own, and such a grandchild also holds the stdio pipes open — so the run settles on the process exiting plus a short drain, under a hard deadline, rather than on the pipes closing. That is what guarantees the tool call returns within its budget and frees the one-at-a-time lock; it is not a guarantee that a deliberately detached grandchild is dead. Bounding *that* is the tier's job (an unprivileged uid, prlimit NPROC, and a machine that stops), not this adapter's.
• An env allowlist. A script gets PATH, HOME, LANG, TZ, TMPDIR, MCP_DATA_DIR when the host set one, the egress proxy variables (HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy, NO_PROXY, no_proxy, NODE_USE_ENV_PROXY) when the host set them — on mcp-host's isolated tier the network is fenced and a script without them cannot reach even an allowlisted host — and exactly the variables that script asked for and the owner granted — never this server's own environment. The fixed half mirrors mcp-host's INSTALL_ALLOWLIST (packages/runner-node/src/spawn-env.ts), for the reason that file gives: a host constant a hosted declaration cannot widen by one name. This decides what a script is handed, not what a hostile script can reach. A script runs as the same uid as this server. On Linux a same-uid process can read /proc/ /environ, so at boot the server wipes that exec-time environment block (src/scrub-environ.ts; process.env keeps every value) and that one-line read comes back empty. If a kernel or sandbox refuses that wipe, a hosted server runs no script at all — skill_run refuses and skill_list reports environ-unscrubbed — unless the owner sets MCP_SKILL_ALLOW_UNSCRUBBED=1; standalone it only warns on stderr. The values still live in the server's memory, reachable through ptrace or /proc/ /mem on a kernel at Yama ptrace_scope = 0. Real isolation between skills that do not trust each other needs the tier (a distinct uid for scripts, /proc mounted hidepid=2, or a non-dumpable server); until then, only put skills in one registration if you would give each of them every credential it holds.
• A non-zero exit is a normal, reported outcome — exit code, stdout and stderr all come back. It is never an exception that loses the output.
• `skill_run` asks before it runs anything. On a client that can show a confirmation prompt (Claude Code) the user is asked there, unless the server sets MCP_CONFIRM_ELICITATION=off. Otherwise the first call starts no process and returns status: "confirmation-required" with a preview of exactly what would run — the interpreter, the argv, the working directory, the timeout, and the names of the variables the script would be handed (field by field in the preview) — plus a confirmToken. Only a repeat call with the same arguments and that token runs the script, once. A token is bound to that exact run: changing the skill, script or argv is refused as DRAFT_CHANGED, and a used token as TOKEN_REUSED. See Confirmations.

The skill_run preview

The first call's preview.willRun is what the user approves, and it is the confirmToken's payload: the token is bound to it. Names only — never a value.

| envNames | every variable the script will be handed, sorted — not onl