Skillport MCP Server

⚓ SkillPort

<div align="center">

The SkillOps Toolkit for Agent Skills

SkillOps = Validate, manage, and deliver skills at scale.

</div>

---

Why SkillPort?

When you...	SkillPort...
Use a coding agent without native skill support	Serves via MCP or CLI
Build your own AI agent	Provides MCP server, CLI, and Python library
Have 50+ skills and need the right one fast	Search-first loading (Tool Search Tool pattern)
Check skills before deployment	Validates against the spec in CI
Manage skill metadata programmatically	Provides meta commands
Find a skill on GitHub	Installs with add <url>

Fully compatible with the Agent Skills specification.

---

Features

Validate

Check skills against the Agent Skills specification.

skillport validate                    # Validate all skills
skillport validate ./skills           # Validate specific directory
skillport validate --json             # CI-friendly JSON output

Catches missing fields, naming issues, and spec violations before they cause problems.

Manage

Full lifecycle management from any source.

# Add from GitHub (shorthand)
skillport add anthropics/skills skills

# Add from GitHub (full URL)
skillport add https://github.com/anthropics/skills/tree/main/skills

# Add from local path or zip
skillport add ./my-skills
skillport add skills.zip

# Update, list, remove
skillport update                      # Update all from original sources
skillport list                        # See installed skills
skillport remove <skill-id>           # Uninstall

Metadata

Update skill metadata without editing files manually. Useful for automation and keeping skills consistent across a team.

skillport meta get <skill> <key>      # Get metadata value
skillport meta set <skill> <key> <val> # Set metadata value
skillport meta unset <skill> <key>    # Remove metadata key

Serve

MCP server for clients that don't natively support Agent Skills.

Inspired by Anthropic's Tool Search Tool pattern — search first, load on demand:

Tool	Purpose
search_skills(query)	Find skills by description (full-text search)
load_skill(skill_id)	Get full instructions + path

Why search matters: With 50+ skills, loading all upfront consumes context and hurts accuracy. SkillPort loads metadata only (~100 tokens/skill), then full instructions on demand.

Works with Cursor, Copilot, Windsurf, Cline, Codex, and any MCP-compatible client.

---

Quick Start

Install

uv tool install skillport
# or: pip install skillport

Add Skills

# Add from GitHub
skillport add anthropics/skills skills

# Or use a custom skills directory
skillport --skills-dir .claude/skills add anthropics/skills skills

Validate

skillport validate
# ✓ All 5 skill(s) pass validation

---

Connect to Agents

Choose how to deliver skills to your AI agents:

Mode	Best for	Setup
CLI Mode	Agents with shell access (Cursor, Windsurf, Codex, etc.)	Per-project
MCP Mode	MCP-compatible clients, multi-project	One-time

CLI Mode

For agents that can run shell commands. No MCP configuration required.

skillport init                        # Initialize project
skillport doc                         # Generate AGENTS.md with skill table
skillport show <id>                   # Load full instructions for a skill

How it works:

1. skillport doc generates a skill table in AGENTS.md
2. The agent reads AGENTS.md to discover available skills
3. When needed, the agent runs skillport show <id> to load full instructions

MCP Mode

For MCP-compatible clients. Install the server:

uv tool install skillport-mcp

Add to your client's config:

{
  "mcpServers": {
    "skillport": {
      "command": "uvx",
      "args": ["skillport-mcp"],
      "env": { "SKILLPORT_SKILLS_DIR": "~/.skillport/skills" }
    }
  }
}

<details> <summary>One-click install for popular clients</summary>

Cursor

VS Code / GitHub Copilot

Kiro

CLI Agents

# Codex
codex mcp add skillport -- uvx skillport-mcp

# Claude Code
claude mcp add skillport -- uvx skillport-mcp

</details>

---

Organization

Organize skills with categories and tags. Works with both CLI and MCP modes.

Categories & Tags

Use metadata to organize and filter skills:

# SKILL.md frontmatter
metadata:
  skillport:
    category: development
    tags: [testing, quality]
    alwaysApply: true  # Always available (Core Skills)

Per-Client Filtering

Expose different skills to different agents:

{
  "mcpServers": {
    "skillport-dev": {
      "command": "uvx",
      "args": ["skillport-mcp"],
      "env": { "SKILLPORT_ENABLED_CATEGORIES": "development,testing" }
    },
    "skillport-writing": {
      "command": "uvx",
      "args": ["skillport-mcp"],
      "env": { "SKILLPORT_ENABLED_CATEGORIES": "writing,research" }
    }
  }
}

---

Configuration

Variable	Description	Default
SKILLPORT_SKILLS_DIR	Skills directory	~/.skillport/skills
SKILLPORT_ENABLED_CATEGORIES	Filter by category	all
SKILLPORT_ENABLED_SKILLS	Filter by skill ID	all
SKILLPORT_ENABLED_NAMESPACES	Filter by namespace	all
SKILLPORT_CORE_SKILLS_MODE	Core Skills behavior (auto/explicit/none)	auto

---

Creating Skills

Create a SKILL.md with YAML frontmatter:

---
name: my-skill
description: What this skill does
metadata:
  skillport:
    category: development
    tags: [example]
---
# My Skill

Instructions for the AI agent.

See Creating Skills Guide for best practices.

---

Skill Sources

Source	Features	Target	URL
Anthropic Official	Document skills (docx, pdf, pptx, xlsx), design, MCP builder	All users	GitHub
Awesome Claude Skills	Curated community collection, 2.5k+ stars	Discovery	GitHub
Hugging Face Skills	Dataset creation, model evaluation, LLM training, paper publishing	ML/AI engineers	GitHub
Claude Scientific Skills	128+ scientific skills (bio, chem, ML), 26+ databases	Researchers	GitHub
ClaudeKit Skills	30+ skills, auth, multimodal, problem-solving frameworks	Full-stack devs	GitHub
Superpowers	TDD, debugging, parallel agents, code review workflows	Quality-focused devs	GitHub
Kubernetes Operations	K8s deployment, monitoring, troubleshooting	DevOps/SRE	GitHub

---

Learn More

• Configuration Guide
• Creating Skills
• CLI Reference
• Design Philosophy

---

Development

Status: Work in progress. APIs may change.

git clone https://github.com/gotalab/skillport.git
cd skillport
uv sync

# Run MCP server
SKILLPORT_SKILLS_DIR=.skills uv run skillport-mcp

# Run CLI
uv run skillport --help

# Run tests
uv run pytest

---

License

MIT

Local publishing credentials

Local PyPI and TestPyPI tokens are read from 1Password only by uv publish, including its dry-run mode; builds receive no publishing credential. Provision the ignored .env.publish-pypi and .env.publish-testpypi maps with UV_PUBLISH_TOKEN=op://<vault>/<item>/credential; store one key per item under the publish tag. Use make publish-check or make publish-test-check to build all three distributions and run uv publish --dry-run without uploading. A dry-run reads the credential but does not prove its validity or upload permissions. make publish and make publish-test perform the uploads when explicitly requested. These local tasks require 1Password CLI and a current uv with publish dry-run support. The GitHub Actions release workflow continues to use PyPI Trusted Publishing (OIDC).