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

---

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",
]

Case	Result
File missing	Defaults to [".agents/skills"]
skill_folders = [] or null	Same default

Each skill_folders entry can be either:

Path kind	Detection	Example
Skill library	No SKILL.md at the folder root — scan subfolders and flat .md files	.agents/skills/ → project-starter/SKILL.md
Single skill	SKILL.md at the folder root — load exactly that skill	LearnSkill/learn/ → one learn skill

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

Variable	Meaning
SKILLS_MCP_ROOT	Project directory containing skillmcp.toml (set by host MCP config)
SKILLS_MCP_LIBRARY	Optional shared skills folder (lowest priority; prepended before skill_folders)
SKILLS_MCP_RULES_INSTRUCTIONS_MAX_CHARS	Cap MCP instruction block size (0 = no cap)

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

Skill sources (merge order)

Priority	Source
Lowest	SKILLS_MCP_LIBRARY (optional env)
↑	Earlier entries in skill_folders
Highest	Last entry in skill_folders

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:

Host	Config file
Claude Code	<project>/.mcp.json
Cursor	<project>/.cursor/mcp.json
Antigravity	<project>/.agents/mcp_config.json
Gemini CLI	~/.gemini/settings.json (global)

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

Tool	Description
verify_setup	JSON health snapshot: paths, skill counts, registration status
list_skills	JSON catalog (project_path optional — merge another repo's skills)
read_skill	Full SKILL.md markdown by name
list_skill_files	Files under a skill's references / scripts / assets
read_skill_file	Read one UTF-8 file from a skill subdirectory
learn_paths	JSON: .learn output paths from skillmcp.toml [learn]
learn_run_script	Run a learn skill script (detectors, collect-cursor)
learn_stamp	Ensure .learn/inbox exists and update lean.stamp

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

Command	Description
init [path]	Create .agents/skills/, skillmcp.toml, register MCP
serve [--root PATH]	Run MCP server on stdio (host spawns this)
verify	Verify layout and MCP registration
mcp register	Re-register with all supported hosts

Debug serve manually:

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

---

Troubleshooting

Problem	Fix
Stale paths after moving project	Run skills-mcp mcp register from the new location
Missing skills	Run skills-mcp verify or MCP verify_setup — check project_root, skill_dirs, skills_count
Server not starting	Host MCP config must use the same Python where skills-mcp is installed
Wrong skills from another repo	Workspace MCP config must set SKILLS_MCP_ROOT to this project
Windows handshake timeout	Add -u before -m in python args

---

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

Project	Role
LearnSkill	Session friction analysis
claude-mem	Long-term memory across sessions