Agent Skills MCP Server

A Model Context Protocol server that exposes a catalog of Markdown-based agent skills — modeled after Anthropic's native Agent Skills format. Skills are guides, not executable tools.

The server discovers SKILL.md files under skills/, parses their YAML frontmatter, and serves them to MCP clients via three generic tools.

---

What Is a Skill Here?

A skill is a directory of Markdown files. The entry is SKILL.md, which contains YAML frontmatter (name, description) and a Markdown body. Supporting files live in reference/, examples/, or anywhere else relative to the skill root.

This mirrors the Anthropic Agent Skills format: progressive disclosure of metadata → instructions → resources.

skills/
└── ui-ux-design/
    ├── SKILL.md
    ├── reference/
    │   ├── foundations.md
    │   ├── interaction.md
    │   ├── accessibility.md
    │   └── patterns.md
    └── examples/
        ├── buttons.md
        ├── forms.md
        └── error-states.md

See CREATING_SKILLS.md for the full authoring guide.

---

MCP Tools

The server exposes exactly three tools, regardless of how many skills exist:

Tool	Purpose
list_skills	Returns name + description for every skill in the catalog. Cheap, always-available index.
get_skill(name)	Returns the SKILL.md body of the named skill plus a manifest of supporting files.
read_skill_file(skill, path)	Returns the contents of a supporting file (e.g. reference/foundations.md).

This 3-tool surface is intentional. Adding a new skill means dropping in a folder of Markdown — no code, no tool registration, no rebuild beyond restarting the server.

---

Quick Start

npm install
npm run build
npm start

Endpoints:

• MCP: POST http://localhost:3000/mcp
• Health: GET http://localhost:3000/health
• Skills index (HTTP, for inspection): GET http://localhost:3000/skills

---

Project Structure

agent-skills-mcp/
├── skills/                       ← skill content (Markdown only)
│   └── ui-ux-design/
│       ├── SKILL.md
│       ├── reference/*.md
│       └── examples/*.md
├── src/
│   ├── core/
│   │   ├── server.ts             ← MCP server + 3 tools
│   │   └── skill-catalog.ts      ← filesystem catalog + frontmatter parser
│   ├── types/
│   │   └── skill.types.ts        ← descriptor types
│   ├── utils/
│   │   └── logger.ts
│   └── index.ts                  ← entry point
├── CREATING_SKILLS.md            ← skill authoring guide
└── package.json

There is no BaseSkill, no per-skill TypeScript, no Zod schemas inside skills. Skills are content; the server is plumbing.

---

Environment Variables

Variable	Description	Default
PORT	Server port	3000
HOST	Server host	127.0.0.1 (local) / 0.0.0.0 (production)
LOG_LEVEL	DEBUG / INFO / WARN / ERROR	INFO
NODE_ENV	local / dev / test / production	local
SKILLS_PATH	Absolute path to the skills directory	<project_root>/skills

---

Adding a New Skill

1. Create skills/<your-skill-name>/SKILL.md
2. Add frontmatter (name, description) and the guide body
3. Add optional reference/ and examples/ files alongside
4. Restart the server (npm run build && npm start)

That is the whole flow. See CREATING_SKILLS.md for conventions, frontmatter rules, and the structural template.

---

Development

npm run typecheck    # Type check without emitting
npm run build        # Compile to dist/
npm run dev          # tsx watch on src/
npm start            # Run compiled server

---

Why Markdown Skills via MCP?

Native Anthropic Skills are filesystem-based and discovered locally by Claude Code, the API, or claude.ai. This server lets you publish a curated catalog of skills over MCP, so multiple agents (across machines, environments, or organizations) can pull from a single canonical source — without each having to install plugins or zip bundles.

The skills themselves remain plain Markdown. That is the point.

---

License

MIT