agentskills-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agentskills-mcp list available skills"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 fileInstallation
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, ipythonThis 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 toolsRuntime dependencies
Package | Version constraint | Why |
|
| MCP server framework |
|
| Response schemas ( |
|
| Frontmatter parsing in |
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 testVia 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.jsonFrontmatter schema
Required fields:
Field | Type | Purpose |
|
| Human-readable name (not unique; |
|
| Semver-ish; used for cache invalidation |
|
| One-liner shown in |
Optional fields:
Field | Type | Default | Purpose |
|
|
| Categorical labels; indexed by |
|
|
| Attribution |
|
|
| SPDX identifier or custom |
|
|
| Semver constraint on the MCP server version |
|
|
| If true, hidden from |
|
|
|
|
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 |
| Return the full catalog. Call this first when you don't know which skill applies. |
| Keyword search across |
Access
Tool | Description |
| Frontmatter only — cheap. |
| Full SKILL.md content (frontmatter + markdown). Cached by file mtime. |
| List files in the skill's |
| Read a specific reference file. |
| List files in |
| Read a specific script file. |
| List files in |
| Read a specific asset file. |
Typical LLM flow
list_skills()— see what's availableIf unclear which fits,
search_skills(user_intent)— narrow downget_skill_body(chosen_skill_id)— load full instructionsFollow the skill's instructions, calling
get_skill_reference/script/assetas 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 |
|
| Human-readable catalog; one section per skill. |
|
| Machine-readable catalog; same fields as |
|
| 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 |
| 3.0 | Exact = 3.0, prefix = 1.5, substring = 0.5 |
| 2.0 | Exact = 2.0, substring = 0.5 |
| 2.0 | Exact tag match = 2.0 per tag |
| 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 callsprovider.stat()to get current mtimeIf the cache has an entry for
(skill_id, mtime), it's returned without re-reading the fileIf 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_idmust not contain/,\, or be./../empty/hiddenname(withinreferences/etc.) must be a single file segmentInvalid IDs return
None(no file access attempted)
Example:
>>> get_skill_body("../../etc/passwd")
NoneExtending
Adding a new skill
Create
./skills/<skill_id>/SKILL.mdwith required frontmatterOptionally add
references/,scripts/,assets/subdirectoriesRestart the server (or call
get_skill_bodyagain — 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 skillsStructured logging integration (replace default
printwarning 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 toolsget_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
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.
Maintenance
Related MCP Connectors
Find AI agent skills: public previews and source links. Read-only discovery; no account required.
Search and load AI agent skills. Free metadata; full content requires a Pro or Studio account.
Search your team's shared AI-skill library, get install commands, and save skills from your agent.
Search and fetch skills from your org's Skills and Agents catalog. Bearer token required.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and retrieve over 89K skills on-demand at runtime, eliminating the need to manually install skills upfront.136MIT
- AlicenseAqualityBmaintenanceEnables agents to discover, read, and use reusable skills stored in public GitHub repositories.417 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables any agent to search skill packs with bounded results, fetch one full validated skill on demand, and act without copying directories into prompts.MIT
- FlicenseNot gradedqualityCmaintenanceEnables searching and browsing a library of Agent Skills and prompts, then loading full SKILL.md instructions and supporting files for a chosen skill.-