Skillporter

Skillporter

Skillporter, is the package manager for AI agent skills. It is a zero runtime dependency CLI and MCP server that installs, pins, audits, synchronizes and rolls back SKILL.md packages across 19 AI coding and autonomous agent harnesses, including Claude Code, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Hermes Agent, OpenHands and Goose.

uvx skillporter diagnose .                        # run the CLI without installing it (uv)pipx install skillporter                          # install the CLI globally (PEP 668 safe)npx @shanmukhdheekonda/skillporter diagnose .     # run the CLI without installing it (npm)

[Skillporter 3.0 CLI and multi-harness bridge fan-out]

Why skills need a package manager

Every AI agent harness reads skills from a different directory (.claude/skills/, .agents/skills/, .github/skills/, .windsurf/skills/, $HERMES_HOME/skills/, ~/.openclaw/skills/), and each one resolves them differently.

• A skill placed in .claude/skills/ is invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf.
• Hand-rolled symlinks break inside Docker builds, CI checkouts, git worktree, and Windows checkouts.
• Manual copies across directories silently drift out of sync across teammates, while naive removals from shared .agents/skills/ directories break other agents.
• An upstream skill can change under you between two sync runs, and an agent loads whatever it finds into its system context.

Skillporter treats skills the way a package manager treats dependencies: one manifest, one lockfile, one resolution step, and one install path that every harness can read.

What Skillporter does

Installation

# Option A: run immediately without a global install, via uvx or npxuvx skillporter diagnose .npx @shanmukhdheekonda/skillporter diagnose .
# Option B: install from PyPI with uv or pipx (PEP 668 safe)uv tool install skillporterpipx install skillporter
# Option C: standalone verified release installer (Linux and macOS)# Verifies SHA256SUMS.txt and the GitHub OIDC provenance attestation# (`gh attestation verify`) or an out-of-band pinned digest# (`SKILLPORTER_SHA256=<64-hex>`). Never falls back to mutable `main`.curl -fsSL https://github.com/Shanmukh-l33t/skillporter/releases/download/v3.0.1/install.sh -o install.shSKILLPORTER_VERSION=v3.0.1 sh install.sh

Python 3.9 or newer is required, and the standalone installer checks for it before unpacking anything. The package ships with no runtime dependencies, so there is nothing else to audit or pin.

Quick start (60 seconds)

# 1. Run the zero residue interactive demo (heals broken symlinks and SHA-256 drift in a temp dir)skillporter demo
# 2. Install a skill across harnesses (validates spec, runs static security scan, deduplicates .agents/skills)skillporter add anthropics/skills --skill pdf --harness all
# 3. Inspect and security scan skills (text, JSON, or SARIF 2.1.0 for GitHub Code Scanning)skillporter scan .skillporter scan . --format sarif > skillporter.sarif
# 4. Initialize manifest, synchronize transitive dependencies, and verify the reproducible lockfile in CIskillporter initskillporter syncskillporter lock --check
# 5. Diagnose reachability, audit provenance and override logs, or roll back to a verified snapshotskillporter diagnose .skillporter audit .skillporter rollback pdf

Supply chain security

Agent skills are untrusted supply chain packages: an agent loads SKILL.md directly into its system context and executes bundled scripts. Skillporter is built around that assumption rather than around convenience.

• Silent skill drift and unpinned upstream changes: skillporter.lock pins resolved Git commits, SHA-256 tree digests, and per-file hashes, blocking unexpected upstream mutations during sync.
• Known static supply chain hazards: inspects Python ASTs, JavaScript and TypeScript scripts, Markdown instructions, and bounded Base64, Hex and PowerShell payloads for embedded credentials, prompt injection override patterns, hidden Unicode and comments, shell pipe RCE, unsafe deserialization, symlink escapes, and multi-file staged execution before installation.
• Unsafe archive and filesystem operations: blocks Zip-Slip and Tar-Slip inputs (../, ..\, drive paths, Windows reserved device names, Unicode NFC/NFD collisions, symlinks, special files, decompression bombs) and stages installs transactionally with crash recovery journals.
• Unscoped agent filesystem writes: constrains skillporter mcp to the workspace root with default-deny write permissions (SKILLPORTER_MCP_ALLOW_WRITES=1 opt-in) and separates conflict overrides (--force) from security risk overrides (--allow-risky).

