SkillPort: a SkillOps CLI and MCP server for Agent Skills

The problem SkillPort solves for teams with many skills

Agent Skills are folders containing a SKILL.md file with YAML frontmatter, and the Agent Skills specification defines what that file must contain. The awkward part is not writing one skill. It is what happens at fifty. A coding agent that loads every skill upfront spends context on instructions it will not use, and the README states that this hurts accuracy. SkillPort addresses that with a search-first loading pattern the README attributes to Anthropic's Tool Search Tool: metadata is loaded first at roughly 100 tokens per skill, and full instructions arrive only when a specific skill is requested.

The second problem is portability. Cursor, Copilot, Windsurf, Cline and Codex do not all handle skills the same way, and some have no native support at all. SkillPort presents itself as the delivery layer between a skills directory on disk and whatever agent is reading it. The README frames the audience as three groups: people using a coding agent without native skill support, people building their own agent, and people who need to validate skills before deployment. If you have five skills and one agent, this is overhead. If you have fifty skills and four clients, the validation and filtering commands start to earn their place.

How the CLI, the MCP server and the index fit together

The repository splits into two installable packages. The PyPI project named skillport is the CLI, and its pyproject.toml describes it as the "SkillOps CLI for Agent Skills" that manages skills on disk. The MCP server ships separately as skillport-mcp, and the CLI's project description points users to it explicitly for indexed search. That separation matters when you are deciding what to install on a developer machine versus what to configure in a client.

The CLI has four command groups visible in the README. validate checks skills against the spec and can emit JSON for CI. add, update, list and remove handle lifecycle, with add accepting a GitHub shorthand, a full URL, a local path or a zip. meta get, meta set and meta unset edit frontmatter keys without opening files. init, doc and show drive the CLI delivery mode.

Delivery has two paths. In CLI mode, skillport doc generates a skill table inside AGENTS.md; the agent reads that table, then runs skillport show <id> to pull full instructions. In MCP mode, the server exposes two tools, search_skills(query) for full-text search and load_skill(skill_id) for the full instructions plus path. Filtering happens through environment variables: SKILLPORT_ENABLED_CATEGORIES, SKILLPORT_ENABLED_SKILLS and SKILLPORT_ENABLED_NAMESPACES. The README shows two server entries in one config file, one scoped to development and testing categories and another to writing and research, which is a clean way to give different agents different skill sets from a single directory.

Installing SkillPort and running a first validation

The README gives two install paths for the CLI. The uv route is listed first, and pip is offered as an alternative. Both target Python 3.10 or later, which the classifiers in pyproject.toml confirm.

uv tool install skillport
# or: pip install skillport

After installation the skillport executable is on your PATH. The next step is to add skills from a source. The README's example pulls the skills directory out of the anthropics/skills repository using the owner/repo shorthand plus a subdirectory.

skillport add anthropics/skills skills

If you keep skills somewhere other than the default, pass the directory flag before the subcommand. The README shows this with a .claude/skills path.

skillport --skills-dir .claude/skills add anthropics/skills skills

Validation is the command worth wiring into CI. The README documents a plain run and a JSON variant, and the example output shows a count of passing skills.

skillport validate
skillport validate ./skills
skillport validate --json

To connect an agent that can run shell commands, initialize the project and generate the skill table. The README's three-step flow is init, doc, then show at the moment the agent needs a skill.

skillport init
skillport doc
skillport show <id>

For MCP clients, install the separate server package and register it. The README's JSON config uses uvx with the SKILLPORT_SKILLS_DIR environment variable pointed at ~/.skillport/skills.

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

Codex and Claude Code users can skip the JSON and register the server through the agent's own command, which the README lists as codex mcp add skillport -- uvx skillport-mcp and claude mcp add skillport -- uvx skillport-mcp.

Rollback, indexing and the gaps in the documentation

The README documents update, which refreshes skills from their original sources, but it does not document rollback. If an upstream skill changes in a way that breaks your agent's behaviour, there is no described command to return to the previous revision. You are left with whatever the original source serves now, unless you keep your own copy. That is a real operational gap for anyone pinning skills the way they pin dependencies.

