skillport 0.1.0b2

Bring Agent Skills to Cursor / Copilot / Codex & more — via CLI or MCP. Manage once, serve anywhere.

⚓ SkillPort

🚢 All Your Agent Skills in One Place - Manage once, serve anywhere ⚓

Agent Skills → Cursor · Copilot · Codex & more - via CLI or MCP

Why SkillPort?

Claude Agent Skills are great - but they only work in Claude. What about Cursor, Copilot, Codex? With dozens of skills loaded upfront, there's less context and agent performance suffers.

Context Engineering for Expert Knowledge - SkillPort brings expertise into context-only when needed.

When you...	SkillPort helps by...
Switching to Cursor with 20+ Agent skills	Add one line to config - all skills work instantly	MCP Server →
Team using Cursor, Copilot, and Codex	Share one folder, filter by category per tool	Organize →
50+ skills, "which one was for PR reviews?"	Search by keyword - finds it in milliseconds	Scale →
Long debugging session, context running low	Skills load on-demand - not all upfront	Scale →
Found an awesome skill on GitHub	skillport add <url> - ready to use in seconds	CLI →
Don't want to set up MCP	CLI works standalone - init, add, sync to AGENTS.md	CLI Mode →

🔄 Compatible with Claude Agent Skills - Write skills once, use everywhere. Skills that work with Claude Code work with SkillPort, and vice versa.

Quick Start (5 min)

Choose your setup:

Mode	Best for	Per-project setup
MCP Mode	Multi-project, per-client filtering	Not required
CLI Mode	Quick Setup, single project	Required (skillport init)

Tip: Start with MCP Mode for the full experience. CLI Mode is simpler but requires setup in each project.

---

MCP Mode

1. Install

Skip this step if you only want to serve an existing skills directory via MCP.

Install to manage skills and use them without MCP:

uv tool install skillport
# or: pip install skillport

Enables add, remove, lint, search, show, and sync (export to AGENTS.md for non-MCP agents).

2. Add Skills

Skip this step if you already have skills (e.g., in .claude/skills/). Just point SKILLPORT_SKILLS_DIR to it in step 3.

# Add a sample skill
skillport add hello-world

# Or add from GitHub
skillport add https://github.com/anthropics/skills

3. Add to Your MCP Client

To customize environment variables, use manual configuration below instead of one-click install.

Cursor (one-click)

VS Code / GitHub Copilot (one-click)

Kiro (one-click)

CLI Agents

# Claude Code
claude mcp add skillport -- uvx skillport

# With custom skills directory
claude mcp add skillport --env SKILLPORT_SKILLS_DIR=~/.claude/skills -- uvx skillport

# Codex
codex mcp add skillport -- uvx skillport

# With custom skills in the project directory
codex mcp add skillport --env SKILLPORT_SKILLS_DIR=./.agent/skills -- uvx skillport

Other MCP Clients (Windsurf, Cline, Roo Code, Gemini CLI, etc.)

Add to your client's MCP config file:

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

Client	Config file
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	VS Code settings or .cline/mcp_settings.json
Roo Code	.roo/mcp.json (project) or VS Code settings

Claude Desktop (Not Recommended, Use the official Agent Skills)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

4. Use It

Ask your AI: "Search for hello-world and run it"

The agent will:

1. search_skills("hello-world") - find matching skills
2. load_skill("hello-world") - get instructions + path
3. Follow the instructions using its tools

---

CLI Mode

For: Coding agents with shell commands (Cursor, Windsurf, Cline, Copilot, Codex, Gemini CLI, etc.)

Skills sync to AGENTS.md and load via skillport show. No MCP configuration needed.

# 1. Install
uv tool install skillport

# 2. Add skills
skillport add hello-world
skillport add https://github.com/anthropics/skills

# 3. Initialize your project
skillport init
# → Select skills directory and instruction files interactively
# → Creates .skillportrc, syncs skills to AGENTS.md

How it works: Your agent reads the skills table in AGENTS.md, then runs skillport show <id> to load full instructions.

Note: CLI mode requires skillport init in each project. For multi-project use, consider MCP Mode.

Key Features

Deliver: MCP Server

Tools for progressive skill loading:

Tool	Transport	Purpose
search_skills(query)	stdio, HTTP	Find skills by task description
load_skill(skill_id)	stdio, HTTP	Get full instructions and filesystem path
read_skill_file(skill_id, file_path)	HTTP only	Read files (experimental)

stdio (default): The path from load_skill is accessible in the agent's execution environment-agents can read files and run scripts directly.

Streamable HTTP (experimental): For remote agents without filesystem access. Adds read_skill_file but is not fully tested yet.

Manage: CLI

Project Setup:

skillport init              # Initialize project (.skillportrc, AGENTS.md)
skillport sync              # Update AGENTS.md when skills change
skillport sync --all        # Update all instruction files in .skillportrc

Skill Management:

skillport add <source>      # GitHub URL, local path, or built-in name
skillport list              # See installed skills
skillport remove <id>       # Uninstall a skill
skillport lint [id]         # Validate skill files

Search & Load:

skillport search <query>    # Find skills by description
skillport show <id>         # View skill details and instructions

Install from GitHub:

One command to install skills from any GitHub URL-no cloning required. Supports branches and subdirectories:

# Anthropic official skills
skillport add https://github.com/anthropics/skills

# Specific path in a repo
skillport add https://github.com/wshobson/agents/tree/main/plugins/developer-essentials/skills

Discover more: Awesome Claude Skills Claude Scientific Skills・ Kubernetes Operations ・ Notion Skills

Organize: Categories & Namespaces

Use metadata.skillport to:

• Search - category and tags improve discoverability
• Filtering - Control which skills each client sees
• Core Skills - alwaysApply: true for always-available skills

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

Client-Based Skill Filtering:

Expose different skills to different AI agents:

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

{
  "mcpServers": {
    "writing-skills": {
      "command": "uvx",
      "args": ["skillport"],
      "env": { "SKILLPORT_ENABLED_CATEGORIES": "writing,research" }
    }
  }
}

Filter options:

• SKILLPORT_ENABLED_SKILLS - Specific skill IDs
• SKILLPORT_ENABLED_CATEGORIES - By category
• SKILLPORT_ENABLED_NAMESPACES - By directory prefix
• SKILLPORT_CORE_SKILLS_MODE - Skills visible to agent without searching (auto/explicit/none)

Scale: Progressive Disclosure

The Problem:

System Prompt (every conversation):
├── Company guidelines (2,000 tokens)
├── Coding standards (3,000 tokens)
├── Review checklist (1,500 tokens)
├── 50 more instructions...
└── Total: 30,000+ tokens before you say "hello"

The Solution: Skills load progressively - metadata first, full instructions on demand:

Stage	Tokens	When
Metadata	~100/skill	Always (searchable)
Instructions	~5,000	On load_skill()

100 skills = ~15K tokens (vs 300K+ if all loaded upfront)

SkillPort enhances this with:

• BM25 search - Find the right skill without loading all metadata
• Per-client filtering - Expose only relevant skills to each agent
• Fallback chain - FTS → substring (always returns results)

Design: Path-Based Execution

SkillPort provides knowledge, not a runtime. Instead of executing code, it returns filesystem paths:

# load_skill returns:
{
    "instructions": "How to extract text from PDFs...",
    "path": "/Users/me/.skillport/skills/pdf-extractor"
}

The agent executes scripts directly:

python {path}/scripts/extract.py input.pdf -o result.txt

Context Engineering: Executing code doesn't require reading code.

Approach	Context Cost
Read script → execute	~2,000 tokens
Execute via path	~20 tokens

This keeps SkillPort simple and secure-it's a harbor, not a runtime.

Design Philosophy →

Configuration

Variable	Description	Default
SKILLPORT_SKILLS_DIR	Skills directory	~/.skillport/skills
SKILLPORT_ENABLED_CATEGORIES	Filter by category (comma-separated)	all
SKILLPORT_ENABLED_SKILLS	Filter by skill ID (comma-separated)	all
SKILLPORT_ENABLED_NAMESPACES	Filter by namespace (comma-separated)	all
SKILLPORT_CORE_SKILLS_MODE	Core Skills behavior (auto/explicit/none)	auto
SKILLPORT_CORE_SKILLS	Core Skill IDs for explicit mode (comma-separated)	none

Full Configuration Guide →

Creating Skills

Create a SKILL.md file with YAML frontmatter. name and description are required:

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

Instructions for the AI agent.

Skill Authoring Guide →

Learn More

• Configuration Guide - Filtering, search options, multi-client setup
• Creating Skills - SKILL.md format and best practices
• CLI Reference - Full command documentation
• Design Philosophy - Why skills work this way

Development

git clone https://github.com/gotalab/skillport.git
cd skillport
uv sync
SKILLPORT_SKILLS_DIR=.agent/skills uv run skillport serve

License

MIT