skillshelf

An MCP server that makes a library of agent skills available by name without loading any of them into an agent's context. Say "use the tdd skill" and the agent calls load_skill("tdd"); until then the library costs only the fixed tool descriptions (about 2 KB), however many skills it holds.

Sources are Git repositories pinned to a full commit SHA. Nothing follows a branch at runtime.

Use

npm install && npm run build
node dist/cli.js add https://github.com/mattpocock/skills   # resolves HEAD to a commit and pins it
node dist/cli.js list                                        # mattpocock/tdd, mattpocock/grill-me, …
node dist/cli.js serve                                       # MCP over stdio

MCP client configuration (Claude Code, Codex, Cursor or any MCP client):

{ "mcpServers": { "skills": { "command": "node", "args": ["/path/to/skillshelf/dist/cli.js", "serve"] } } }

add <git-url> [--name <source>] [--ref <branch|tag|sha>] [--path <folder>] adds or re-pins a source; run it again with the same name to update. The config lives at ~/.config/skillshelf/skillshelf.json (--config or SKILLSHELF_CONFIG), checkouts at ~/.cache/skillshelf (--cache or SKILLSHELF_CACHE). serve fetches any missing checkout before it starts.

{
  "sources": [
    { "name": "mattpocock", "repo": "https://github.com/mattpocock/skills", "commit": "4ae2317ddb22b046e26455e4f9c9b3aaaf62212d" }
  ]
}

Related MCP server: ThirdBrain skills-mcp

Tools

Tool descriptions and server instructions never contain skill names or descriptions.

Names

Every skill is addressed as <source>/<name>, so two repositories can both have a tdd. If one source has two skills with the same name, both are kept and their folder is added: mattpocock/engineering/code-review. A bare name that matches several skills is refused with the candidates rather than resolved silently.

MCP Skills Extension

The server also implements SEP-2640: it declares io.modelcontextprotocol/skills, answers skills/list and skills/get with frontmatter, digests and sizes, and serves every file as a skill://<source>/<name>/<file> resource. Hosts that support the extension can load skills natively; the tools above work everywhere else. resources/directory/read is not implemented.

Safety

• Commits are fetched by SHA and verified after checkout. Git runs without user or system configuration, prompts or LFS downloads.

• Symlinks are checked out as plain files holding the link text, and are never listed if present in a local tree. Only files listed for a skill can be read.

• Every read is checked against the SHA-256 digest recorded at startup.

• Scripts are returned as text. Nothing in a skill is executed.

• Skill content is third-party text handed to an agent as instructions. Pin repositories you have read.

Skills larger than 512 files or 16 MiB, or without a valid name and description, are skipped and reported on stderr. Frontmatter that strict YAML rejects only because of an unquoted colon is read as plain key: value lines.

Develop

npm run check          # typecheck and tests (Node 22.18+ runs the TypeScript directly)
npm run smoke -- tdd mocking.md   # build, start over stdio with your config, load a skill

License

MIT