Indexing is the second soft spot. The pyproject.toml lists lancedb, tantivy and openai under the dev dependency group, and .env.example exposes SKILLPORT_DB_PATH with a default under ~/.skillport/indexes/default/skills.lancedb, plus SKILLPORT_SEARCH_LIMIT and SKILLPORT_SEARCH_THRESHOLD. So a search index exists and is configurable. What the README does not explain is when that index is built, whether add triggers it, or what happens when the index and the skills directory drift apart. The .env.example also sets SKILLPORT_EMBEDDING_PROVIDER to none by default, with openai as the other listed value, which suggests keyword search is the baseline and embeddings are opt-in. The README does not describe the quality difference between the two, and I would not assume the default is the better one for a large skill set.

A third constraint is the packaging split. The CLI package depends on skillport-core pinned to the same version, so the CLI and core move together. If you install the MCP server, you are managing a second package with its own version. The README's quick start does not explain how to keep the two in step.

When SkillPort is the wrong tool

SkillPort assumes your skills conform to the Agent Skills specification. If your prompts live in a proprietary format, a database, or a vendor's hosted skill store, validate will not help you and the add command has nothing to parse. The tool is a manager for files on disk, not a converter.

It is also a poor fit for a single-agent setup with a handful of skills. The CLI delivery mode requires the agent to read AGENTS.md and then issue a shell command to load instructions. That is an extra round trip per skill, and for three skills it costs more than pasting them into a system prompt. The README's own justification for search-first loading is the 50+ skill case.

Finally, the project is in beta. The pyproject.toml classifier says Development Status 4 - Beta, and the last push to the repository was on 2026-06-24. That is not a criticism of the design, but it does mean the command surface can still move between releases. The release history shows v1.1.0 in December 2025, v1.1.1 in January 2026, and v1.1.2 in June 2026, so the cadence is real but not fast. Anyone who needs a frozen interface should pin the version and read the changelog before upgrading.

How SkillPort differs from writing skills directly into each agent

The obvious alternative is to skip the tool and place SKILL.md files wherever each agent expects them, letting the agent's own discovery mechanism do the work. That approach has no extra dependency and no index to maintain. Its weakness is duplication: the same skill ends up copied into a Cursor directory, a Claude directory and a Copilot directory, and keeping them identical becomes a manual chore. SkillPort's answer is one directory with per-client filtering through SKILLPORT_ENABLED_CATEGORIES, so a single source serves several agents with different visible skill sets.

A second alternative is a general-purpose MCP server that exposes tools rather than skills. The distinction is what gets loaded. A tool server hands the model callable functions with schemas. SkillPort hands the model instructions, and the two MCP tools it exposes are search_skills and load_skill, which are about retrieving prose, not executing code. If your goal is to give an agent new capabilities, a tool server is the right shape. If your goal is to give it procedural knowledge, SkillPort is aimed at that. The README does list SKILLPORT_ALLOWED_COMMANDS with values like python, uv, node, cat, ls and grep in .env.example, so there is an execution-related setting, but the README does not document what it gates.

Licence, upgrade cost and what to check before adopting

SkillPort is MIT licensed, and pyproject.toml declares license = "MIT" with the matching classifier. For most teams that means permissive use, modification and redistribution with the licence text retained. That is a statement about the licence terms, not legal advice for your situation.

The upgrade cost is mostly the two-package split. The CLI pins skillport-core to an exact version, so upgrading the CLI pulls a matching core. The MCP server is a separate install, and the README does not describe a compatibility matrix between CLI and server versions. If you deploy both, test them together rather than upgrading one. The dev dependency group also pulls in lancedb, tantivy and openai, which are heavier than the three runtime dependencies (skillport-core, typer, rich) and matter only if you are building from source or running the test suite.

The configuration surface is small enough to review in one sitting. SKILLPORT_SKILLS_DIR, the three filter variables, SKILLPORT_CORE_SKILLS_MODE with values auto, explicit and none, and the search limit and threshold. The README does not explain what auto does differently from explicit, so if core skills matter to your setup, that is the first thing to test. Start with skillport validate --json on your current skills to see how many pass, then decide whether the MCP path or the CLI path fits your agents.

Editorial conclusion

Adopt SkillPort if you already keep skills as SKILL.md files and need one place to validate them in CI, install them from GitHub, and serve them to agents that lack native skill support. Skip it if your skills live in a proprietary format, or if you need a documented rollback path, because the README does not describe one. Before committing, run skillport validate --json against your existing skill directory and confirm every file passes the Agent Skills spec; that single command tells you how much migration work is left.

Frequently asked questions

Official sources

1. gotalab/skillport on GitHub
2. Issues
3. License: MIT
4. README
5. Releases