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

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

Argument	Required	Default	Description
--repo	No	sample_skills	Path to root folder containing grouped skills
--max-depth	No	4	Maximum folder depth to walk
--port	No	8080	Port for web UI
--host	No	localhost	Host for web UI

MCP Tools

Tool	Input	Output	Description
browse(path, depth=1)	"", "coding", "coding/python"	Child groups + skills (nested if depth>1)	Navigate the skill hierarchy
read(path)	"coding/python/fastapi"	Full SKILL.md body	Load skill content
search(query)	"fastapi", "web"	Ranked paths	Search by name, tags, aliases, description, path segments
info(path)	"coding/python/fastapi"	YAML metadata (no body)	Lightweight skill inspection
use(path)	"coding/python/fastapi"	Updated metadata	Track skill usage (boosts search ranking)
steps(path)	"coding/python/fastapi"	Ordered step list	Get workflow sub-skills
reload()	—	Status	Re-scan repo, re-validate, re-index

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

Field	Required	Type	Description
name	Yes	string	Unique identifier across the entire tree. Does not need to match folder name.
tags	No	list	Keywords for search: [python, api, web]
aliases	No	list	Alternative names an AI might search by: [fast api, fastapi framework]
description	No	string	One or two sentences explaining the skill. Indexed for search.
depends_on	No	list of paths	Prerequisites the AI should know first: [python/basics]
related	No	list of paths	Conceptually similar skills: [flask, starlette]
followed_by	No	list of paths	Natural next skills after mastering this one
steps	No	list of paths	Ordered sub-skill paths for multi-step workflows
uses	Auto	integer	Usage counter — auto-incremented by use() tool
last_used	Auto	string or null	ISO timestamp — auto-set by use() tool

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