SkillMCP

Local MCP server that serves project skills to AI coding agents (Cursor, Claude Code, Gemini CLI, Antigravity).

The host spawns skills-mcp serve over stdio (no HTTP). SkillMCP injects a short session ritual via MCP instructions and exposes tools to list and read SKILL.md files on demand.

Pairs well with LearnSkill (session friction) and claude-mem (long-term memory).

Requirements: Python ≥ 3.11. Standalone package — no monorepo or sibling tools required.

Install

cd SkillMCP

# Option A — uv (recommended)
uv sync
uv run skills-mcp --version

# Option B — pip
pip install -e .
skills-mcp --version

Related MCP server: mcp-canon

Quick start

cd /path/to/your-project
skills-mcp init .          # skillmcp.toml, .agents/skills/, register MCP with hosts
skills-mcp verify            # layout + registration check

Restart your agent host so it picks up the new MCP server entry.

Example project layout (see examples/my-project/):

your-project/
  skillmcp.toml
  .agents/
    skills/
      my-skill/
        SKILL.md

Configuration

skillmcp.toml

Lists skill folders in priority order. Later entries win on name collision.

skill_folders = [
    "/path/to/shared/skills",
    ".agents/skills",
]

Each skill_folders entry can be either:

skill_folders = [
    "/path/to/LearnSkill/learn",   # single skill folder
    ".agents/skills",              # project skill library
]

Skill library contents:

• Directory skills: foo/SKILL.md plus optional references/, scripts/, assets/

• Flat legacy files: foo.md (YAML frontmatter + body)

Single skill folder: point at the directory that contains SKILL.md (name in frontmatter need not match the folder name).

Frontmatter fields: name, description, optional triggers, metadata, license, compatibility.

Environment variables

Config discovery: walk up from cwd for skillmcp.toml, or use SKILLS_MCP_ROOT when set.

Skill sources (merge order)

Project rules (AGENT.md, AGENTS.md, Cursor rules/hooks) are not injected by SkillMCP — configure those in your agent host.

MCP host registration

skills-mcp init and skills-mcp mcp register write a server entry to:

Example entry (Cursor / Claude):

{
  "mcpServers": {
    "skills-mcp": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "skills_mcp", "serve", "--root", "/path/to/your-project"],
      "env": {
        "SKILLS_MCP_ROOT": "/path/to/your-project",
        "SKILLS_MCP_LIBRARY": "/path/to/shared/skills"
      }
    }
  }
}

On Windows, use the full path to python.exe in command if skills-mcp is not on PATH. Add -u before -m in args if stdio buffering causes handshake timeouts.

Optional shared library: set SKILLS_MCP_LIBRARY to a skills folder (e.g. SkillMCP/examples/my-project/.agents/skills).

Manual config (no init): add the same mcpServers block yourself using the Python where skills-mcp is installed, then restart the host.

MCP tools

list_skills response

Returns metadata only (not full bodies):

[
  {
    "name": "role-plan",
    "description": "Produce an execution-ready plan before writing code…",
    "path": ".agents/skills/role-plan/SKILL.md",
    "format": "directory",
    "references_dir": "references",
    "scripts_dir": "",
    "assets_dir": ""
  }
]

Pass project_path when working in a repo other than SKILLS_MCP_ROOT to merge that project's skills (local names win on collision).

Session instructions

Every session gets a fixed ritual: call list_skills, then read_skill(name) before implementing patterns a skill covers. Large skill bodies stay out of context until explicitly loaded.

CLI

Debug serve manually:

skills-mcp serve --root /path/to/your-project

Troubleshooting

Design notes

• Stdio, not HTTP — local-only; every MCP host supports it

• Instructions + tools — small ritual always on; skill bodies loaded on demand

• Last-wins merge — shared library + early folders; project skills in later folders override by name

• No daemon — host spawns the server per session; skill index rebuilt each spawn

Related projects