skills_mcp_server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
uv sync

# Run the server (development)
uv run uvicorn main:app --reload

# Run all tests
uv run pytest -v tests/

# Run a single test file
uv run pytest -v tests/test_routes.py

# Run with coverage
uv run pytest --cov=. tests/

# Docker
docker-compose up --build

Architecture

This is a dual-interface skill management server:

1. REST API (control plane) — routes.py handles skill lifecycle (install, delete, list). Requires X-API-Key header.
2. MCP Server (provider plane) — mcp_server.py exposes skills as MCP tools via StreamableHTTP at /mcp. Also requires X-API-Key.

Both interfaces share a single SkillManager instance (from services.py), wired up at startup via FastAPI's lifespan in main.py.

Key Files

• main.py — FastAPI app, lifespan, MCPAuthMiddleware, mounts FastMCP at /mcp
• routes.py — REST endpoints + ENFORCEMENT_PROMPT (injected into agent system prompts)
• services.py — SkillManager: install/delete/reload skills, GitHub URL parsing, venv setup via uv
• mcp_server.py — FastMCP with 4 tools: get_available_skills, get_skill_instructions, get_skill_reference, get_skill_script
• models.py — Pydantic schemas for all request/response types
• s3_skills.py — S3Skills loader: syncs S3 bucket → local cache → delegates to Agno's LocalSkills

Skill Structure

Each skill is a folder in SKILLS_DIR:

my_skill/
├── SKILL.md              # Required: YAML frontmatter (name, description) + instructions body
├── scripts/              # Optional: Python scripts (can be executed if ALLOW_RUN_SCRIPTS=true)
│   ├── run.py
│   └── requirements.txt  # Triggers isolated venv creation via uv
└── references/           # Optional: reference documents

Skills are loaded by Agno's LocalSkills or S3Skills. Installing/deleting a skill calls manager.reload() to refresh the in-memory registry without restarting the server.