skills

The Skills MCP Server exposes Claude-compatible skills as MCP tools. Each skill is a directory containing a SKILL.md that defines the task instructions for the AI. When the server starts, it scans the configured skills directory (defaulting to ~/.skills) and registers each skill as a distinct MCP tool named after the skill (converted to a valid tool name). Clients can call these tools via MCP to have the model follow the skill’s detailed instructions for tasks like code review, documentation, or workflow guidance. You can run the server locally with the default setup or point it at a custom skills directory and optionally enable verbose logging for debugging. The Docker guidance shows how to mount your skills directory into the container so the server can discover and expose them as tools.

Prerequisites:

• Go (for building from source if you choose to)
• Docker (optional, for containerized usage)
• A skills directory containing SKILL.md files organized per skill

Installation steps:

1. Install the pre-built binary (recommended):

• Visit the GitHub Releases page for portertech/skills-mcp-server and download the appropriate binary for your platform.
• Place the binary in a directory on your PATH, e.g. /usr/local/bin.

2. Build from source (optional):

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

3. Run the server locally:

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

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

4. Run with Docker (optional):

# Pull the image
docker pull portertech/skills-mcp-server:latest

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

5. Verify installation by listing skills (if you have a SKILL.md with proper content):

skills --list /path/to/skills

Notes and tips:

• The server discovers skills by scanning the configured skills directory for SKILL.md files. Each discovered skill becomes an MCP tool using a normalized name (lowercased, spaces/hyphens replaced with underscores). If two skills map to the same tool name, the first is registered and the second is skipped with a warning.
• To integrate with an MCP client (Claude-style), provide a configuration with mcpServers.skills.command set to the binary (or docker invocation) and point the argument path to your skills directory. For Docker usage, you can mount the skills directory into the container and pass the path inside the container as an argument.
• If you want verbose logging for troubleshooting, start the server with a verbose flag or environment variable if supported by the build, and check logs for tool discovery messages and invocation traces.
• The skills directory should contain subdirectories representing individual skills, each with a SKILL.md that defines the name and description shown in tool listings. Ensure YAML frontmatter in SKILL.md is valid and that the tool naming rules are followed to prevent collisions.
• No external dependencies beyond standard Go tooling are required when using the pre-built binary; building from source requires Go tooling on your host.