┌─────────────┐     "list/run tools"      ┌────────────────────┐
   │  MCP client │ ────────────────────────► │                    │
   │ Claude Code │                           │   MCP Skill        │
   │ Claude Dsk. │ ◄──────────────────────── │   Registry server  │
   │  VS Code    │      tool results         │                    │
   └─────────────┘                           │   discovers every  │
   ┌─────────────┐     POST /api/v1/...      │   skills/<name>/   │
   │ REST caller │ ◄────────────────────────►│   folder           │
   └─────────────┘                           └─────────┬──────────┘
                                                       │ runs in
                                                       ▼ subprocess
                                          skills/text-statistics/
                                          skills/your-skill/ ...

        MCP clients                         REST clients
   (Claude Code / Desktop,            (curl, scripts, the
    GitHub Copilot, VS Code)            Next.js dashboard)
            │                                   │
            ▼  Streamable HTTP                  ▼  /api/v1
   ┌──────────────────────────────────────────────────────┐
   │                FastAPI application                    │
   │  api → mcp → services → repositories → db → models    │
   │  discovery · validation · sandboxed execution · audit │
   └──────────────────────────────────────────────────────┘
            │ discovers + runs                  │ persists
            ▼                                   ▼
   skills/ + agents/  (self-contained folders)   SQLite (history, audit)

git clone https://github.com/sarveshtalele/mcp-skills-registry.git
cd mcp-skills-registry

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

skill-registry          # serves on http://localhost:7860

curl http://localhost:7860/health
# {"status":"ok","version":"0.2.0","skills_loaded":1}

docker build -t mcp-skill-registry .
docker run -p 7860:7860 -v "$(pwd)/data:/data" mcp-skill-registry

# Via MCP client
"Reverse engineer https://github.com/nopSolutions/nopCommerce"

# Via REST API
curl -X POST http://localhost:7860/api/v1/skills/legacy-discovery/execute \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"repo_url": "https://github.com/nopSolutions/nopCommerce"}}'

claude mcp add --transport http skill-registry \
  https://sarveshtalele-mcp-skills-registry.hf.space/mcp

/mcp          # lists connected servers and their tools

{
  "servers": {
    "skill-registry": {
      "type": "http",
      "url": "https://sarveshtalele-mcp-skills-registry.hf.space/mcp"
    }
  }
}

# 1. initialize — returns an Mcp-Session-Id header
curl -i -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 2. list tools
curl -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call a tool
curl -X POST http://localhost:7860/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"text-statistics","arguments":{"text":"Hello world."}}}'

# Example: run a skill
curl -X POST http://localhost:7860/api/v1/skills/text-statistics/execute \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"text": "The quick brown fox jumps over the lazy dog."}}'

┌──────────────────────────────────────────────────────────────────────┐
│                     FastAPI application  (port 7860)                │
│                                                                     │
│   api/        Routers:  /  ·  /health  ·  /mcp  ·  /api/v1/skills  │  ← transport
│     │                                                               │
│   mcp/        Streamable HTTP transport · JSON-RPC 2.0 · sessions   │  ← MCP protocol
│     │                                                               │
│   services/   SkillRegistry (facade)                                │  ← application
│     │           ├─ loader      parse & validate SKILL.md            │     logic
│     │           ├─ validator   check inputs against the manifest    │
│     │           ├─ executor    run skill in a sandboxed subprocess  │
│     │           ├─ search      keyword / optional semantic ranking  │
│     │           ├─ installer   safe ZIP upload (zip-slip/bomb guard)│
│     │           ├─ publisher   auto-commit to GitHub on upload      │
│     │           └─ audit       append-only event log                │
│     │                                                               │
│   repositories/  execution history · audit trail                    │  ← persistence
│     │                                                               │
│   db/  models/  config/  container/  main                           │  ← storage, types,
│         SQLite + schema.sql · pydantic models · settings · wiring   │     wiring
└───────────────────────────────────┬──────────────────────────────────┘
                                    │ discovers & executes
                                    ▼
                       skills/   self-contained skill folders
                         └─ <name>/  SKILL.md · scripts/ · references/ · assets/

client → tools/call (MCP)  or  POST /api/v1/skills/{name}/execute (REST)
   │
   ├─ 1. look up the skill in the in-memory catalogue        (404 if unknown)
   ├─ 2. validate inputs against SKILL.md                    (types, required, enums)
   ├─ 3. spawn subprocess: python _runner.py <skill> run     (isolated, timed)
   │         inputs → JSON via stdin   ·   output → JSON via stdout
   ├─ 4. enforce timeout + output-size cap                   (kill child on overrun)
   ├─ 5. record execution + audit entry                      (SQLite)
   └─ 6. return { status, output | error, duration_ms }

skill-name/
├── SKILL.md          # Required: YAML frontmatter (manifest) + instructions
├── scripts/          # Optional: code — entrypoint exposes run(inputs) -> dict
├── references/       # Optional: supporting docs
├── assets/           # Optional: templates, resources, extra requirements.txt
└── ...               # Any additional files

python scripts/new_skill.py my-skill

---
name: my-skill
version: 1.0.0
description: What it does and the phrases that should trigger it.
execution:
  type: python-script
  entrypoint: scripts/main.py:run
  timeout_seconds: 30
