⚓ SkillPort

Why SkillPort?

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:

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:

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" }
    }
  }
}

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

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

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

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

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