Important security note: static scanning (STATIC_SECURITY_ASSESSMENT) inspects files for known dangerous patterns and structural anomalies. A clean static scan is not proof that a skill is safe at runtime. Novel natural-language prompt injections or dynamically fetched payloads can still steer an agent at runtime.

How the scan is graded and where its limits are is documented in SECURITY.md.

Lockfile, sync and rollback

skillporter.lock is the reproducible record of what is installed:

• Pins resolved_commit, tree_hash, per-file SHA-256 file_hashes, pin_state (PINNED_COMMIT, PINNED_CONTENT or UNPINNED_MUTABLE), dependencies, and adapter version.
• skillporter sync honors locked Git commit SHAs even when upstream branches move, and rejects unexpected upstream content changes without --force.
• skillporter lock --check verifies the lockfile in CI and fails on mismatch.
• skillporter audit reports installed origins, lockfile drift, and .skillporter/audit.jsonl events, so any risk override is visible after the fact.

Rollback is transactional rather than a re-download. Replacements are staged in .skillporter/tmp/txn-* behind a write-ahead journal.json, prior versions are snapshotted into .skillporter/backups/, and skillporter rollback restores a skill together with its dependency graph from SHA-256 verified backups.

Harness support matrix (19 harnesses)

Skillporter distinguishes support status (NATIVE, COMPATIBLE, ADAPTED) from verification evidence (RUNTIME_VERIFIED, INTEGRATION_TESTED, FIXTURE_TESTED, DOCUMENTATION_VERIFIED). An adapter is never marked RUNTIME_VERIFIED unless it has been tested against a live harness runtime.

Each harness record ships its detection rules, path precedence, and vendor documentation reference. skillporter matrix prints the same matrix from the installed CLI, and skillporter detect reports which harnesses exist on the current machine.

MCP server

skillporter mcp runs a hardened JSON-RPC 2.0 Model Context Protocol server so an agent can query a workspace instead of shelling out. It exposes nine tools (diagnose, detect, scan, inspect, matrix, add, install, sync, remove), is read-only by default, refuses paths outside the workspace root, and requires an explicit opt-in before any write tool becomes available:

skillporter mcp                                   # read-onlyskillporter mcp --allow-writes                    # enable write toolsSKILLPORTER_MCP_ALLOW_WRITES=1 skillporter mcp    # same, via the environment

Client setup for Claude Code and other MCP clients is covered in the MCP guide.

CLI reference

Exit codes

• 0: clean, or the operation succeeded
• 1: policy or diagnostic finding (drift, broken symlink, spec error, security block, lockfile mismatch, cycle or conflict)
• 2: usage or runtime error (invalid argument, unknown harness, missing path)

Documentation

• Website: overview, interactive terminal demo, and live 19-harness matrix.
• Documentation home: the full guide set, from installation through lockfiles, scanning, and CI.
• Install: installation channels and provenance verification options.
• FAQ: frequently asked questions.
• Blog: engineering articles and release write-ups.

The same guides are versioned in the repository under docs/ if you prefer to read them on GitHub.

Contributing

Issues and pull requests are welcome. The short version:

• Open an issue before starting a large architectural change.
• New harness adapters must link the vendor documentation that proves the skill discovery path, and must not claim a verification level that has not been tested.
• The core library stays on the Python standard library, with zero runtime dependencies.

Full setup instructions, the required local quality gates, and the adapter checklist are in CONTRIBUTING.md. To report a vulnerability, follow SECURITY.md instead of opening a public issue.

License

MIT. See LICENSE.