agentskills-mcp
# 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](https://gofastmcp.com/) 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`](./mcp-server-architecture.png) for the full visual, or [`mcp-architecture.mmd`](./mcp-architecture.mmd) for the editable Mermaid source (renders natively on GitHub).
---
## 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)
```bash
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
```bash
pip install -r requirements.txt # runtime deps only
pip install -r requirements-dev.txt # add dev/test tools
```
### Runtime dependencies
| Package | Version constraint | Why |
|---------|-------------------|-----|
| `fastmcp` | `>=2.14,<3.0` | MCP server framework |
| `pydantic` | `>=2.10,<3.0` | Response schemas (`SkillSummary`, `ListSkillsResult`, etc.) |
| `pyyaml` | `>=6.0,<7.0` | Frontmatter parsing in `skill_provider.parse_frontmatter()` |
Python 3.10+ required (uses `slots=True` dataclasses and `from __future__ import annotations`).
---
## Quick start
### Via the `agentskills-mcp` CLI (after `pip install .`)
```bash
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
```python
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:
```python
mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)
```
### Smoke tests
```bash
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:
| Field | Type | Purpose |
|-------|------|---------|
| `name` | `str` | Human-readable name (not unique; `skill_id` is the directory name) |
| `version` | `str` | Semver-ish; used for cache invalidation |
| `description` | `str` | One-liner shown in `list_skills()` output |
Optional fields:
| Field | Type | Default | Purpose |
|-------|------|---------|---------|
| `tags` | `list[str]` | `[]` | Categorical labels; indexed by `search_skills()` |
| `author` | `str` | `""` | Attribution |
| `license` | `str` | `""` | SPDX identifier or custom |
| `min_mcp_version` | `str` | `""` | Semver constraint on the MCP server version |
| `deprecated` | `bool` | `false` | If true, hidden from `list_skills()` by default |
| `replaces` | `str` | `""` | `skill_id` this skill supersedes |
Example `SKILL.md`:
```markdown
---
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)
| Tool | Description |
|------|-------------|
| `list_skills(include_deprecated=False, tag=None)` | Return the full catalog. Call this first when you don't know which skill applies. |
| `search_skills(query, include_deprecated=False, limit=10)` | Keyword search across `skill_id`, `name`, `tags`, `description`. Returns ranked matches with relevance scores. |
### Access
| Tool | Description |
|------|-------------|
| `get_skill_metadata(skill_id)` | Frontmatter only — cheap. |
| `get_skill_body(skill_id)` | Full SKILL.md content (frontmatter + markdown). Cached by file mtime. |
| `list_skill_references(skill_id)` | List files in the skill's `references/` directory. |
| `get_skill_reference(skill_id, name)` | Read a specific reference file. |
| `list_skill_scripts(skill_id)` | List files in `scripts/`. |
| `get_skill_script(skill_id, name)` | Read a specific script file. |
| `list_skill_assets(skill_id)` | List files in `assets/`. |
| `get_skill_asset(skill_id, name)` | Read a specific asset file. |
### 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).
| URI | MIME type | Description |
|-----|-----------|-------------|
| `skills://catalog/markdown` | `text/markdown` | Human-readable catalog; one section per skill. |
| `skills://catalog/xml` | `application/xml` | Machine-readable catalog; same fields as `list_skills()`. |
| `skills://tools-usage-instructions` | `text/markdown` | Condensed guidance for the LLM on when to call which tool. |
**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):
| Field | Weight | Match strategy |
|-------|--------|----------------|
| `skill_id` | 3.0 | Exact = 3.0, prefix = 1.5, substring = 0.5 |
| `name` | 2.0 | Exact = 2.0, substring = 0.5 |
| `tags` | 2.0 | Exact tag match = 2.0 per tag |
| `description` | 1.0 | Word-level substring = 0.2 per word |
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:
```python
>>> 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`](./discovery_tools_spec.md).
---
## License
TBD — set in your own project's `LICENSE` file.
TDQS
Scored across 10 tools
Most tools are clearly separated by resource (skill body, references, scripts, assets) and by action (list vs get vs search). The only soft overlap is between list_skills, search_skills, and get_skill_metadata, which all return catalog-level metadata, but the descriptions give explicit guidance on when to use each.
Every tool follows a strict verb_noun snake_case pattern (list_/get_/search_ + resource). The per-directory resource names (skill_references, skill_scripts, skill_assets) are parallel and predictable, so an agent can infer unlisted tools.
Ten tools is well within the ideal range and each earns its place: three discovery tools, one body reader, and a symmetric list/get pair for each of the three sub-directories. No redundant or filler tools.
The read/lifecycle surface for consuming a skill is fully covered: discover, inspect metadata, read body, and traverse references, scripts, and assets. Gaps are minor and likely intentional — there is no way to create, update, or delete skills, and no tool to execute a script rather than just read it.