Skills MCP Server

A no-nonsense MCP (Model Context Protocol) server that exposes Claude-compatible skills as tools, enabling any agent with an MCP client to use them. Minimal by design, written in Go.

Installation

Pre-built binaries are available on the GitHub Releases page.

Go Install

go install github.com/portertech/skills-mcp-server/cmd/skills@latest

Build from Source

git clone https://github.com/portertech/skills-mcp-server.git
cd skills-mcp-server
go build -o skills ./cmd/skills

Docker

docker pull portertech/skills-mcp-server:latest

Or build locally:

docker build -t skills-mcp-server:latest .

Usage

# Start the server with default skills directory (~/.skills)
skills

# Start with a custom skills directory
skills /path/to/skills

# List discovered skills
skills --list /path/to/skills

# Enable verbose logging
skills --verbose /path/to/skills

Docker

# Run with skills directory mounted
docker run -i --mount type=bind,src=$HOME/.skills,dst=/skills,readonly skills-mcp-server:latest /skills

# List skills
docker run --mount type=bind,src=$HOME/.skills,dst=/skills,readonly skills-mcp-server:latest --list /skills

MCP Client Configuration

Claude Code / Cursor / etc.

Add to your MCP configuration:

{
  "mcpServers": {
    "skills": {
      "command": "skills",
      "args": ["/path/to/your/skills"]
    }
  }
}

Docker

{
  "mcpServers": {
    "skills": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--mount", "type=bind,src=/path/to/skills,dst=/skills,readonly", "skills-mcp-server:latest", "/skills"]
    }
  }
}

Creating Skills

Skills are directories containing a SKILL.md file with YAML frontmatter:

~/.skills/
├── code-review/
│   └── SKILL.md
└── git-workflow/
    └── SKILL.md

SKILL.md Format

---
name: my-skill
description: A brief description of what this skill does
---

# My Skill

Detailed instructions for the AI to follow when using this skill.

## Guidelines

- Specific rules and best practices
- Step-by-step procedures
- Examples and templates

Required Fields

• name: Unique skill identifier
• description: Brief description shown in tool listings

How It Works

1. Discovery: The server scans the skills directory for SKILL.md files
2. Registration: Each skill becomes an MCP tool named after the skill
3. Invocation: When a model calls the tool, it receives the skill's instructions
4. Execution: The model follows the instructions to complete the task

Tool Naming

Skill names are converted to valid MCP tool names:

The conversion:

• Lowercases the name
• Replaces spaces and hyphens with underscores

Note: Skills that would produce the same tool name (e.g., code-review and code_review) are considered duplicates. The first one discovered is registered; subsequent collisions are skipped with a warning.

Example Interaction

User: "Review my pull request"

Model: Invokes code_review tool

Server returns:

# Skill: code-review

**Description:** Expert code review guidance...

---

When reviewing code, follow these guidelines...

Model: Uses the instructions to perform a thorough code review.

Development

# Run tests
make test

# Run tests with coverage
make test-cover

# Build
make build

# Format code
make fmt

# Run all checks
make ci

# Test with sample skills
make list-test

See Makefile for all available targets.

Release Process

# Check current version
make version

# Run all checks before release
make ci

# Create a release (runs ci, tags, and pushes to Docker Hub)
make release VERSION=1.0.0

The release target:

1. Runs make ci (lint + test)
2. Creates an annotated git tag v<VERSION>
3. Builds and pushes multi-arch Docker images to Docker Hub

To release manually:

# Create and push tag
make tag-version VERSION=1.0.0
git push origin v1.0.0

# Build and push Docker images
make docker-login  # requires DOCKER_USERNAME and DOCKER_PASSWORD
make docker-publish VERSION=1.0.0

License

MIT