Skillberry-store service (a.k.a., SBS)

This service implements a smart skills repository for agentic workflows. Manage, execute, and organize your skills, tools and snippets with powerful search and lifecycle management.

▶ Watch full highlights video

Features ✨

• Manage tools for agentic workloads: Add (Persist), Remove, Update, and Delete tools.
• Tools Execution: Invoke tools (with parameters) using Docker (sand-boxing).
• Tools Search and list: Shortlist tools using semantic and classic search.
• Tools Life Cycle Management: Provides tools life cycle management (state, visibility, etc.).
• Tools Persistence: Support persistence of tools into filesystem, GitHub repos etc.
• Namespaces: Organize and label skills, tools, and snippets using namespaces for better categorization and filtering.
• Observability: Provide metrics and traces for operational and behavioural analysis of tools usage.
• OpenAPI frontend: FastAPI endpoint to interact and manage tools (using tools-manifest artifacts)
• CLI Support: Command-line interface for all API operations.
• MCP frontend: Expose virtual MCP servers for any subset of the tools or all of them.
• NFS/WebDAV frontend: Expose skills as mountable filesystems (vNFS) over WebDAV or NFSv3 — readable by any tool that can mount a network drive.
• Support Multiple MCP backends: Consume and route additional tools from multiple backend MCP servers.
• Agentic Framework Integration: Connect to different agentic frameworks via the MCP frontend.
• MCP control API: Exposes an MCP server API for each of the available REST operations ( e.g., add tools, semantic search etc.)
• Plugin Architecture: Extensible plugin system for AI-powered content generation, evaluation, and optimization. See Plugin Installation Guide.

Quickstart 🚀

Installation 📦

Install skillberry-store without plugins (minimal installation):

pip install skillberry-store

Or install with plugins:

# All plugins
pip install skillberry-store[plugins-all]

# Creator plugin only (AI-powered content generation)
pip install skillberry-store[plugin-creator]

# Evaluator plugin only (AI-powered content evaluation)
pip install skillberry-store[plugin-evaluator]

# Dedupe plugin only (AI-powered duplicate skill detection)
pip install skillberry-store[plugin-dedupe]

# Skill Optimizer plugin only (optimize existing skills using Claude Code)
pip install skillberry-store[plugin-skill-optimizer]

# Multiple specific plugins
pip install skillberry-store[plugin-creator,plugin-evaluator,plugin-skill-optimizer]

For detailed plugin installation options and configuration, see the Plugin Installation Guide.

Run the Service with Docker or Podman 🐳

make docker-run

Note: use make help for a complete list of options

You can control where SBS stores its data by setting SBS_BASE_DIR (defaults to the system temp directory).

Interacting with the UI 👨‍💻

The Skillberry Store now includes a modern web UI that starts automatically with the backend:

• Web UI: http://localhost:8002 - Modern React-based interface
• API Documentation: http://localhost:8000/docs - OpenAPI/Swagger interface

The Web UI provides:

• Visual management of Tools, Skills, Snippets, VMCP Servers, and vNFS Servers
• Search and filtering capabilities
• Tool execution with parameter input
• Code viewing and editing
• Real-time updates

To disable the UI and run only the backend:

ENABLE_UI=false make run

Prerequisites 🛠️

• Docker or Podman is installed on your machine.

The default is docker. If you want to use podman, include this line

docker alias=`podman`

into one (or more) of the following configuration files, depending on which shell(s) you are using

• ~/.zshrc
• ~/.bashrc
• ~/.bash_profile
• ~/.profile

Additional requisites for local deployment:

• Your user has Docker permissions (i.e., is a member of the docker group).
• The Docker logging driver is set to either json-file or journald.

Check the logging driver with the following command:

docker info --format '{{.LoggingDriver}}'

If the response is not json-file or journald, configure your Docker logging as documented here.

Running with podman on MacOS ⚒️

• Alias docker to podman, as explained in Prerequisites
• Create and start a Podman machine:

podman machine init --now --cpus=4 --memory=4096 -v /tmp:/tmp podman-machine-default

if you already have a default Podman machine with this name, then you need to first

podman machine stop
podman machine rm podman-machine-default

Then rerun Podman machine initialization and

make docker-run

Design Requirements

See DESIGN_REQUIREMENTS.md

Local installation 📦

We support Linux, macOS, and Windows.

git clone [email protected]:skillberry-ai/skillberry-store.git
cd skillberry-store

On Linux, macOS, or WSL:

make install-requirements

On Windows (no WSL needed):

pip install -e .

Start the Service locally (alternative to docker) 🚀

On Linux, macOS, or WSL:

make run

On Windows:

sbs-srv

Notes:

• By default, SBS runs on host 0.0.0.0 and port 8000 publishing its metrics on port 8090. To change, set the environment variables SBS_PORT/SBS_HOST/PROMETHEUS_METRICS_PORT
• To disable observability all together, set environment variable OBSERVABILITY with False
• The Web UI starts automatically on port 3000. To disable it, set ENABLE_UI=false
• On first run, the UI will automatically install its dependencies (requires Node.js 18+)

Web UI Features 🎨

The Skillberry Store includes a modern React-based web interface with:

• Tools Management: Create, view, execute, and delete tools with file upload support
• Skills Management: Organize tools and snippets into reusable skills
• Snippets Management: Store and manage code snippets with syntax highlighting
• VMCP Servers: Create and manage virtual MCP servers for tool subsets
• vNFS Servers: Expose skills as mountable WebDAV or NFS filesystems
• Search & Filter: Semantic search across all resources
• Real-time Updates: Automatic refresh of data using TanStack Query
• Responsive Design: Built with PatternFly (IBM's design system)

UI Technology Stack

• React 18 + TypeScript
• Vite (fast development server)
• PatternFly (IBM design system)
• TanStack Query (data fetching)
• React Router (navigation)

UI Development

To work on the UI separately:

cd src/skillberry_store/ui
npm install
npm run dev

The UI source code is located in src/skillberry_store/ui/ and includes:

• src/pages/ - Page components for each section
• src/components/ - Reusable UI components
• src/services/ - API client layer
• src/types/ - TypeScript type definitions

Engage with the Service via OpenAPI 📜

Open a browser against http://127.0.0.1:8000/docs .

Engage with the Service through a Python Client 🐍

The service can be consumed via skillberry store service sdk. Refer to skillberry-store-sdk for installation and usage.

Engage with the Service via CLI 💻

A CLI (auto-generated) that provides command-line access to all API operations.
Example usage:

# Install the SDK (includes CLI)
pip install skillberry-store-sdk

# Use the CLI
sbs --help                     # Show available commands
sbs connect http://prod:8000   # Connect to different server
sbs list-skills                # List all skills
sbs get-tool convert           # Get a specific tool
sbs create-vmcp-server         # Create a VMCP server
sbs search-tools "calculator"  # Search for tools

Available command groups:

For detailed CLI documentation, see docs/cli.md.

Engage with the Service via MCP 📜

Each control API function is available as an MCP tool to be used by agentic AI workflows.
To access use an MCP client against http://127.0.0.1:8000/control_sse .

Virtual MCP Servers (VMCP)

A VMCP server exposes a single skill's tools and snippets as a standalone MCP endpoint.
Create one via the UI (Virtual MCP Servers → Create VMCP Server) or the REST API:

curl -X POST "http://localhost:8000/vmcp_servers/?name=my-skill&skill_uuid=<uuid>"

Connect an MCP client to http://localhost:<assigned-port>/sse.

Support Multiple MCP Backends

Follow the steps outlined in Connecting MCP as a backend.

Virtual NFS Servers (vNFS) 🗂️

A vNFS server exposes a single skill as a mountable read-only filesystem over WebDAV or NFSv3.
This lets any tool — including Claude Code — read skill files directly via mount or rclone,
without going through the REST API.

Create a vNFS server via the UI (Virtual NFS Servers → Create vNFS Server) or the REST API:

# WebDAV (default)
curl -X POST "http://localhost:8000/vnfs_servers/?name=my-skill&skill_uuid=<uuid>&protocol=webdav"

# NFSv3
curl -X POST "http://localhost:8000/vnfs_servers/?name=my-skill&skill_uuid=<uuid>&protocol=nfs"

Mounting — WebDAV

The easiest option is rclone (no root required, works on Linux, macOS, WSL2):

# Install: brew install rclone  /  apt install rclone  /  dnf install rclone
rclone mount :webdav: /mnt/skill \
  --webdav-url=http://localhost:<port>/<skill-name> \
  --read-only --daemon

# Unmount
fusermount3 -u /mnt/skill

Alternatively, with davfs2:

# Install: apt install davfs2  /  dnf install davfs2
sudo mount -t davfs http://localhost:<port>/<skill-name> /mnt/skill

# Unmount
sudo umount /mnt/skill

Mounting — NFSv3

# Install: apt install nfs-common  /  dnf install nfs-utils
sudo mount -t nfs localhost:/ /mnt/skill \
  -o port=<port>,mountport=<port>,nfsvers=3,proto=tcp,nolock,soft

# Skill files are at /mnt/skill/<skill-name>/

# Unmount
sudo umount /mnt/skill

The UI Virtual NFS Servers detail page shows the exact commands pre-filled with the correct port and skill name.

Run SBS with GitHub backend

Follow the steps outlined in Github backend.

Monitoring the Service 📈

To start a local Prometheus server execute:

echo -e "global:\n  scrape_interval: 5s\nscrape_configs:\n  - job_name: \"skillberry-store\"\n    static_configs:\n      - targets: [\"localhost:8090\"]\n    metric_relabel_configs:\n      - source_labels: [__name__]\n        regex: '.*_created'\n        action: drop" > /tmp/prometheus.yml
docker run --rm --name prometheus --network="host" -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml

Metrics are available in Prometheus at http://localhost:9090.

Note: Application metrics are prefixed with SBS_.

To start a local Jaeger server execute:

docker run --rm --name jaeger --network="host" -p 4317:4317 -p 16686:16686 jaegertracing/all-in-one:latest

Traces are available in Jaeger at http://localhost:16686.

📚 Additional documentation can be found at docs.

• Customizing configurations details can be found here
• Guthub support details can be found here