inputs:
  - name: text
    type: string
    required: true
    description: Text to process.
outputs:
  - name: result
    type: string
    description: Processed text.
---

# My Skill
Instructions for the agent.

def run(inputs: dict) -> dict:
    return {"result": inputs["text"].upper()}

# Option A: reload the running server
curl -X POST http://localhost:7860/api/v1/admin/reload

# Option B: upload a packaged skill (no restart needed)
zip -r my-skill.zip my-skill/
curl -X POST http://localhost:7860/api/v1/skills/upload -F 'file=@my-skill.zip'

GitHub (source of truth)  ──push main──►  HF Space (Docker build)  ──►  live MCP server
        │                                         │
   CI: lint + test                        Dockerfile → uvicorn :7860

docker build -t mcp-skill-registry .
docker run -p 7860:7860 -v "$(pwd)/data:/data" mcp-skill-registry

pip install huggingface_hub
huggingface-cli login
huggingface-cli upload <user>/mcp-skill-registry . . --repo-type space

make install   # editable install with dev extras
make test      # pytest (37+ tests)
make lint      # ruff + black --check
make format    # ruff --fix + black
make run       # local dev server

pytest -q                     # all tests
pytest tests/test_api.py      # specific test module
pytest -k "test_upload"       # by name pattern

mcp-skills-registry/
├── src/skill_registry/         # the server (layered package)
│   ├── api/                    # HTTP routers (health, mcp, rest)
│   ├── mcp/                    # JSON-RPC 2.0 protocol handler
│   ├── services/               # business logic
│   │   ├── registry.py         # facade: coordinates all services
│   │   ├── loader.py           # SKILL.md parser & skill discovery
│   │   ├── validator.py        # input validation against manifests
│   │   ├── executor.py         # subprocess execution + timeout
│   │   ├── _runner.py          # child process skill runner
│   │   ├── search.py           # keyword & semantic search
│   │   ├── installer.py        # ZIP upload (zip-slip/bomb guards)
│   │   ├── github_publisher.py # auto-commit uploads to GitHub
│   │   ├── agent_loader.py     # AGENT.md parser & agent discovery
│   │   └── audit.py            # append-only audit trail
│   ├── repositories/           # execution history & audit persistence
│   ├── db/                     # SQLite wrapper + schema.sql
│   ├── models/                 # pydantic domain models
│   ├── config.py               # env-driven settings (SKILLREG_*)
│   ├── container.py            # composition root (build_container)
│   └── main.py                 # app factory + CLI entrypoint
│
├── skills/                     # self-contained skills (auto-discovered)
│   ├── _template/              # scaffold skeleton for new skills
│   ├── text-statistics/        # worked example
│   ├── change-impact-analysis/ # graph-driven deployment risk analysis
│   ├── speckit/                # spec-driven development suite
│   │   ├── constitution/
│   │   ├── specify/
│   │   ├── plan/
│   │   └── tasks/
│   └── factory/                # governed engineering suite
│       ├── legacy-discovery/
│       ├── topology-planning/
│       ├── task-decomposition/
│       ├── ui-modernization/
│       ├── test-generation/
│       └── spec-governance/
│
├── agents/                     # agent orchestration definitions
│   ├── arch-analyst/
│   ├── migration-eng/
│   └── gatekeeper/
│
├── frontend/                   # Next.js dashboard (static export)
│   ├── app/                    # Next.js app router pages
│   └── out/                    # built static files (served by FastAPI)
│
├── scripts/                    # utilities
│   ├── new_skill.py            # scaffold a new skill
│   └── hf_entrypoint.sh        # Hugging Face Spaces boot script
│
├── tests/                      # pytest suite
│   ├── test_api.py             # REST API tests
│   ├── test_mcp_transport.py   # MCP protocol tests
│   ├── test_loader.py          # skill loader tests
│   ├── test_validator.py       # input validation tests
│   ├── test_executor.py        # subprocess execution tests
│   ├── test_upload.py          # ZIP upload + install tests
│   ├── test_agents.py          # agent loading + API tests
│   └── test_github_publisher.py # GitHub auto-publish tests
│
├── docs/                       # extended documentation
│   ├── ARCHITECTURE.md         # layered design & execution model
│   ├── ADDING_A_SKILL.md       # full skill authoring guide
│   ├── DEPLOYMENT.md           # GitHub → HF Spaces pipeline
│   └── SKILL_AND_AGENT_REFERENCE.md  # file-by-file reference
│
├── .github/workflows/
│   ├── ci.yml                  # lint + test on Python 3.10–3.12
│   └── deploy-hf.yml          # auto-deploy to Hugging Face Spaces
│
├── Dockerfile                  # multi-stage: Node (frontend) + Python (server)
├── pyproject.toml              # project metadata, deps, tool config
├── requirements.txt            # HF Spaces runtime deps
├── Makefile                    # dev shortcuts (install, test, lint, run)
├── app.py                      # thin ASGI entrypoint shim
├── CONTRIBUTING.md             # contributor guide
└── LICENSE                     # MIT

# Dev setup
python -m venv .venv && source .venv/bin/activate
make install

# Before opening a PR
make format         # ruff --fix + black
make lint           # ruff + black --check
make test           # pytest