agentskills-modelcontextprotocol

An MCP (Model Context Protocol) server that exposes a catalog of "skills" to LLM agents. Each skill is a directory containing a SKILL.md (YAML frontmatter + Markdown body) plus optional references/, scripts/, and assets/ subdirectories. The server lets an LLM discover which skills exist, fetch their contents on demand, and read their supporting files.

Built on FastMCP 2.x. Designed for the Claude Desktop, VS Code, and custom MCP client ecosystem.

Architecture

MCP Client (LLM Agent)
    │  MCP Protocol (stdio / streamable-http)
    ▼
create_mcp_server()  ← Factory entry
    │  registers tools · mounts resources · wires SkillRegistry
    ▼
┌─────────────────────────────────────────────┐
│  Server Surface                              │
│  • 10 Tools   (LLM-invoked, on-demand)       │
│  • 3 Resources (URI-addressable context)     │
└─────────────────────────────────────────────┘
    │  delegates lookups
    ▼
SkillRegistry  ← validates frontmatter · LRU cache by (skill_id, mtime)
    │  resolves via abstract interface
    ▼
SkillProvider (interface)  ← list() · read() · stat() · list_subdir() · read_subfile()
    │
    ├─ LocalFileSystemSkillProvider  (reads ./skills)
    └─ GitSkillProvider              (future — pulls from remote git repo)
    │
    ▼
Filesystem (./skills/<skill_id>/)

See mcp-server-architecture.png for the full visual, or mcp-architecture.mmd for the editable Mermaid source (renders natively on GitHub).

Related MCP server: capalith

Project structure

.
├── mcp_server.py              # FastMCP wiring: create_mcp_server(), all 10 tools, 3 resources, CLI entry point
├── skill_provider.py          # SkillProvider ABC + LocalFileSystemSkillProvider + GitSkillProvider stub
├── discovery_tools_spec.md    # Spec for list_skills() / search_skills() + frontmatter schema
├── pyproject.toml             # Package metadata, deps, entry point, tooling config (ruff/mypy/pytest)
├── requirements.txt           # Runtime deps (pip install -r)
├── requirements-dev.txt       # Dev/test deps (pytest, ruff, mypy, ipython)
├── mcp-server-architecture.png  # Polished architecture diagram (Playwright + CSS)
├── mcp-architecture.mmd       # Same diagram as Mermaid source (for README embedding)
├── mcp-architecture.mermaid.png  # Mermaid rendering (tall/narrow — prefer the .png above)
└── README.md                  # This file

Installation

Option A — Install from source (recommended)

cd /path/to/agentskills-modelcontextprotocol
pip install -e .            # editable install — pick up code changes automatically
pip install -e '.[dev]'     # also installs pytest, ruff, mypy, ipython

This registers the agentskills-mcp command-line entry point (see Usage below).

Option B — Plain requirements.txt

pip install -r requirements.txt          # runtime deps only
pip install -r requirements-dev.txt       # add dev/test tools

Runtime dependencies

Python 3.10+ required (uses slots=True dataclasses and from __future__ import annotations).

Quick start

Via the agentskills-mcp CLI (after pip install .)

agentskills-mcp                                       # defaults: ./skills, stdio transport
agentskills-mcp --skills-root /opt/skills
agentskills-mcp --transport streamable-http --port 8080
agentskills-mcp --smoke-test                          # run in-process smoke test

Via the Python API

from mcp_server import create_mcp_server

mcp = create_mcp_server(skills_root="./skills")
mcp.run()  # stdio transport (default — for Claude Desktop, VS Code)

For HTTP transport:

mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

Smoke tests

agentskills-mcp --smoke-test       # via CLI entry point
python mcp_server.py                # directly via __main__
python skill_provider.py            # provider-level test (validation, path traversal, etc.)

Skill directory convention

Each skill is a subdirectory of ./skills/ (or wherever skills_root points):

incident-response/
├── SKILL.md          ← YAML frontmatter + Markdown body
├── references/       ← served by get_skill_reference()
│   └── checklist.md
├── scripts/          ← served by get_skill_script()
│   └── run.py
└── assets/           ← served by get_skill_asset()
    └── template.json

Frontmatter schema

Required fields:

Optional fields:

Example SKILL.md:

---
name: Incident Response
version: 1.2.0
description: Runbooks for on-call incident handling
tags: [ops, sre, on-call]
author: SRE Team
license: Apache-2.0
---

# Incident Response

Follow the runbook for your incident severity...

Skills with missing/invalid frontmatter are skipped at registration time (logged via the on_warning callback, not raised) — one bad skill won't break the catalog.

Tools (10)

Discovery (NEW in this refinement)

Access

Typical LLM flow

1. list_skills() — see what's available

2. If unclear which fits, search_skills(user_intent) — narrow down

3. get_skill_body(chosen_skill_id) — load full instructions

4. Follow the skill's instructions, calling get_skill_reference/script/asset as needed

Resources (3)

Resources are URI-addressable context that the client decides when to fetch (unlike tools, which the LLM invokes).

Why both tools and resources? Different MCP clients behave differently. Claude Desktop exposes resources as attachable context; other clients may auto-prefetch. Tools work everywhere. Providing both ensures the discovery layer is reachable regardless of client behavior.

Search scoring algorithm

search_skills(query) uses multi-field scoring (no embeddings required for v1):

Query is tokenized on whitespace; each token scored independently and summed. Case-insensitive. Results with score 0 are excluded. Ties broken alphabetically by skill_id.

Caching

SkillRegistry maintains an LRU cache (max 256 entries) keyed by (skill_id, mtime):

• get_skill_body(skill_id) first calls provider.stat() to get current mtime

• If the cache has an entry for (skill_id, mtime), it's returned without re-reading the file

• If the file changed on disk (different mtime), the cache entry is invalidated and the file is re-read

This means repeated calls to get_skill_body are essentially free, and editing a SKILL.md on disk is reflected on the next call without server restart.

Security

Path traversal is rejected at the provider layer:

• skill_id must not contain /, \, or be ./../empty/hidden

• name (within references/ etc.) must be a single file segment

• Invalid IDs return None (no file access attempted)

Example:

>>> get_skill_body("../../etc/passwd")
None

Extending

Adding a new skill

1. Create ./skills/<skill_id>/SKILL.md with required frontmatter

2. Optionally add references/, scripts/, assets/ subdirectories

3. Restart the server (or call get_skill_body again — the cache invalidates on mtime change)

Adding a new provider

Implement the SkillProvider ABC (5 methods: list, stat, read, list_subdir, read_subfile), then pass it to create_mcp_server(provider=YourProvider()). The registry and all 10 tools work unchanged.

The GitSkillProvider stub in skill_provider.py shows the implementation plan for a future git-backed provider (shallow clones, atomic checkout swap, per-skill version pinning via git refs).

Roadmap

• GitSkillProvider — pull skills from a remote git repo (shared team catalogs, version pinning)

• search_skills_semantic() — embeddings-based semantic search (companion to the keyword tool)

• Pagination for list_skills() once catalogs exceed ~500 skills

• Structured logging integration (replace default print warning callback)

• Integration tests for cache invalidation (modify SKILL.md between calls)

• CLI tool for skill scaffolding (new-skill <name> creates the directory + frontmatter template)

Open questions are tracked in section 7 of discovery_tools_spec.md.

License

TBD — set in your own project's LICENSE file.