Hierarchical Skills For AI - A Skills Serving Hierarchical MCP Server

A hierarchical MCP (Model Context Protocol) server for managing skill definitions. Skills are stored as folders containing SKILL.md with YAML frontmatter, organized in a browsable tree structure with full-text search and a web UI.

When to Use / When Not to Use

Use this when

• You have many skills (100+) and including all their frontmatter in the AI's context window would waste tokens

• You want structured, hierarchical organization of skills by domain (coding, security, writing...)

• You want search + browse so the AI can find the right skill without knowing the exact path

• You want usage tracking so popular skills naturally rank higher over time

• You want a web UI for humans to browse the same skill tree

Don't use this when

• You have few skills (< 15) — just install them as per your agents' instructions, no server needed

• Your skills are ephemeral or one-shot — the server setup overhead isn't worth it

• You need real-time editing or CRUD from the web UI — it's read-only by design

• You need multi-user auth or permissions — not built for that

• You need relational queries or a database backend — this is filesystem + in-memory index

Related MCP server: agentskill-mcp

Architecture

  Agent (MCP client)             Human (browser)
       ↓                              ↓
Skills MCP Server ← python mcp_server.py --port 8080
       │                              │
       ├── MCP (stdio)                ├── HTTP (web UI)
       │   browse(path, depth=1)      │   GET /api/browse?path=&depth=
       │   read(path)                 │   GET /api/search?q=
       │   search(query)              │   GET /api/read?path=
       │   info(path)                 │   GET /api/info?path=
       │   use(path)                  │
       │   steps(path)                │
       │   reload()                   │
       │                              │
       └──────────────────────────────┘
                      ↓
          ┌───────────┼───────────┐
          ↓           ↓           ↓
     File system    Index     Usage stats
     (SKILL.md)   (tags,     (uses count,
                   aliases,   last_used)
                   body,
                   relations)

Quick Start

# Install
python3 -m venv venv
source venv/bin/activate
pip install -e .

# Run with sample skills (activate venv first)
python mcp_server.py --port 8080

# Open web UI
open http://localhost:8080

CLI Arguments

MCP Tools

Skill File Format

Each skill lives in its own folder containing a SKILL.md file with YAML frontmatter delimited by ---.

Folder structure rules

skills/
  coding/                      # group folder (has subfolders, no SKILL.md)
    python/
      fastapi/                 # skill folder → contains SKILL.md
        SKILL.md
      pytest/
        SKILL.md
    rust/
      tokio/
        SKILL.md

• A folder is a skill if it contains SKILL.md

• A folder is a group if it has subfolders but no SKILL.md

• A folder can be dual (both group + skill) — has SKILL.md AND subfolders

• Folders beyond --max-depth are silently ignored

• Empty folders (no SKILL.md, no subfolders) are silently ignored

• Use lowercase with hyphens for folder names: web-scraping

• All path lookups are case-insensitive — "Coding/Python" and "coding/python" resolve to the same node

• Case collisions are rejected at startup: having both Coding/ and coding/ folders will abort the server — use consistent casing

Frontmatter fields

Example

---
name: fastapi
tags: [python, api, web]
aliases: [fast api, fastapi framework]
description: Python web framework for building APIs
depends_on: [python/basics]
related: [flask, starlette]
followed_by: [sqlalchemy, pytest]
uses: 0
last_used: null
steps: [setup/project-scaffold, coding/python/fastapi/routing]
---

After the closing ---, write standard Markdown body content. The server never modifies the body — only uses and last_used in the frontmatter are updated automatically.

Validation rules

On startup and reload() the server validates every skill:

• SKILL.md must exist and have valid YAML frontmatter

• name field is required and must be unique across the entire tree

• Duplicate names cause an abort with per-skill error logging

• Folders with case-colliding paths (e.g. Coding/ and coding/) cause an abort — use consistent casing

• Folders beyond --max-depth are silently ignored

Hierarchy guidelines

• Keep --max-depth between 3 and 5 levels

• Aim for 5–15 children per group node; split into sub-groups if exceeding 20

• Use dual nodes (folder with SKILL.md + subfolders) when a group has general content applying to all children

• Prefer 3–8 tags per skill, lowercase, singular form

Project Structure

skills-mcp-server/
├── mcp_server.py           # Root-level entry point
├── pyproject.toml          # Project configuration
├── src/
│   ├── __init__.py         # Package init
│   ├── __main__.py         # Entry point
│   ├── main.py             # CLI + server orchestration
│   ├── models.py           # Data models
│   ├── frontmatter.py      # YAML frontmatter parser
│   ├── discovery.py        # Folder walker
│   ├── tree.py             # In-memory skill tree
│   ├── index.py            # Search index
│   ├── mcp_server.py       # MCP tool definitions
│   ├── http_server.py      # HTTP server for web UI
│   └── static/
│       └── index.html      # Web UI (vanilla HTML/CSS/JS)
├── tests/
│   ├── test_discovery.py   # Tests for discovery
│   ├── test_frontmatter.py # Tests for YAML parsing
│   └── test_tools.py       # Tests for tree tools & search
├── sample_skills/          # Demo skills
├── HANDOFF.md              # Session handoff notes
├── AGENTS.md               # Agent conventions
└── IMPLEMENTATION_PLAN.md  # Full implementation plan

Design Principles

• Hierarchy for humans, search for models — tree browsing and full-text search coexist

• Filesystem as source of truth — no database needed

• Minimal dependencies — only mcp and pyyaml

• Read-only web UI — no editing, no auth, no build step

• Self-improving index — usage tracking boosts popular/recent skills in search results

Tests

python -m pytest tests/ -v