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```bash
go install github.com/portertech/skills-mcp-server/cmd/skills@latest
### Build from Source```bash
git clone https://github.com/portertech/skills-mcp-server.git
cd skills-mcp-server
go build -o skills ./cmd/skills
Docker```bash
docker pull portertech/skills-mcp-server:latest
Or build locally:```bash
docker build -t skills-mcp-server:latest .
Usage```bash
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```bash
# 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:```json
{
"mcpServers": {
"skills": {
"command": "skills",
"args": ["/path/to/your/skills"]
}
}
}
### Docker```json
{
"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```markdown
---
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 identifierdescription: Brief description shown in tool listings
How It Works
- Discovery: The server scans the skills directory for
SKILL.mdfiles - Registration: Each skill becomes an MCP tool named after the skill
- Invocation: When a model calls the tool, it receives the skill's instructions
- Execution: The model follows the instructions to complete the task
Tool Naming
Skill names are converted to valid MCP tool names:
| Skill Name | Tool Name |
|---|---|
code-review |
code_review |
My Skill |
my_skill |
git-workflow |
git_workflow |
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```bash
# 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```bash
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`
3. Builds and pushes multi-arch Docker images to Docker Hub
To release manually:```bash
# 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
