Skip to main content
Glama
agentskills-mcp

agentskills-mcp

by janacibron

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: skills-mcp

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

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

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 .)

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:

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:

---
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:

>>> 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.

Available Tools

10 tools
get_skill_assetGet Skill AssetB

Read a specific asset file from a skill's assets/ directory.

Inputs: name (required), skill_id (required).

get_skill_bodyGet Skill BodyA

Return the full SKILL.md content for a skill (frontmatter + markdown body). Call this when you're ready to follow the skill's instructions. Cached by file mtime — repeated calls are cheap.

Inputs: skill_id (required). Returns: result

get_skill_metadataGet Skill MetadataA

Return lightweight metadata for a single skill (frontmatter only — name, version, description, tags). Cheaper than get_skill_body when you only need the catalog entry for a known skill_id.

Inputs: skill_id (required). Returns: result

get_skill_referenceGet Skill ReferenceB

Read a specific reference file from a skill's references/ directory.

Inputs: name (required), skill_id (required).

get_skill_scriptGet Skill ScriptA

Read a specific script file from a skill's scripts/ directory.

Inputs: name (required), skill_id (required).

list_skill_assetsList Skill AssetsB

List files in a skill's assets/ directory.

Inputs: skill_id (required). Returns: result

list_skill_referencesList Skill ReferencesB

List files in a skill's references/ directory.

Inputs: skill_id (required). Returns: result

list_skillsList SkillsA

Return the catalog of all registered skills. Use this first when you don't know which skill applies to the user's request. Each entry includes skill_id, name, version, description, and tags — enough to decide whether to call get_skill_body next.

Inputs: tag, include_deprecated. Returns: total, skills, server_version

list_skill_scriptsList Skill ScriptsB

List files in a skill's scripts/ directory.

Inputs: skill_id (required). Returns: result

search_skillsSearch SkillsA

Keyword search across skill_id, name, tags, and description. Returns ranked matches with relevance scores. Use this when the user's request names a specific intent and you want to find skills whose metadata matches — without scanning the whole catalog.

Inputs: query (required), limit, include_deprecated. Returns: hits, query, total, truncated

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers