Content
# ⚓ SkillPort
<div align="center">
**The SkillOps Toolkit for Agent Skills**
SkillOps = Validate, manage, and deliver skills at scale.
[](https://python.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
</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](https://www.anthropic.com/engineering/advanced-tool-use) 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](https://agentskills.io/specification).
---
## Features
### Validate
Check skills against the [Agent Skills specification](https://agentskills.io/specification).
```bash
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.
```bash
# 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.
```bash
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](https://www.anthropic.com/engineering/advanced-tool-use) 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
```bash
uv tool install skillport
# or: pip install skillport
```
### Add Skills
```bash
# Add from GitHub
skillport add anthropics/skills skills
# Or use a custom skills directory
skillport --skills-dir .claude/skills add anthropics/skills skills
```
### Validate
```bash
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**](#cli-mode) | Agents with shell access (Cursor, Windsurf, Codex, etc.) | Per-project |
| [**MCP Mode**](#mcp-mode) | MCP-compatible clients, multi-project | One-time |
### CLI Mode
For agents that can run shell commands. No MCP configuration required.
```bash
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:
```bash
uv tool install skillport-mcp
```
Add to your client's config:
```json
{
"mcpServers": {
"skillport": {
"command": "uvx",
"args": ["skillport-mcp"],
"env": { "SKILLPORT_SKILLS_DIR": "~/.skillport/skills" }
}
}
}
```
<details>
<summary>One-click install for popular clients</summary>
**Cursor**
[](cursor://anysphere.cursor-deeplink/mcp/install?name=skillport&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJza2lsbHBvcnQtbWNwIl0sImVudiI6eyJTS0lMTFBPUlRfU0tJTExTX0RJUiI6In4vLnNraWxscG9ydC9za2lsbHMifX0=)
**VS Code / GitHub Copilot**
[](https://insiders.vscode.dev/redirect/mcp/install?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport-mcp%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%7D)
**Kiro**
[](https://kiro.dev/launch/mcp/add?name=skillport&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22skillport-mcp%22%5D%2C%22env%22%3A%7B%22SKILLPORT_SKILLS_DIR%22%3A%22~/.skillport/skills%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
**CLI Agents**
```bash
# 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:
```yaml
# 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:
```json
{
"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:
```markdown
---
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](guide/creating-skills.md) for best practices.
---
## Skill Sources
| Source | Features | Target | URL |
|--------|----------|--------|-----|
| Anthropic Official | Document skills (docx, pdf, pptx, xlsx), design, MCP builder | All users | [GitHub](https://github.com/anthropics/skills/tree/main/skills) |
| Awesome Claude Skills | Curated community collection, 2.5k+ stars | Discovery | [GitHub](https://github.com/ComposioHQ/awesome-claude-skills) |
| Hugging Face Skills | Dataset creation, model evaluation, LLM training, paper publishing | ML/AI engineers | [GitHub](https://github.com/huggingface/skills) |
| Claude Scientific Skills | 128+ scientific skills (bio, chem, ML), 26+ databases | Researchers | [GitHub](https://github.com/K-Dense-AI/claude-scientific-skills) |
| ClaudeKit Skills | 30+ skills, auth, multimodal, problem-solving frameworks | Full-stack devs | [GitHub](https://github.com/mrgoonie/claudekit-skills) |
| Superpowers | TDD, debugging, parallel agents, code review workflows | Quality-focused devs | [GitHub](https://github.com/obra/superpowers) |
| Kubernetes Operations | K8s deployment, monitoring, troubleshooting | DevOps/SRE | [GitHub](https://github.com/wshobson/agents/tree/main/plugins/kubernetes-operations/skills) |
---
## Learn More
- [Configuration Guide](guide/configuration.md)
- [Creating Skills](guide/creating-skills.md)
- [CLI Reference](guide/cli.md)
- [Design Philosophy](guide/philosophy.md)
---
## Development
> **Status:** Work in progress. APIs may change.
```bash
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
